NFC認証レポート：ICチップデータと真正性の確認

概要

NFC認証レポートは、Diditが書類のNFCチップ(ePassport、電子IDカード、またはその他のICAO 9303準拠の電子書類)から読み取り、検証した内容を記録したものです。チップに格納された身元情報、暗号学的な完全性チェック(SODおよびData Groupのハッシュ)、発行国が使用するDocument Signer Certificate(DSC)の概要が含まれます。このレポートは、ユーザーがワークフロー内のNFCステップを完了した後に生成されます。Diditはユーザーのデバイス上でチップのData Groupを読み取り、Document Security Object(SOD)の署名を発行国のCSCA証明書で検証し、各Data GroupのハッシュをSODが署名した値と照合したうえで、チップのMRZを書類の表面からOCRで読み取ったMRZと突き合わせます。マイナンバーカードは代わりにJPKIを通じて読み取られます(chip_protocol: "jpki")。そのレポートでは、証明書、署名、失効、保有者データのチェックがjpkiの下に格納され、ICAOのフィールドはnullのままです。マイナンバーカード(JPKI)を参照してください。各レポートは、セッション全体のステータスとは独立した独自のstatusを持ち、NFCステップ単体がどのように判定されたかを示します。

Approved: チップが読み取られ、発生した警告のうち、ステップをレビューまたは却下に振り分けるよう設定されたものが1つもない状態です。
In Review: 設定されたアクションがReviewである警告が少なくとも1つ発生した状態です(例: 未検証チップのアクションがレビューに設定されている場合のNFC_CHIP_NOT_VERIFIEDやNFC_TRUST_ANCHOR_MISSING、またはデフォルトのアクションのままのJPKI_REVOCATION_UNCHECKED)。
却下: 設定されたアクションが却下である警告が少なくとも1つ発生した状態です(例: データ不一致のアクションが却下に設定されている場合のNFC_AND_OCR_DATA_NOT_SAME)。
Not Finished: ユーザーがNFCステップを完了しなかった状態です。チップの読み取りが放棄されたか、デバイスがNFCに対応していませんでした。
Resub Requested: レビュアーがユーザーに再提出を求めた状態です。このレポートは新しい試行によって置き換えられます。

APIレスポンス内での表示箇所

NFCレポートはnfc_verifications[]配列の中で返されます。これは常にJSON配列であり、単数形のnfcオブジェクトになることはありません。ワークフローがNFCを複数回実行する場合(例: ステップアップフロー)は複数のエントリが含まれ、各エントリはそれぞれ独自のnode_idを持ちます。

セッション判定API: GET /v3/session/{sessionId}/decision/のトップレベルにnfc_verifications[]として含まれます。セッション判定の取得を参照してください。
Webhook: NFCステップがデータを生成すると、status.updatedペイロードに同じnfc_verifications[]配列が含まれます。Webhookを参照してください。
スタンドアロンNFC: チップを直接送信する場合は、NFCの概要を参照してください。

ワークフローに含まれるNFCステップがスキップまたはバイパスされた場合、判定ペイロードにはトップレベルのnfc_skip_reasonフィールドも含まれ、その理由が正確に示されます。理由は、書類にチップがない、発行国の証明書が利用できない、デバイスにNFCリーダーがない、ネイティブSDKなしで認証が実行された(ブラウザからはNFCにアクセスできない)、MRZからチップのアクセスキーを導出できなかった、マイナンバーカードをJPKIで読み取れなかった、またはユーザーがスキップを選択した、のいずれかです。この分類に当てはまらない場合はnullのままです。最も多いのは、ユーザーが試行の途中で放棄した場合(レポートのステータスはNot Finished)や、NFCがまだ保留中のセッションです。正確な値についてはスキップ理由を参照してください。

以前のドキュメントでは単数形のnfcフィールドが参照されていました。この形式はv3の判定エンドポイントには存在しません。V2 Webhookに明示的に固定されている送信先でのみ現れ、このフィールドにはchip_protocolとjpkiも含まれます。常にresponse.nfc_verifications[0]を読み取り、配列を反復処理してください。

スキーマ

フィールドごとの正式なスキーマは、データモデルのリファレンスページにあります。以下のフィールドは、その正式なスキーマと同じ内容です。

フィールド	型	説明
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	NFCステップのステータスです(意味は上記を参照)。
`node_id`	string \| null	このレポートを生成したワークフローのグラフノードです。複数ステップのワークフローで、2つの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準拠のePassportまたはeIDチップです。`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`(読み取ったData Groupの一覧)、`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`も追加されます)。DG11がない場合、これらのキーはnullではなく存在しません。NFCステップがスキップされた場合は`null`です。
`authenticity`	object \| null	ICAOのパッシブ認証の結果です(以下を参照)。JPKIによる読み取りの場合は`null`です。
`authenticity.sod_integrity`	boolean	SODの署名が発行国の有効なCSCAまでの信頼チェーンで検証され、かつDSCが失効も期限切れもしていない場合は`true`です。
`authenticity.dg_integrity`	boolean	すべてのData Groupのハッシュが、SODで署名された値と一致する場合は`true`です。`false`の場合、チップのデータが改ざんされたか、一部しか読み取られていないことを意味します。
`certificate_summary`	object \| null	このチップに署名したDSCの概要です。`issuer`、`subject`、`serial_number`、`not_valid_before`、`not_valid_after`(タイムスタンプは`YYYY-MM-DD HH:MM:SS`形式)に加え、個々のチェック結果(`csca_verified`、`csca_missing`、`dsc_revoked`、`dsc_expired`、`csca_expired`)を含む`validation`オブジェクトがあります。`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のアクションが設定された警告が発生しなかった状態です。警告が発生しても、設定されたアクションが「No action」である場合も含みます。	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`	レビュアーがこのステップの再提出を求めた状態です。	ユーザーが再試行すると、新しい試行がこのレポートを置き換えます。

