必要なデータを受け取り、署名の検証を行います。
署名検証には以下のデータが必要となります。

署名値

署名に利用した秘密鍵に対応する証明書

署名対象データのダイジェスト

ダイジェストの作成に利用したハッシュ関数

マイナンバーカードのJPKI APによる署名値の作成や証明書の取得は、PocketSign Verify SDKを利用して実装できます。
詳しくはVerify SDK リファレンスをご参照ください。

対応する証明書

公的個人認証サービス(JPKI)によって発行された証明書のうち、マイナンバーカードに搭載された署名用電子証明書および利用者証明用電子証明書のみが利用できます。
それ以外の証明書を受け取った場合は unsupported_certificate エラーを返します。

なお、現行のPocketSign Verify APIはスマートフォンに搭載される署名用電子証明書および利用者証明用電子証明書には対応しておらず、
これらの証明書を受け取った場合にも同様に unsupported_certificate エラーを返します。

スマートフォンに搭載される証明書の検証については、サポートに向けて取り組んでいます。

対応するハッシュ関数

ダイジェストの作成に利用できるハッシュ関数は、CRYPTREC暗号リスト(電子政府推奨暗号リスト)で推奨されるハッシュ関数のみです。
PocketSign Verify APIでは、CRYPTREC LS-0001-2022を参照しており、このうち以下のハッシュ関数のみに対応しています。

SHA-256

SHA-384

SHA-512

署名検証の流れ

以下の手順で署名検証を行います。
ステップの途中で検証に失敗した場合、そこで検証を打ち切り、エラーもしくは検証結果を返します。

証明書チェーンの確認

対象の証明書が、公的個人認証サービス(JPKI)認証局によって発行された証明書であることを確認します。

証明書チェーンの確認に失敗した場合はAPIがエラー扱いとなります。エラーコードは unsupported_certificate となります。

有効期限の確認

対象の証明書が有効期限内であることを確認します。

有効期限の検証に失敗した場合は、検証結果コード certificate_has_expired が返されます。

署名値の確認

署名値が、証明書に記載された公開鍵に対応する秘密鍵によって作成されたものであることを確認します。

署名値の確認に失敗した場合は、検証結果コード signature_did_not_match が返されます。

失効確認

証明書の失効確認を行います。

失効確認に失敗した場合は、検証結果コード certificate_has_been_revoked が返されます。

上記のステップを全て通過した場合、検証結果コード ok が返されます。

証明書の失効事由

certificate_status.revocation_reasonは、証明書が失効した事由を表します。

失効事由の詳細については、地方公共団体システム機構(J-LIS)が提供する認証局の運営情報の一部として公開されている署名用認証局運用規程(4.9.9. オンラインでの失効ステータス確認の適用性)および利用者証明用認証局運用規程(4.9.9. オンラインでの失効ステータス確認の適用性)をご参照ください。
以下に、当該規程に記載されている失効事由を示します。

`revocation_reason`	失効事由
`unspecified`	交付前に破棄した
`key_compromise`	利用者の秘密鍵が危殆化した
`ca_compromise`	CAの秘密鍵が危殆化した
`affiliation_changed`	証明書の記載内容に変更が生じた
`superseded`	証明書を更新した
`cessation_of_operation`	証明書の必要性がなくなった（使用しなくなった）
`certificate_hold`	秘密鍵の安全性に疑義が生じたため、証明書を一時的に保留した（一時保留の解除は行わない）

失効確認の方法

失効確認の方法は2通りから選択できます。
いずれの方法でも同じデータソースを参照していますが、更新のタイミング等が異なります。

また、料金の計算方法も異なります。
詳しくは料金体系(準備中)をご参照ください。

CRLファイルの参照

認証局より日時で取得したCRL（証明書失効リスト）ファイルの中に、検証対象の電子証明書が含まれているかどうかを確認します。

参照するCRLファイルは、毎朝7:30(日本時間)頃に更新されます。この時刻までは前日分のCRLファイルが参照されます。
CRLファイル更新作業は通常5〜10分程度を要し、この期間中は前日分のCRLファイルが参照される可能性があります。
確実に当日分の失効情報を確認したい場合は、OCSPによる問い合わせをご利用ください。

