> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # NFC 인증 경고 및 오류 코드 > 칩 판독 건너뜀/미검증, OCR/칩 불일치, 만료된 인증서 등 Didit NFC 모듈의 모든 경고에 대한 원인, 심각도 및 해결 방법을 확인하세요. ## 개요 NFC 보고서의 경고는 Didit이 칩을 읽고 검증하는 동안 관찰한 모든 상태를 표시합니다. 경고는 `nfc_verifications[]`의 각 항목에 있는 `warnings[]` 배열에 포함되며([NFC 보고서](https://docs.didit.me/ko/core-technology/nfc-verification/report-nfc-verification.md) 참조), `feature`는 `"NFC"`로 설정됩니다. 각 항목은 공통 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태인 `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`를 따릅니다. 모든 경고에는 세 가지 계층이 있습니다. 1. **`risk` 코드** — 코드에서 일치 여부를 확인할 수 있는 안정적인 식별자(아래에 나열된 코드). 2. **`log_type`** — `information`, `warning`, `error` 중 하나입니다. 워크플로에서 해당 위험에 대해 구성한 작업에서 파생됩니다. **작업 없음** → `information`, **검토** → `warning`, **거부** → `error`. 3. **결정 영향** — 동일하게 구성된 작업은 NFC 보고서의 `status`도 제어합니다. 검토 작업은 `In Review`로, 거부 작업은 `Declined`로 변경합니다. 이러한 방식으로 구성 가능한 NFC 위험은 4가지(`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME`)이며, 여기에 각각 고유한 설정을 가진 5가지 [일본 마이넘버카드](#일본-마이넘버카드-jpki) 위험이 추가됩니다. 두 가지 인증서 위험(`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`)은 **정보 제공 전용**입니다. 항상 `log_type: "information"`을 가지며 자체적으로 NFC 상태를 변경하지 않습니다. NFC 모듈이 생성하는 전체 위험 코드 목록은 아래와 같습니다. 다른 NFC 위험 코드는 존재하지 않습니다. ## 생성되는 경고 | `risk` | 원인 | 심각도 (`log_type`) | 상태에 영향을 미치나요? | 조치 방법 | | - | - | - | - | - | | `SKIPPED_NFC_VALIDATION` | 칩 인식이 건너뛰어졌습니다. 워크플로에서 건너뛰기를 허용(`allow_nfc_skip`)하여 사용자가 건너뛰기를 탭했거나, 클라이언트가 NFC를 읽을 수 없어 건너뛰었습니다. 정확한 이유는 `additional_data.skip_reason`에 기록되며([건너뛰기 이유](#건너뛰기-이유) 참조) 경고의 `long_description`을 결정합니다. | **NFC 건너뛰기 작업** 설정(`skip_nfc_action`)을 따름: information / warning / error. | 구성 가능 — No action, Review 또는 Decline. | 정책상 NFC가 필수인 경우 건너뛰기 작업을 Decline으로 설정하거나(또는 건너뛰기를 완전히 비활성화) 사용자에게 NFC 지원 기기에서 재시도하도록 안내하십시오. 그렇지 않다면 No action으로 유지하여 OCR 전용 인증으로 대체하십시오. | | `NFC_CHIP_NOT_VERIFIED` | 칩을 읽었으나 명시적으로 확인된 신뢰 앵커 부재 이외의 이유로 암호학적 검증에 실패했습니다. 데이터 그룹 해시, SOD 서명 또는 기타 수동 인증 검사가 확인되지 않았습니다. | **검증되지 않은 칩 작업** 설정(`unverified_chip_action`)을 따름. | 구성 가능 — No action, Review 또는 Decline. | 유효하지 않거나 변조되었을 가능성이 있는 칩으로 처리하십시오. `authenticity` 및 `certificate_summary.validation`을 검토하여 어떤 검사가 실패했는지 확인하십시오. | | `NFC_TRUST_ANCHOR_MISSING` | 칩의 Document Signer Certificate(DSC)가 Didit의 신뢰 저장소에 없는 국가 서명 인증 기관(CSCA) 세대에 속합니다(`certificate_summary.validation.csca_missing`이 `true`). 따라서 Didit이 SOD의 신뢰 체인을 설정할 수 없습니다. | **검증되지 않은 칩 작업** 설정(`unverified_chip_action`)을 따름. | 구성 가능 — No action, Review 또는 Decline. | 이는 신뢰 저장소의 지원 범위 공백이며 칩이 변조되었다는 증거는 아닙니다. 대체 검사를 통해 문서를 검토하고, 누락된 CSCA를 조사할 수 있도록 발급 국가와 함께 Didit 지원팀에 문의하십시오. | | `NFC_AND_OCR_DATA_NOT_SAME` | 칩에서 읽은 MRZ가 문서의 시각적 영역에서 OCR로 추출한 MRZ와 일치하지 않습니다(`<` 채움 문자를 무시하고 정규화한 후 비교). 변조의 강력한 징후입니다. | **데이터 불일치 작업** 설정(`inconsistent_data_action`)을 따름 — 신분증 인증 데이터 일관성 검사를 제어하는 설정과 동일합니다. | 구성 가능 — No action, Review 또는 Decline. | 달리 입증되지 않는 한 변조로 처리하십시오. 일반적으로 Decline으로 설정합니다. 수동 비교를 위해 `additional_data` payload에 OCR MRZ 행(`ocr_mrz`, 배열)과 칩 MRZ(`nfc_mrz`, 단일 문자열)가 포함됩니다. | | `DSC_CERTIFICATE_REVOKED` | 이 칩에 서명한 Document Signer Certificate가 발급 국가의 인증서 폐기 목록(CRL)에 나타납니다. | 항상 `information`. | 아니요 — 이 항목 자체만으로는 NFC 상태를 변경하지 않습니다. | 서명 키가 손상되었을 수 있다는 강력한 징후입니다. 필요한 경우 자체 로직을 통해 이러한 세션을 수동 검토로 전달하십시오. 칩은 대개 구성 가능한 `NFC_CHIP_NOT_VERIFIED`도 함께 트리거합니다. | | `DSC_CERTIFICATE_EXPIRED` | DSC의 유효 기간이 지났습니다(`certificate_summary.validation.dsc_expired`가 `true`). | 항상 `information`. | 아니요 — 이 항목 자체만으로는 NFC 상태를 변경하지 않습니다. | 오래된 문서에서 흔히 발생합니다. 폐기와 마찬가지로 만료된 DSC 또한 전체 SOD 검증에 실패하므로 `NFC_CHIP_NOT_VERIFIED`가 함께 트리거되어 구성된 작업을 수행합니다. | | `JPKI_CERTIFICATE_INVALID` | 일본 마이넘버카드: 카드에서 읽은 인증서가 해당 유형의 JPKI 인증 기관으로 연결되지 않거나 유효 기간이 지났거나 해당 유형의 마이넘버카드 인증서가 아닙니다. `additional_data.certificate_types`에 실패한 인증서가 나열되며, `jpki.certificates[].failure`에 이유가 명시됩니다. | `jpki_certificate_invalid_action`을 따름 (기본값 Decline). | 구성 가능: No action, Review 또는 Decline. | 유효하지 않거나 변조된 카드로 처리하십시오. 만료된 카드 인증서도 여기에 해당하며, 소지자가 관할 지자체에서 갱신해야 합니다. | | `JPKI_SIGNATURE_INVALID` | 일본 마이넘버카드: 일회용 챌린지에 대한 카드의 서명이 인증서와 대조하여 검증되지 않아 카드를 소지하고 PIN을 알고 있다는 사실이 입증되지 않았습니다. 카드를 전혀 읽지 않고 NFC 단계가 종료된 경우에도 발생합니다(이 경우 `additional_data.certificate_types`는 비어 있음). | `jpki_signature_invalid_action`을 따름 (기본값 Decline). | 구성 가능: No action, Review 또는 Decline. | 카드 인식을 유효한 증명으로 수락하지 마십시오. 사용자에게 실물 카드로 재시도하도록 요청하십시오. | | `JPKI_CERTIFICATE_REVOKED` | 일본 마이넘버카드: 분실 신고가 접수되었거나 소지자의 등록 정보가 변경되는 등의 이유로 폐기 확인 결과 인증서가 폐기된 것으로 보고되었습니다(`jpki.revocation_status`가 `revoked`). | `jpki_certificate_revoked_action`을 따름 (기본값 Decline). | 구성 가능: No action, Review 또는 Decline. | 카드를 수락하지 마십시오. | | `JPKI_REVOCATION_UNCHECKED` | 일본 마이넘버카드: 인증서와 서명은 검증되었으나 폐기 확인 응답을 확인할 수 없어(`jpki.revocation_status`가 `unchecked`) 카드의 폐기 가능성을 배제할 수 없습니다. 체인이나 서명이 이미 실패한 경우에는 발생하지 않습니다. | `jpki_revocation_unchecked_action`을 따름 (기본값 Review). | 구성 가능: No action, Review 또는 Decline. | 폐기 응답이 없는 검증된 카드를 어느 정도까지 허용할지 결정하고 그에 따라 작업을 설정하십시오. | | `JPKI_AND_OCR_DATA_NOT_SAME` | 일본 마이넘버카드: 서명 인증서의 성명, 생년월일, 성별 또는 주소가 동일한 카드의 사진에서 읽은 데이터와 다릅니다. `additional_data.fields`는 값이 아닌 일치하지 않는 속성 이름만 명시합니다. | `jpki_inconsistent_data_action`을 따름 (기본값 Review). | 구성 가능: No action, Review 또는 Decline. | 결정하기 전에 `jpki.attributes`를 신분증 인증 데이터와 비교하십시오. 인증서에 대체 문자가 저장되어 있기 때문에 흔하지 않은 문자가 포함된 성명은 다르게 나타날 수 있습니다(`jpki.attributes.name_substitute_characters`). | > [!NOTE] > > `SKIPPED_NFC_VALIDATION`은 `NFC_CHIP_NOT_VERIFIED` 및 `NFC_TRUST_ANCHOR_MISSING`과 상호 배타적입니다. 칩 검증 경고는 칩 읽기를 건너뛰지 않은 경우에만 평가됩니다. 두 가지 칩 검증 경고 또한 상호 배타적입니다. ## 정확한 설명 문자열 API는 각 risk에 대해 다음과 같은 정확한 `short_description` 및 `long_description` 문자열을 반환합니다. | `risk` | `short_description` | `long_description` | | - | - | - | | `SKIPPED_NFC_VALIDATION` | Skipped NFC Validation | 사유별 상이 — [건너뛰기 사유](#건너뛰기-이유)를 참조하십시오. 건너뛰기 사유가 존재하기 전에 기록된 기존 세션에서는 "The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support."로 대체됩니다. | | `NFC_CHIP_NOT_VERIFIED` | NFC chip not verified | Near Field Communication(NFC) 칩이 명시적으로 식별된 트러스트 앵커 누락 이외의 사유로 패시브 인증에 실패했습니다. 칩 데이터 또는 서명이 유효하지 않거나 변조되었을 수 있습니다. | | `NFC_TRUST_ANCHOR_MISSING` | NFC trust anchor unavailable | 발급 국가의 국가 서명 인증 기관(CSCA) 트러스트 앵커를 사용할 수 없어 Near Field Communication(NFC) 칩을 검증할 수 없습니다. 이는 트러스트 저장소 지원 범위의 공백이며, 칩이 변조되었다는 증거는 아닙니다. | | `NFC_AND_OCR_DATA_NOT_SAME` | NFC and OCR data not same | Near Field Communication(NFC) 칩 데이터와 OCR 데이터가 일치하지 않으며, 이는 잠재적인 문서 변조 또는 데이터 불일치를 나타냅니다. | | `DSC_CERTIFICATE_REVOKED` | Document Signer Certificate revoked | 전자여권 칩 데이터 서명에 사용된 문서 서명자 인증서(DSC)가 발급 국가의 인증서 폐기 목록(CRL)에 의해 폐기되었으며, 이는 서명 키가 유출되었을 수 있음을 나타냅니다. | | `DSC_CERTIFICATE_EXPIRED` | Document Signer Certificate expired | 전자여권 칩 데이터 서명에 사용된 문서 서명자 인증서(DSC)가 만료되었으며, 인증서의 유효 기간이 지났음을 의미합니다. | | `JPKI_CERTIFICATE_INVALID` | My Number Card certificate not valid | 마이넘버카드 칩에서 읽은 인증서가 유효하지 않습니다. 일본 공개 키 인프라(JPKI) 인증 기관으로 연결되지 않거나, 유효 기간을 벗어났거나, 요청된 유형의 마이넘버카드 인증서가 아닙니다. | | `JPKI_SIGNATURE_INVALID` | My Number Card signature not valid | 일회성 인증 챌린지에 대해 마이넘버카드가 생성한 서명이 카드의 인증서로 검증되지 않으므로, 카드 소지와 PIN을 알고 있음이 증명되지 않았습니다. | | `JPKI_CERTIFICATE_REVOKED` | My Number Card certificate revoked | 폐기 확인 결과 마이넘버카드에서 읽은 인증서가 폐기된 것으로 보고되었습니다. 예를 들어 분실 신고가 접수되었거나 소지자의 등록 정보가 변경되었기 때문일 수 있습니다. | | `JPKI_REVOCATION_UNCHECKED` | My Number Card revocation status not checked | 마이넘버카드의 인증서와 서명은 검증되었으나 폐기 상태를 확인할 수 없어 폐기된 카드일 가능성을 배제할 수 없습니다. | | `JPKI_AND_OCR_DATA_NOT_SAME` | My Number Card chip and OCR data not same | 마이넘버카드의 서명용 인증서에 포함된 성명, 생년월일, 성별 또는 주소가 카드 이미지(OCR)에서 읽은 데이터와 일치하지 않으며, 이는 대체 또는 데이터 불일치 가능성을 나타냅니다. | ## 건너뛰기 이유 `SKIPPED_NFC_VALIDATION` 경고에는 NFC가 실행되지 않은 구체적인 이유를 나타내는 7가지 고정 코드 중 하나인 `additional_data.skip_reason`이 포함됩니다(건너뛰기 이유가 도입되기 전에 기록된 세션의 경우 `additional_data`가 `null`일 수 있으므로 이전 결정을 처리할 때 해당 필드를 선택 항목으로 취급하세요). 동일한 분류 체계가 세션 수준의 결정 payload에서 `nfc_skip_reason`으로도 나타나며, 여기에는 NFC를 전혀 실행할 수 없어(칩이 없는 문서, 웹 연동) NFC 보고서나 경고가 존재하지 않는 세션도 포함됩니다. | `skip_reason` | 의미 | `long_description` | | - | - | - | | `USER_SKIPPED` | 호환되는 기기에서 NFC가 제공되었으나 사용자가 건너뛰기를 선택했습니다. | 호환되는 기기에서 NFC 칩 읽기 단계가 제공되었으나 사용자가 건너뛰기를 선택했습니다(워크플로 설정에서 건너뛰기가 허용됨). | | `DOCUMENT_WITHOUT_CHIP` | 문서 디자인상 읽기 가능한 NFC 칩이 없습니다(ICAO 9303 전자 문서가 아님). | 해당 문서에 읽기 가능한 NFC 칩이 없어 NFC 인증을 수행할 수 없습니다. ICAO 9303 전자 문서가 아닙니다. | | `CHIP_CERTIFICATE_UNAVAILABLE` | 칩은 존재하지만 해당 문서의 발급 기간에 적용되는 발급 국가 서명 인증서(CSCA)가 없어 서명을 검증할 수 없습니다. | 해당 문서의 발급 기간에 적용되는 발급 국가 서명 인증서(CSCA)를 사용할 수 없어 칩의 서명을 검증할 수 없으므로 NFC 인증을 수행할 수 없습니다. | | `DEVICE_WITHOUT_NFC` | 네이티브 SDK에서 스마트폰에 사용할 수 있는 NFC 리더가 없다고 보고했습니다. | 사용자의 기기에 사용 가능한 NFC 리더가 없다고 보고되어 NFC 인증을 수행할 수 없습니다. | | `INTEGRATION_WITHOUT_NFC_ACCESS` | 네이티브 SDK 없이(예: 웹 브라우저에서) 인증이 실행되었으며, 스마트폰의 NFC 리더에 접근할 수 없습니다. | 네이티브 모바일 SDK를 통해 인증이 실행되지 않아 스마트폰의 NFC 리더에 접근할 수 없었으므로 NFC 인증을 수행할 수 없습니다(웹 브라우저는 NFC 칩을 읽을 수 없음). | | `MRZ_KEY_UNAVAILABLE` | 문서의 MRZ에서 칩 접근 키(BAC/PACE 시드)를 도출할 수 없습니다. | 문서의 기계 판독 영역(MRZ)에서 칩 접근 키를 도출할 수 없어 NFC 인증을 수행할 수 없습니다. | | `JPKI_UNAVAILABLE` | 해당 문서는 JPKI를 통해 칩을 읽는 일본 마이넘버카드이나, 본 인증에서는 JPKI를 사용할 수 없었습니다. 기능이 활성화되지 않았거나 앱의 네이티브 SDK 릴리스가 마이넘버카드를 읽을 수 없습니다. 브라우저에서 인증된 마이넘버카드는 다른 칩과 마찬가지로 `INTEGRATION_WITHOUT_NFC_ACCESS`를 받고, NFC가 없는 스마트폰에서는 `DEVICE_WITHOUT_NFC`를 받습니다. | 해당 마이넘버카드는 JPKI를 통해 읽지만, 본 인증에서는 JPKI를 사용할 수 없어 NFC 인증을 수행할 수 없었습니다. 기능이 활성화되지 않았거나 앱의 SDK가 마이넘버카드를 읽을 수 없습니다. | > [!NOTE] > > NFC 보고서 및 해당 `SKIPPED_NFC_VALIDATION` 경고는 클라이언트가 NFC 단계에 도달하여 명시적으로 건너뛴 경우에만 존재합니다(일반적으로 `USER_SKIPPED`이거나 스캔 시점에 리더를 사용할 수 없는 것으로 확인된 경우 `DEVICE_WITHOUT_NFC`). NFC 단계가 사용자에게 아예 제공되기 전에 우회된 경우(칩이 없는 문서, 인증서 누락, 보고된 NFC 기능 없음, 읽을 수 없는 MRZ 키, JPKI 사용 불가)에는 보고서나 경고가 생성되지 않으며, 세션 상태에 영향을 주지 않고 세션 수준의 `nfc_skip_reason` 필드에만 이유가 표시됩니다. ## 설정 세 가지 워크플로 설정을 통해 NFC 경고가 라우팅되는 방식을 제어합니다. 각각 **조치 없음**, **검토** 또는 **거부**로 설정할 수 있습니다. 1. **NFC 건너뛰기 작업** (`skip_nfc_action`) — `SKIPPED_NFC_VALIDATION`에 적용됩니다. `allow_nfc_skip`이 활성화된 경우에만 사용자에게 건너뛰기 옵션이 제공됩니다. 2. **미검증 칩 작업** (`unverified_chip_action`) — `NFC_CHIP_NOT_VERIFIED` 및 `NFC_TRUST_ANCHOR_MISSING` 모두에 적용되므로, 위험 코드를 통해 인증 실패 이유를 설명하면서도 세션 상태 동작은 동일하게 유지됩니다. 3. **데이터 불일치 작업** (`inconsistent_data_action`) — `NFC_AND_OCR_DATA_NOT_SAME`에 적용됩니다. 신분증 인증에서 사용되는 데이터 불일치 설정과 동일합니다. 두 가지 `DSC_CERTIFICATE_*` 위험에는 작업 설정이 없으며 항상 정보 제공용입니다. 일본 마이넘버카드 위험에는 다음 섹션에 나열된 다섯 가지 추가 설정이 있습니다. ## 일본 마이넘버카드 (JPKI) 일본 마이넘버카드는 ICAO 9303 대신 JPKI를 통해 읽히므로(`chip_protocol: "jpki"`), 위의 ICAO 위험은 절대 발생하지 않습니다. 대신 마이넘버카드 판독 시 다음 다섯 가지 위험이 발생하며, 각 위험은 NFC 노드에서 고유한 설정을 갖습니다. | 설정 | 위험 | 기본값 | | - | - | - | | `jpki_certificate_invalid_action` | `JPKI_CERTIFICATE_INVALID` | 거부 | | `jpki_signature_invalid_action` | `JPKI_SIGNATURE_INVALID` | 거부 | | `jpki_certificate_revoked_action` | `JPKI_CERTIFICATE_REVOKED` | 거부 | | `jpki_revocation_unchecked_action` | `JPKI_REVOCATION_UNCHECKED` | 검토 | | `jpki_inconsistent_data_action` | `JPKI_AND_OCR_DATA_NOT_SAME` | 검토 | 건너뛴 마이넘버카드 판독은 다른 칩과 마찬가지로 `SKIPPED_NFC_VALIDATION`을 발생시키고 `skip_nfc_action`을 따릅니다. 판독 작동 방식에 대해서는 [일본 마이넘버카드 (JPKI)](https://docs.didit.me/ko/core-technology/nfc-verification/overview.md#일본-마이넘버카드-jpki)를 참조하세요. > [!WARNING] > > JPKI를 통한 마이넘버카드 판독은 프로덕션 환경에서 아직 활성화되지 않았습니다. 활성화되기 전까지 마이넘버카드는 건너뛰기 이유 `JPKI_UNAVAILABLE`과 함께 NFC 단계를 건너뛰며 이러한 위험은 발생하지 않습니다. ## 예시 ### 검토 중 — 칩을 확인할 수 없음 ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_CHIP_NOT_VERIFIED", "additional_data": null, "log_type": "warning", "short_description": "NFC chip not verified", "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.", "node_id": "nfc_primary" }, { "feature": "NFC", "risk": "DSC_CERTIFICATE_EXPIRED", "additional_data": null, "log_type": "information", "short_description": "Document Signer Certificate expired", "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.", "node_id": "nfc_primary" } ] } ``` 여기서 미인증 칩에 대한 작업이 Review로 설정되어 있어 `NFC_CHIP_NOT_VERIFIED`에 `log_type: "warning"`이 전달되고 NFC 보고서 상태는 `In Review`가 됩니다. 만료된 DSC 항목은 순수한 정보 제공용입니다. ### 거부됨 — 칩과 OCR 불일치 ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_AND_OCR_DATA_NOT_SAME", "additional_data": { "ocr_mrz": ["P