NFC 인증 보고서: 칩 데이터 및 진위 확인

개요

NFC 인증 보고서는 전자여권, 전자 신분증 또는 기타 ICAO 9303 전자 문서 등의 NFC 칩에서 Didit이 읽고 검증한 내용을 담고 있습니다. 여기에는 칩의 인적 사항 데이터, 암호학적 무결성 검사(SOD 및 Data Group 해시), 발급 국가에서 사용한 문서 서명자 인증서(DSC) 요약 정보가 포함됩니다. 이 보고서는 사용자가 워크플로에서 NFC 단계를 완료한 후 생성됩니다. Didit은 사용자 기기에서 칩의 Data Group을 읽고, 발급 국가의 CSCA 인증서와 대조하여 문서 보안 객체(SOD) 서명을 검증하며, SOD가 서명한 값과 각 Data Group 해시를 대조하고, 문서의 인쇄면에서 OCR로 추출한 MRZ와 칩의 MRZ를 상호 대조합니다. 일본 마이넘버카드는 대신 JPKI를 통해 판독됩니다(chip_protocol: "jpki"). 해당 보고서에는 jpki 아래에 인증서, 서명, 폐기 및 명의인 데이터 검사가 포함되며, ICAO 필드는 null로 유지됩니다. 자세한 내용은 일본 마이넘버카드(JPKI)를 참고하세요. 각 보고서는 전체 세션 상태와 무관하게 NFC 단계만의 처리 결과를 반영하는 자체 status를 가집니다.

승인됨 — 칩을 성공적으로 읽었으며, 발생한 경고 중 해당 단계를 검토 또는 거부로 라우팅하도록 구성된 경고가 없습니다.
검토 중 — 구성된 작업이 검토인 경고가 하나 이상 발생했습니다(예: 미검증 칩에 대한 작업이 검토로 설정된 경우의 NFC_CHIP_NOT_VERIFIED 또는 NFC_TRUST_ANCHOR_MISSING, 기본 작업이 적용된 JPKI_REVOCATION_UNCHECKED).
거부됨 — 구성된 작업이 거부인 경고가 하나 이상 발생했습니다(예: 데이터 불일치 작업이 거부로 설정된 경우의 NFC_AND_OCR_DATA_NOT_SAME).
완료되지 않음 — 사용자가 NFC 단계를 완료하지 않았습니다. 칩 판독이 중단되었거나 기기가 NFC를 지원하지 않았습니다.
재제출 요청됨 — 검토자가 사용자에게 재제출을 요청했습니다. 이 보고서는 새로운 시도로 대체됩니다.

API 응답에서 표시되는 위치

NFC 보고서는 nfc_verifications[] 배열 내에 제공되며, 단일 nfc 객체가 아닌 항상 JSON 배열 형태로 전달됩니다. 워크플로에서 NFC를 두 번 이상 실행하는 경우(예: 스텝업 플로우) 여러 항목이 나타날 수 있으며, 각 항목은 고유한 node_id를 가집니다.

세션 결정 API — GET /v3/session/{sessionId}/decision/의 최상위 수준에서 nfc_verifications[]로 나타납니다. 세션 결정 조회를 참고하세요.
Webhook — status.updated payload에는 NFC 단계에서 데이터가 생성된 후 동일한 nfc_verifications[] 배열이 포함됩니다. Webhook을 참고하세요.
독립형 NFC — 직접 칩을 제출하는 방식에 대해서는 NFC 개요를 참고하세요.

워크플로에 생략되거나 우회된 NFC 단계가 포함된 경우, 결정 payload의 최상위 수준에 정확한 이유를 명시하는 nfc_skip_reason 필드도 함께 제공됩니다. 문서에 칩이 없음, 발급 국가의 인증서를 사용할 수 없음, 기기에 NFC 리더기가 없음, 네이티브 SDK 없이 인증이 실행됨(브라우저에서 NFC 접근 불가), MRZ에서 칩 액세스 키를 파생할 수 없음, 마이넘버카드를 JPKI를 통해 읽을 수 없음, 사용자가 건너뛰기를 선택함 등이 여기에 해당합니다. 해당 분류 체계에 속하지 않는 결과(가장 흔하게는 시도 중간에 중단한 사용자(보고서 상태 Not Finished) 또는 NFC가 아직 대기 중인 세션)의 경우 null로 유지됩니다. 정확한 값은 건너뛰기 사유를 참고하세요.