2つの証明書の警告(DSC_CERTIFICATE_REVOKED、DSC_CERTIFICATE_EXPIRED)は情報提供のためのものです。warnings[]には表示されますが、それ単独でNFCのstatusが変わることはありません。動作の一覧はNFCの警告を参照してください。

例

Approved: チップの読み取りに成功し、暗号学的にも有効

{
  "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": []
    }
  ]
}

Declined: 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`	`"user_authentication"` \| `"signature"`の配列	読み取ったカードの証明書。`user_authentication`（4桁のPIN）は常に読み取られます。`signature`（署名用PIN）は、NFCノードの`jpki_request_attributes`設定がオンの場合に読み取られます。この設定はデフォルトでオンです。
`jpki.chain_valid`	真偽値	すべての証明書が、その種類に対応するJPKI認証局まで連鎖し、有効期間内であり、かつその種類のマイナンバーカード証明書である場合に`true`。
`jpki.signature_valid`	真偽値	カードがワンタイムチャレンジに対して行ったすべての署名が検証に成功した場合に`true`。カードはPINが入力された後にのみ署名するため、本人がカードを所持し、PINを知っていることの証明になります。
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`：すべての証明書が失効していないことが確認されています。`revoked`：証明書が失効しています（例：カードの紛失が届け出られた場合）。`unchecked`：失効に関する応答が得られなかったため、失効したカードである可能性を排除できません。`good`として扱われることはありません。失効確認は、チェーンと署名が有効な場合にのみ行われます。
`jpki.ca_generation`	文字列 \| null	証明書を発行したJPKI認証局の世代（例：`"2023"`）。どの認証局にも連鎖する証明書がない場合は`null`。
`jpki.certificate_expires_at`	文字列 (ISO 8601) \| null	読み取った証明書のうち最も早い有効期限。
`jpki.certificates[]`	配列	読み取った証明書ごとに1件のエントリ：`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`	オブジェクト \| null	署名用証明書のチェーンが有効な場合に、その証明書から取得した保有者のデータ：`full_name`（登録どおりの表記。通常は日本語の文字体系）、`date_of_birth`（`YYYY-MM-DD`）、`gender`（`M`、`F`または`null`）、`address`、および`name_substitute_characters` / `address_substitute_characters`。後者2つは、標準の文字セットに含まれないために代替文字に置き換えられた文字を示します（置き換えがない場合は`null`）。署名用証明書が要求されなかった場合、またはそのチェーンが有効でない場合は`null`。
`jpki.attributes_match_ocr`	真偽値 \| null	属性が同じカードの写真から読み取ったデータと一致する場合は`true`、いずれかが異なる場合は`false`（`JPKI_AND_OCR_DATA_NOT_SAME`）、`attributes`が`null`の場合を含め、比較できるものがない場合は`null`です。
`jpki.mismatched_attributes`	文字列の配列	写真のデータと異なる属性（`full_name`、`date_of_birth`、`gender`、`address`）。値そのものが含まれることはありません。

レポートには、証明書そのもの、そのシリアル番号、署名、およびカードの12桁の個人番号（マイナンバー）が含まれることはありません。個人番号はNFCステップで読み取られることもありません。

マイナンバーカードの読み取り例

{
  "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認証レポート：ICチップデータと真正性の確認

概要

APIレスポンス内での表示箇所

スキーマ

ステータスの値

例

Approved: チップの読み取りに成功し、暗号学的にも有効

Declined: OCRとチップのデータの不一致

マイナンバーカード (JPKI)

JPKIフィールド

マイナンバーカードの読み取り例

セキュリティに関する注意

関連情報

​概要

​APIレスポンス内での表示箇所

​スキーマ

​ステータスの値

​例

​Approved: チップの読み取りに成功し、暗号学的にも有効

​Declined: OCRとチップのデータの不一致

​マイナンバーカード (JPKI)

​JPKIフィールド

​マイナンバーカードの読み取り例

​セキュリティに関する注意

​関連情報

概要

APIレスポンス内での表示箇所

スキーマ

ステータスの値

例

Approved: チップの読み取りに成功し、暗号学的にも有効

Declined: OCRとチップのデータの不一致

マイナンバーカード (JPKI)

JPKIフィールド

マイナンバーカードの読み取り例

セキュリティに関する注意

関連情報