OCSPによる問い合わせ

認証局が運用するOCSPレスポンダに都度問い合わせを行い、証明書の状態を確認します。

失効確認の目的

署名検証の過程で実施された失効確認は、check_purpose が signature_verification (署名検証)として記録されます。
証明書データによる失効確認および証明書IDによる失効確認の場合は、check_purpose が liveness_check (現況確認)として記録されます。

これらは、関係機関への報告のために利用されます。
また、PocketSign Verify APIの利用料金計算にも利用されます。

利用者の特定

このAPIは、証明書が発行された利用者の特定を行う機能を提供しています。
この機能を使用すると、公的個人認証サービス(JPKI)が提供する証明書紐付け情報および証明書新旧紐付け機能を利用し、利用者に対して一意な利用者IDを割り当てることができます。

同一の人物に対して発行された署名用電子証明書と利用者証明用電子証明書については、そのいずれに対しても同一の利用者IDが返されます。
これを利用することで、例えば署名用電子証明書によって登録した利用者に対して利用者証明用電子証明書によるログイン機能をシームレスに提供することができます。

利用者IDは、引っ越しや有効期限到来等による証明書の更新後も、同一の値が返されます。

利用者情報の削除を行うと、以後は新しい利用者IDが割り当てられます。

利用者IDはテナント内で一意であり、同一の証明書であっても異なるテナントでは異なる利用者IDが割り当てられます。

証明書に記載された情報(`certificate_content`)

このAPIでは、証明書に記載された情報を取り出してレスポンスに含めます。
証明書に記載された情報は、このAPIのレスポンスでのみ返され、検索APIや取得APIで後から取得した場合には返されません。

証明書に格納されたテキストデータをそのまま返すため、利用する際にはパースが必要です。
テキストデータの形式は地方公共団体情報システム機構(J-LIS)が提供している利用者クライアントソフトに係る技術仕様の一部として公開されている署名用電子証明書及び利用者証明用電子証明書のプロファイル仕様書 2.2版を参照してください。

署名用電子証明書には、基本4情報（氏名、住所、生年月日、性別）が含まれており、これらの情報を利用して利用者の身元を確認することが出来ます。
基本4情報の形式は、プロファイル仕様書の「2.1.1. 署名用電子証明書のプロファイル > ②署名用電子証明書のプロファイル拡張領域（Extension） > subjectAltName」をご参照ください。

リクエストとレスポンスの詳細

application/json

Body

verification

object (Verification)

必須

検証結果

string <uuid>

必須

検証ID

result

enum<string>

必須

RESULT_OK: 検証成功

RESULT_SIGNATURE_MISMATCH: 検証失敗（署名不一致のため）

RESULT_CERTIFICATE_REVOKED: 検証失敗（証明書が失効していたため）

RESULT_CERTIFICATE_EXPIRED: 検証失敗（証明書の有効期限切れのため）

列挙型:

RESULT_UNSPECIFIEDRESULT_OKRESULT_SIGNATURE_MISMATCHRESULT_CERTIFICATE_REVOKEDRESULT_CERTIFICATE_EXPIRED

デフォルト値:

RESULT_UNSPECIFIED

hash_algorithm

enum<string>

必須

ダイジェストの作成に利用したハッシュ関数

列挙型:

sha256sha384sha512

digest

string <byte>

必須

署名対象データのダイジェスト（Base64エンコード文字列）

signature

string <byte>

必須

署名値（Base64エンコード）

created_at

string <date-time>

必須

検証時刻

certificate

object (Certificate)

必須

証明書データ

string <uuid>

必須

証明書ID

type

enum<string>

必須

証明書種別

列挙型:

jpki_card_digital_signaturejpki_card_user_authentication

latest

boolean

必須

現行世代の証明書かどうか

各利用者ごとに、同じ種別の証明書のうち最も発行された順番が新しいものを現行世代と呼び、それ以外の証明書は旧世代と呼びます。
証明書に紐付く利用者が特定されていない場合、旧世代の証明書として扱います。