이전 문서에서는 단일 nfc 필드를 언급했습니다. 이 형태는 v3 결정 endpoint에 존재하지 않으며, V2 webhook으로 명시적으로 고정된 대상에만 나타나고 해당 대상에서도 chip_protocol 및 jpki를 전달합니다. 항상 response.nfc_verifications[0]을 읽고 배열을 순회하세요.

스키마

표준 필드별 스키마는 데이터 모델 레퍼런스 페이지에 있습니다. 아래 필드는 해당 표준 스키마를 그대로 반영합니다.

필드	유형	설명
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	NFC 단계 상태입니다(위의 의미 참조).
`node_id`	string \| null	이 보고서를 생성한 워크플로 그래프 노드입니다. 다단계 워크플로에서 두 개의 NFC 검사를 구분할 수 있게 해줍니다.
`is_nfc_skipped`	boolean	이 NFC 단계를 읽지 않고 명시적으로 건너뛴 경우 `true`입니다.
`skip_reason`	string \| null	단계를 건너뛴 이유입니다. `is_nfc_skipped`가 `true`일 때만 설정됩니다. 세션 수준의 `nfc_skip_reason`과 동일한 값이며, 건너뛰기 사유를 참조하십시오.
`chip_protocol`	`"icao"` \| `"jpki"`	칩을 읽은 방법입니다. `icao`: ICAO 9303 전자여권 또는 전자 신분증 칩입니다. `jpki`: 일본 마이넘버카드로, 결과는 `jpki` 아래에 위치합니다. 이 경우 아래의 ICAO 필드(`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`)는 `null`이 됩니다. 건너뛴 단계에서도 설정됩니다.
`jpki`	object \| null	마이넘버카드 조회를 통해 증명된 내용입니다. JPKI 필드를 참조하십시오. ICAO 칩, 건너뛴 단계, 카드를 읽지 않고 단계가 종료된 경우에는 `null`입니다.
`portrait_image`	string (signed URL) \| null	칩(DG2)에서 추출된 인물 사진입니다. 유효 기간이 짧은 서명된 링크이므로 즉시 다운로드해야 합니다. 최신 URL을 받으려면 결정을 다시 조회하십시오.
`signature_image`	string (signed URL) \| null	칩(DG7)에 포함된 소지자의 서명 이미지입니다(있는 경우). 동일하게 유효 기간이 짧은 서명된 링크로 제공됩니다.
`chip_data`	object \| null	칩에서 파싱한 인적 사항 데이터가 포함된 플랫 객체입니다. 성공적으로 읽은 후 항상 존재합니다: `dgs`(읽은 데이터 그룹 목록), `surname`, `name`, `country`, `nationality`, `birth_date`(`YYYY-MM-DD`), `expiry_date`(`YYYY-MM-DD`), `sex`(`M`/`F`), `document_type`(MRZ 문서 코드, 예: `P`), `document_number`, `optional_data`, MRZ 체크 디지트(`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type`(`TD1`/`TD2`/`TD3`). 칩에 DG11이 포함된 경우 `place_of_birth` 및 `address`가 추가됩니다(라틴 문자가 아닌 이름이 포함된 문서의 경우 `full_name` / `full_name_non_latin`도 추가됨). 그렇지 않은 경우 이러한 키는 null이 아니라 생략됩니다. NFC 단계를 건너뛴 경우 `null`입니다.
`authenticity`	object \| null	아래 설명된 ICAO 패시브 인증 결과입니다. JPKI 조회의 경우 `null`입니다.
`authenticity.sod_integrity`	boolean	SOD 서명이 유효한 발급 국가 CSCA로 연결되고 DSC가 해지되거나 만료되지 않은 경우 `true`입니다.
`authenticity.dg_integrity`	boolean	모든 데이터 그룹의 해시가 SOD가 서명한 값과 일치하는 경우 `true`입니다. `false` 값은 칩 데이터가 변조되었거나 부분적으로만 읽혔음을 의미합니다.
`certificate_summary`	object \| null	이 칩에 서명한 DSC의 요약 정보입니다: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after`(`YYYY-MM-DD HH:MM:SS` 형식의 타임스탬프), 개별 검사 결과가 포함된 `validation` 객체(`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing`은 DSC의 발급 CSCA 트러스트 앵커를 사용할 수 없는 경우 `true`입니다. SOD를 로드할 수 없거나 단계를 건너뛴 경우 `null`입니다.
`warnings[]`	array	모듈 수준의 경고 배열로, 각각 `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`를 포함합니다. NFC 경고를 참조하십시오.

상태 값

상태	의미	후속 영향
`Approved`	칩을 읽었으며 Review 또는 Decline 작업이 트리거된 경고가 없습니다. 경고가 발생했으나 구성된 작업이 “작업 없음”인 경우도 포함됩니다.	성공한 NFC 검사로 간주되며, 이것만으로 세션이 검토 중으로 전환되지 않습니다.
`In Review`	구성된 작업이 Review인 경고가 발생했습니다(설정에 따라 `SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` 또는 `JPKI_*` 경고 중 하나).	검토자가 조치를 취할 때까지 세션도 `In Review`로 이동합니다.
`Declined`	구성된 작업이 Decline인 경고가 발생했습니다.	워크플로를 충족하는 승인된 다른 분기가 없는 한 세션이 거부됩니다.
`Not Finished`	사용자가 NFC 단계를 중단했거나, 기기에서 NFC를 지원하지 않거나, 칩 읽기가 완료되지 않았습니다.	NFC 분기에서 결과를 생성하지 못했습니다. 워크플로 대체 수단을 확인하십시오.
`Resub Requested`	검토자가 이 단계의 재제출을 요청했습니다.	사용자가 재시도하면 새로운 시도가 이 보고서를 대체합니다.

두 가지 인증서 경고(DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED)는 정보성 경고입니다. warnings[]에 나타나지만 그 자체로 NFC status를 변경하지는 않습니다. 전체 동작 매트릭스는 NFC 경고를 참조하십시오.

예시

승인됨 — 칩을 읽었으며 암호학적으로 유효함

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

거부됨 — OCR / 칩 불일치

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": [
        {
          "feature": "NFC",
          "risk": "NFC_AND_OCR_DATA_NOT_SAME",
          "additional_data": {
            "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
            "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
          },
          "log_type": "error",
          "short_description": "NFC and OCR data not same",
          "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
          "node_id": "nfc_primary"
        }
      ]
    }
  ]
}

일본 마이넘버카드 (JPKI)

일본 마이넘버카드는 네이티브 SDK에서 JPKI를 통해 읽습니다. 사용자가 카드 PIN을 입력하면 카드가 일회용 챌린지에 서명합니다(작동 방식 참조). 해당 보고서에는 chip_protocol: "jpki"가 포함되며 jpki 아래에 증거가 제공됩니다. 카드에 ICAO 데이터가 포함되어 있지 않으므로 portrait_image, signature_image, chip_data, authenticity, certificate_summary는 null입니다.

JPKI를 통한 마이넘버카드 읽기는 프로덕션 환경에서 아직 활성화되지 않았습니다. 활성화되기 전까지 마이넘버카드는 JPKI_UNAVAILABLE 건너뛰기 사유와 함께 NFC 단계를 건너뜁니다.

JPKI 필드

필드	유형	설명
`jpki.certificate_types`	array of `"user_authentication"` \| `"signature"`	읽은 카드 인증서입니다. `user_authentication`(4자리 PIN)은 항상 읽으며, `signature`(서명용 PIN)는 NFC 노드의 `jpki_request_attributes` 설정이 켜져 있을 때(기본값) 읽습니다.
`jpki.chain_valid`	boolean	모든 인증서가 해당 유형의 JPKI 인증 기관(CA)으로 체인 연결되고, 유효 기간 내에 있으며, 해당 유형의 마이넘버카드 인증서인 경우 `true`입니다.
`jpki.signature_valid`	boolean	일회용 챌린지에 대해 카드가 생성한 모든 서명이 검증되면 `true`입니다. 카드는 PIN이 입력된 후에만 서명하므로, 사용자가 카드를 소지하고 PIN을 알고 있음을 증명합니다.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: 모든 인증서가 해지되지 않았음이 확인되었습니다. `revoked`: 예를 들어 분실 신고 등의 사유로 인증서가 해지되었습니다. `unchecked`: 해지 여부 응답을 확인할 수 없어 해지된 카드일 가능성을 배제할 수 없습니다. 절대로 `good`으로 처리되지 않습니다. 해지 여부는 체인과 서명이 모두 유효한 경우에만 확인합니다.
`jpki.ca_generation`	string \| null	인증서를 발급한 JPKI 인증 기관의 세대(예: `"2023"`)입니다. 인증서가 연결되는 인증 기관이 없으면 `null`입니다.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	읽은 인증서 중 가장 빠른 만료일입니다.
`jpki.certificates[]`	array	읽은 인증서당 하나의 항목: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after`, `failure`. `failure`는 체인이 유효할 때 `null`이며, 그렇지 않으면 `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy`(해당 유형의 마이넘버카드 인증서가 아님) 또는 `key_usage` 중 하나입니다.
`jpki.attributes`	object \| null	체인이 유효한 경우 서명용 인증서에서 가져온 소지자의 데이터: `full_name`(등록된 성명, 대개 일본어 문자 체계), `date_of_birth`(`YYYY-MM-DD`), `gender`(`M`, `F` 또는 `null`), `address`, 그리고 표준 문자 집합 외부에 있어 대체 문자로 치환된 문자를 표시하는 `name_substitute_characters` / `address_substitute_characters`(치환된 문자가 없으면 `null`). 서명용 인증서가 요청되지 않았거나 체인이 유효하지 않은 경우 `null`입니다.
`jpki.attributes_match_ocr`	boolean \| null	속성이 동일한 카드의 사진에서 읽은 데이터와 일치하면 `true`, 일치하지 않는 속성이 있으면 `false`(`JPKI_AND_OCR_DATA_NOT_SAME`), `attributes`가 `null`인 경우를 포함하여 비교할 수 없는 경우 `null`입니다.
`jpki.mismatched_attributes`	문자열 배열	사진 데이터와 일치하지 않는 속성(`full_name`, `date_of_birth`, `gender`, `address`) 목록이며, 해당 속성의 값은 포함되지 않습니다.

보고서에는 인증서 자체, 일련번호, 서명, 또는 NFC 단계에서 전혀 읽지 않는 카드의 12자리 개인번호(마이넘버)가 절대 포함되지 않습니다.

예시: 마이넘버카드 읽기

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": null,
      "signature_image": null,
      "chip_data": null,
      "is_nfc_skipped": false,
      "skip_reason": null,
      "chip_protocol": "jpki",
      "jpki": {
        "certificate_types": ["user_authentication", "signature"],
        "chain_valid": true,
        "signature_valid": true,
        "revocation_status": "good",
        "ca_generation": "2023",
        "certificate_expires_at": "2029-05-15T14:59:59Z",
        "certificates": [
          {
            "type": "user_authentication",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          },
          {
            "type": "signature",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          }
        ],
        "attributes": {
          "full_name": "山田 太郎",
          "date_of_birth": "1990-05-15",
          "gender": "M",
          "address": "東京都千代田区千代田1番1号",
          "name_substitute_characters": null,
          "address_substitute_characters": null
        },
        "attributes_match_ocr": true,
        "mismatched_attributes": []
      },
      "authenticity": null,
      "certificate_summary": null,
      "warnings": []
    }
  ]
}