created_at

string <date-time>

必須

証明書情報が保存された時刻

certificate_status

object (CertificateStatus)

可選

証明書失効状態の確認結果

string <uuid>

必須

証明書失効確認ID

status

enum<string>

必須

証明書の失効状態

列挙型:

goodrevoked

check_method

enum<string>

必須

証明書の失効状態を確認する手段

列挙型:

crlocsp

check_purpose

enum<string>

必須

証明書の失効状態を確認する目的

列挙型:

signature_verificationliveness_check

source_updated_at

string <date-time>

可選

証明書失効状態の確認に利用したデータソースの更新日時

CRLやOCSPレスポンスに含まれる thisUpdate に相当します。
CRLにシリアル番号が含まれない場合は設定されません。

revoked_at

string <date-time>

可選

失効した日時

失効していない場合は設定されません。

revocation_reason

enum<string>

可選

証明書の失効理由

この値は、RFC 5280 5.3.1に定義されるCRLReasonに対応します。
証明書が有効である場合には設定されません。

列挙型:

unspecifiedkey_compromiseca_compromiseaffiliation_changedsupersededcessation_of_operationcertificate_holdremove_from_crlprivilege_withdrawnaa_compromise

created_at

string <date-time>

必須

失効確認を行った時刻

certificate_content

CertificateContent

必須

証明書の内容

One of

CertificateContentJPKICardDigitalSignature

CertificateContentJPKICardUserAuthentication

マイナンバーカードに搭載された署名用電子証明書に記載された情報

subject

string

必須

証明書のサブジェクト

validity

object

CertificateContentBasicValidity

必須

有効期限

crl_distribution_point

string

必須

CRL配布点

subject_alternative_name

object

CertificateContentJPKICardDigitalSignatureSAN

必須

証明書のサブジェクト代替名（基本4情報）

user

object (User)

可選

利用者データ

string <uuid>

必須

利用者ID

created_at

string <date-time>

必須

利用者情報が保存された時刻

is_new_user

boolean

可選

利用者が新規に作成されたかどうか

例

{
  "verification": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "result": "RESULT_UNSPECIFIED",
    "hash_algorithm": "sha256",
    "digest": "string",
    "signature": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "certificate": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "type": "jpki_card_digital_signature",
    "latest": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "certificate_status": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "good",
    "check_method": "crl",
    "check_purpose": "signature_verification",
    "source_updated_at": "2019-08-24T14:15:22Z",
    "revoked_at": "2019-08-24T14:15:22Z",
    "revocation_reason": "unspecified",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "certificate_content": {
    "subject": "string",
    "validity": {
      "not_before": "2019-08-24T14:15:22Z",
      "not_after": "2019-08-24T14:15:22Z"
    },
    "crl_distribution_point": "string",
    "subject_alternative_name": {
      "common_name": "string",
      "substitute_character_of_common_name": "string",
      "gender": "1",
      "date_of_birth": "string",
      "address": "string",
      "substitute_character_of_address": "string"
    }
  },
  "user": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "is_new_user": true
}

署名検証

対応する証明書

対応するハッシュ関数

署名検証の流れ

証明書の失効事由

失効確認の方法

CRLファイルの参照

OCSPによる問い合わせ

失効確認の目的

利用者の特定

証明書に記載された情報(`certificate_content`)

リクエストとレスポンスの詳細

Requestパラメータ

サンプルコード

Response

署名検証

対応する証明書#

対応するハッシュ関数#

署名検証の流れ#

証明書の失効事由#

失効確認の方法#

CRLファイルの参照#

OCSPによる問い合わせ#

失効確認の目的#

利用者の特定#

証明書に記載された情報(certificate_content)#

リクエストとレスポンスの詳細#

Requestパラメータ

サンプルコード

Response

対応する証明書

対応するハッシュ関数

署名検証の流れ

証明書の失効事由

失効確認の方法

CRLファイルの参照

OCSPによる問い合わせ

失効確認の目的

利用者の特定

証明書に記載された情報(`certificate_content`)

リクエストとレスポンスの詳細