읽기 작업에서 해지 확인을 사용할 수 없는 경우, 기본 설정에서 동일한 보고서에 revocation_status: "unchecked", JPKI_REVOCATION_UNCHECKED 경고 및 status: "In Review"가 표시됩니다. NFC 경고를 참조하십시오.

보안 참고 사항

NFC 칩 데이터는 발급 기관에 의해 서명되므로, sod_integrity: true 및 dg_integrity: true가 포함된 승인된 보고서는 Didit이 생성할 수 있는 가장 강력한 신원 증거입니다. 서명된 이미지 URL(portrait_image, signature_image)은 유효 기간이 짧으므로 즉시 다운로드하고 공개적으로 캐시하지 마십시오. 새로운 링크가 필요한 경우 결정을 다시 요청하십시오.

인증

인증

모니터링

플랫폼

NFC 인증 보고서: 칩 데이터 및 진위 확인

개요

API 응답에서 표시되는 위치

스키마

상태 값

예시

승인됨 — 칩을 읽었으며 암호학적으로 유효함

거부됨 — OCR / 칩 불일치

일본 마이넘버카드 (JPKI)

JPKI 필드

예시: 마이넘버카드 읽기

보안 참고 사항

관련 항목

​개요

​API 응답에서 표시되는 위치

​스키마

​상태 값

​예시

​승인됨 — 칩을 읽었으며 암호학적으로 유효함

​거부됨 — OCR / 칩 불일치

​일본 마이넘버카드 (JPKI)

​JPKI 필드

​예시: 마이넘버카드 읽기

​보안 참고 사항

​관련 항목

개요

API 응답에서 표시되는 위치

스키마

상태 값

예시

승인됨 — 칩을 읽었으며 암호학적으로 유효함

거부됨 — OCR / 칩 불일치

일본 마이넘버카드 (JPKI)

JPKI 필드

예시: 마이넘버카드 읽기

보안 참고 사항

관련 항목