Enterprise エディション

署名検証 — 詳細リファレンス

概要

このページは、NextPDF Enterprise における AdES 検証側サーフェスの詳細リファレンスです。エントリポイントは NextPDF\Enterprise\Security\Validation\AdESValidationEngine です。これは、基本・時刻付き・長期・アーカイブタイムスタンプの各チェックに対する、NextPDF の ETSI モデル化された検証フローを実装します。すなわち、基本検証、時刻付き検証、長期データ付き検証、およびアーカイブ DocTimeStamp カバレッジチェーン検証です。結果は ValidationReport 値であり、ETSI URN 文字列値を持つ MainIndication および SubIndication の enum ケースを保持します。ここで文書化する補助サーフェスは、SignatureDataExtractor SPI とその CmsSignatureDataExtractor 実装、PdfSignatureDictionaryScanner バイトレベルスキャナ、NextPDF\Enterprise\Security\Pki パス検証サーフェス、そして BatchSignatureValidator です。ワークフローレベルのガイダンスについては、署名検証: AdES / PAdES 暗号検証側を参照してください。

提供と licensing

この機能は NextPDF Enterprise（nextpdf/enterprise）で提供され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得。

公開 API サーフェス

シンボル	パラメータ	既定の挙動	戻り値	スロー/失敗	備考
`AdESValidationEngine::__construct`	11 個のオプションパラメータ: `?PathValidatorInterface $chainValidator`、`?SignatureDataExtractor $extractor`、`ClockInterface $clock`、`?LoggerInterface $logger`、`string $defaultPolicy`、`NetworkPolicy $networkPolicy`、および 5 個のオプション検証コラボレータ	既定はすべてフェイルクローズ。エンジンクロック上の Pki パス検証、エクストラクタなし、TSA トラストストアなし	新しいエンジン	スローしない	トラストストアがない場合、TSA チェーン評価は untrusted と報告され、それは `INDETERMINATE` にマップされ、決して合格にはならない
`AdESValidationEngine::validateBasic`	`string $signedData`、`string $signature`	基本検証: フォーマット、ダイジェスト、暗号、脆弱アルゴリズム、チェーン、来歴ゲート付き失効	`ValidationReport`	スローしない。抽出およびパスの失敗はフェイルクローズ型レポートにマップ	エクストラクタがない場合はガードチェックのみ。エッジケースを参照
`AdESValidationEngine::validateWithTime`	`string $signedData`、`string $signature`、`DateTimeImmutable $claimedTime`	まず基本検証。証明書ウィンドウと失効を主張時刻に対して比較	`ValidationReport`	スローしない	属性が存在する場合は厳格な署名タイムスタンプゲート。`$claimedTime` が時刻アンカーのまま
`AdESValidationEngine::validateWithLongTermData`	`string $signedData`、`string $signature`、`array $dssData`（`certs`/`ocsps`/`crls`）	基本合格が必須。TSA-at-genTime で武装した署名タイムスタンプゲート。POE、DSS 失効、およびアーカイブゲート	`ValidationReport`	スローしない	埋め込みデータが不十分な `NetworkPolicy::STRICT_OFFLINE` は `INDETERMINATE` / `TRY_LATER` を返す
`AdESValidationEngine::validateArchivalTimestampChain`	`string $pdfBytes`、`array $dssData = []`、`?TrustAnchorStoreInterface $anchors = null`	厳密な ByteRange バイトに対する証拠ベースの DocTimeStamp カバレッジチェーン	`ValidationReport`	敵対的バイトでもスローしない	`TOTAL_PASSED` は信頼済みで EOF をカバーするチェーンに対してのみ
`MainIndication`	—	文字列裏付けの enum、3 ケース	—	—	ETSI URN 値。下記のケース一覧を参照
`SubIndication`	—	文字列裏付けの enum、15 ケース	—	—	ETSI URN 値。下記のケース一覧を参照
`ValidationReport::__construct`	`MainIndication $mainIndication`、`?SubIndication $subIndication`、`DiagnosticData $diagnosticData`、`DateTimeImmutable $validationTime`、`string $validationPolicy = ''`	不変（`final readonly`）の検証結果	新しいレポート	スローしない	`isPassed()`、`isFailed()`、`isIndeterminate()`、`toArray()`
`DiagnosticData::__construct`	`array $certificateChain`、`array $timestamps`、`array $revocationData`、`string $validationPolicy`、`string $signatureFormat`、`array $warnings`（すべて既定値あり）	不変の証拠コンテナ。監査証跡のみ	新しい値	スローしない	`toArray()` はレポート用に参照をシリアライズ
`SignatureDataExtractor::extract`	`string $signedData`、`string $signature`	SPI: CMS を解析し検証コンポーネントを抽出	`ExtractedSignatureData`	署名が解析できない場合 `SignatureExtractionException`	インターフェース。ASN.1 解析をエンジンから分離
`CmsSignatureDataExtractor::extract`	`string $signedData`、`string $signature`	抽出に加え、デタッチ型 PAdES 基本署名を暗号的に検証	`ExtractedSignatureData`	CMS がまったく解析できない場合にのみ `SignatureExtractionException`	暗号または束縛の失敗は `cryptoValid` / `hashValid` を false としたデータを返し、それに対してスローしない
`PdfSignatureDictionaryScanner::scan`	`string $pdfBytes`	`/ByteRange` + `/Contents` 辞書を、精密フィットのアンチスプーフ相互チェック付きでバイトレベルスキャン	`list<PdfSignatureOccurrence>`	全域的。決してスローせず、不正な候補はスキップ	カバレッジ終端順、最も早いものが先頭
`PathValidatorInterface::validate`	`array $chain`、`?DateTimeImmutable $validationTime = null`、`array $initialPolicies = []`	ポリシー処理を伴う RFC 5280 §6.1.4 パス検証	`PathValidationResult`	構造的に無効なチェーン、または破られた敵対的リミットで `PathValidationException`	チェーンはエンドエンティティが先頭、アンカーが末尾
`PathValidatorInterface::validateWithAiaChasing`	`array $chain`、`?DateTimeImmutable $validationTime = null`	欠落した中間証明書の AIA 解決、その後に検証	`PathValidationResult`	`PathValidationException`	フェッチはタイムアウトとバイトリミットで上限制御
`CertificateChainValidator`	コンストラクタ: エンジン、`PathValidationOptions`、クロック、ロガー。静的 `withDefaults()`	既定の敵対的キャップを持つ SPI 実装	両メソッドから `PathValidationResult`	`PathValidationException`	`OpenSSLCertificate` を PEM にエクスポートできない場合にもスロー
`PathValidationOptions::__construct`	キャップ（`maxDepth`、`maxPolicyFanout`、`fetchTimeoutSeconds`、`fetchSizeCapBytes`）に加え、ポリシーフラグ、`?TrustAnchorStoreInterface $trustAnchors`、`bool $requireTrustedAnchor`	深さ 32、ファンアウト 64、フェッチあたり 5 秒、フェッチあたり 10 MiB。全フラグ false	新しいオプション	スローしない	ファクトリ: `defaults()`、`strict()`、`withTrustAnchors()`
`PathValidationResult::__construct`	`bool $valid`、`string $trustAnchorFingerprint`、`DateTimeImmutable $validatedAt`、`array $validPolicies`、`?RevocationCheckResult $revocation`、`bool $trustAnchorTrusted`、`array $fetchedCertificates`、`array $failureReasons`	不変の結果。`trustAnchorTrusted` は既定 false（フェイルクローズ）	新しい値	スローしない	信頼メンバーシップは構造的妥当性とは別
`PolicyProcessor`	コンストラクタ: `PolicyTreeState $state`、`PathValidationOptions $options`。`processCertificate(string $certDer, int $depth, bool $selfIssued)`、`finalizeWrapUp()`、`tree()`	RFC 5280 §6.1.4 のポリシーツリー展開、マッピング、ラップアップ	`void` / `list<non-empty-string>` / `PolicyTree`	ポリシー処理の失敗すべてに対して `PathValidationException`（フェイルクローズ）	ラップアップは anyPolicy を除いた生存ポリシー OID を返す
`PolicyTree`	`attach(PolicyTreeNode $node, PathValidationOptions $options)`、`enforceFanout(...)`、`remove(...)`、および読み取りクエリ群	深さインデックス付きの `valid_policy_tree` 状態	メソッドごとに異なる	ライブなリーフ数がファンアウトキャップを超えた場合 `PathValidationException`	`ANY_POLICY_OID`（`2.5.29.32.0`）を公開
`NameConstraintsChecker::processCertificate`	`string $certDer`、`bool $applyNameCheck`	RFC 5280 §6.1.4(g) に従い、許可/除外サブツリーを蓄積し強制	`void`	違反したサブツリー、制約内の未サポート GeneralName 形式、または破られたキャップで `PathValidationException`	比較不能な名前はフェイルクローズで扱う
`TrustAnchorStoreInterface::containsFingerprint`	`string $anchorDerSha256Hex`	アンカーの DER 証明書に対する小文字 16 進 SHA-256 によるメンバーシップ	`bool`	スローしない	パス検証器が参照する信頼シーム
`BatchSignatureValidator::validate`	`array $inputs`（`list<DocumentSignatureInput>`）	バッチ単位の失効キャッシュを伴う複数ドキュメント署名検証	`BatchValidationReport`	空リストで `InvalidArgumentException`。リソースガードが 1000 ドキュメント超のバッチを拒否	`NextPDF\Enterprise\Signature` に存在

final class AdESValidationEngine

public function validateBasic(string $signedData, string $signature): ValidationReport

public function validateWithTime(
    string $signedData,
    string $signature,
    DateTimeImmutable $claimedTime,
): ValidationReport

public function validateWithLongTermData(
    string $signedData,
    string $signature,
    array $dssData,
): ValidationReport

public function validateArchivalTimestampChain(
    string $pdfBytes,
    array $dssData = [],
    ?TrustAnchorStoreInterface $anchors = null,
): ValidationReport

public function validate(
    array $chain,
    ?DateTimeImmutable $validationTime = null,
    array $initialPolicies = [],
): PathValidationResult;

public function validateWithAiaChasing(
    array $chain,
    ?DateTimeImmutable $validationTime = null,
): PathValidationResult;

public static function withDefaults(
    ?ClockInterface $clock = null,
    ?AiaChaser $aiaChaser = null,
    ?LoggerInterface $logger = null,
): self

public function containsFingerprint(string $anchorDerSha256Hex): bool;

public function extract(string $signedData, string $signature): ExtractedSignatureData;

public function scan(string $pdfBytes): array

public function validate(array $inputs): BatchValidationReport

インジケーション enum。 MainIndication のケース: TOTAL_PASSED、TOTAL_FAILED、INDETERMINATE。裏付け値は urn:etsi:019102:mainindication:total-passed（小文字、ハイフン区切り）のパターンに従います。SubIndication のケース: HASH_FAILURE、SIG_CRYPTO_FAILURE、REVOKED、EXPIRED、NOT_YET_VALID、NO_POE、TRY_LATER、CERTIFICATE_CHAIN_GENERAL_FAILURE、FORMAT_FAILURE、REVOKED_CA_NO_POE、CRYPTO_CONSTRAINTS_FAILURE、POLICY_PROCESSING_FAILURE、REVOCATION_OUT_OF_BOUNDS_NO_POE、NO_SIGNING_CERTIFICATE_FOUND、TIMESTAMP_ORDER_FAILURE。それぞれは正確なケース名を持つ urn:etsi:019102:subindication:<CASE_NAME> で裏付けられます。

挙動契約

レポートを入れ、レポートを出す。 4 つのエンジンエントリポイントは、敵対的入力に対してスローするのではなく ValidationReport を返します。捕捉された SignatureExtractionException はガードパスへ経路づけられ、捕捉された PathValidationException は TOTAL_FAILED / CERTIFICATE_CHAIN_GENERAL_FAILURE にマップされます。
基本検証の順序。 まずフォーマットチェック。解析不能な構造は TOTAL_FAILED / FORMAT_FAILURE（EN 319 102-1 §5.3.4）です。次にダイジェスト（HASH_FAILURE）と暗号検証（SIG_CRYPTO_FAILURE）で、EN 319 102-1 §5.2.7.4 のビルディングブロック結果に一致します。ダイジェストは検証器によって再計算され、messageDigest 署名付き属性と比較されます（RFC 5652 §5.6）。生成者が供給したダイジェストは決して信頼されません。
脆弱アルゴリズムは格下げされる。 SHA-1 の下で検証される署名、または脆弱な署名証明書束縛を伴う署名は、INDETERMINATE / CRYPTO_CONSTRAINTS_FAILURE を返し、決して TOTAL_PASSED にはなりません。時刻パスはこれを再主張するため、脆弱な署名が時刻有効な合格へと洗浄されることはありません。
失効の来歴ゲート。 エクストラクタの失効フラグは、エクストラクタが実際に失効チェックを実行した場合（revocationChecked が true）にのみ参照されます。未チェックの既定値は「失効していないことが検証済み」でも REVOKED のトリガでもありません。失効証拠は DSS パスによって確立されます。
非合格の伝播。 時刻および長期パスは、非合格の基本結果を決してアップグレードしません。1 つの例外があります。基本の INDETERMINATE / REVOKED は $claimedTime に対して解決されます。主張時刻以前の失効は TOTAL_FAILED / REVOKED です。これは、失効関連の不確定を時刻証拠で解決する EN 319 102-1 §5.3.4 のパターンを反映しています。比較を実行できない場合、未解決の基本レポートがそのまま伝播されます。
厳格な署名タイムスタンプ束縛（フェイルクローズ、BC 破壊）。 CMS が id-aa-timeStampToken 未署名属性を持つ場合、その存在は時刻および長期の両パスで強制をトリガします。warn-only モードは存在しません。カーディナリティは、正確に 1 つの値を持つ正確に 1 つの属性でなければなりません（EN 319 122-1 §5.3）。それ以外の形状はすべて TOTAL_FAILED / FORMAT_FAILURE です。トークンは端から端まで暗号的に検証されなければなりません。検証不能なトークン、パーサ差分の競合、またはインプリント不一致は INDETERMINATE / TIMESTAMP_ORDER_FAILURE です。未サポートまたは SHA-1 のインプリントアルゴリズムは INDETERMINATE / CRYPTO_CONSTRAINTS_FAILURE です。束縛規則は RFC 3161 Appendix A です。トークンの messageImprint は SignerInfo の signature 値オクテットのハッシュと等しくなければならず、一定時間で比較されます。
長期パスのゲート。 clause-5.4 注釈付きパスでは、束縛された署名タイムスタンプはさらに、トークンの genTime における TSA 証明書評価を受けます。信頼されないアンカーは INDETERMINATE / CERTIFICATE_CHAIN_GENERAL_FAILURE であり、決して合格にはなりません。埋め込み DSS 素材が不十分な NetworkPolicy::STRICT_OFFLINE は INDETERMINATE / TRY_LATER を返します。存在証明、DSS 失効、およびアーカイブチェーンの各所見は、それぞれマップされたサブインジケーションを伴う INDETERMINATE へショートサーキットします。
アーカイブチェーンのゲート。 DocTimeStamp が存在しない場合は INDETERMINATE / NO_POE です。構造的に非適合な ByteRange は TOTAL_FAILED / FORMAT_FAILURE です。各トークンは検証され、そのインプリントを厳密な ByteRange がカバーするバイトに束縛し、TSA-at-genTime のファセットマッピング（EXPIRED、NOT_YET_VALID、REVOKED_CA_NO_POE、CERTIFICATE_CHAIN_GENERAL_FAILURE、または strict-offline 下の TRY_LATER）を通過しなければなりません。順序が強制されます。非減少の genTime、厳密に進行するカバレッジ、そして後続のトークンが先行トークンの /Contents ホールを含むこと。最新のトークンは最終バイトをカバーしなければならず、末尾バイトが残ると TIMESTAMP_ORDER_FAILURE です。検証器クロックより 300 秒を超えて先行する genTime は TIMESTAMP_ORDER_FAILURE です。
診断は決して判定しない。 DiagnosticData::$timestamps の存在証明エントリは監査証跡のみです。それらはインジケーションを決して変えず、アキュムレータは各エントリポイントでリセットされます。
Pki のリミットは暗号処理に先立つ。 PathValidationOptions のキャップ（深さ 32、ポリシーファンアウト 64、フェッチあたり 5 秒と 10 MiB）は、高コストの処理の前にチェックされます。PathValidationResult::$trustAnchorTrusted は $valid とは別です。requireTrustedAnchor は、確認されていない終端を無効にします。strict() は requireExplicitPolicy、ハードフェイルの失効トランスポート、および requireTrustedAnchor を有効化します。パス妥当性はアンカー相対であり、RFC 5280 §6.1 に従います。有効なパスは、入力として供給されたトラストアンカーから始まります。
バッチサーフェス。 BatchSignatureValidator::validate() は、空リストに対して InvalidArgumentException をスローし、1000 ドキュメントを超えるバッチをリソースガードにより拒否します。そのパイプラインではすべての暗号検証を PHP が担います。

エッジケースと失敗モード

既定エンジンはエクストラクタを持たない。 new AdESValidationEngine() はガードチェックのみを実行します。空の署名または署名データは TOTAL_FAILED。空でないペアはすべて INDETERMINATE / NO_SIGNING_CERTIFICATE_FOUND に解決され、決して TOTAL_PASSED にはなりません。暗号検証を得るには NextPDF\Enterprise\Security\Validation\CmsSignatureDataExtractor を注入してください。
既定の TSA 信頼チェックはストアを持たない。 その場合、あらゆる TSA チェーンが untrusted と報告されるため、アーカイブおよび長期の署名タイムスタンプ結果は INDETERMINATE のままです。validateArchivalTimestampChain(..., $anchors) または設定済みの TsaCertificateAtGenTimeCheck 経由でアンカーを供給してください。
空の $pdfBytes。 validateArchivalTimestampChain('') は TOTAL_FAILED / FORMAT_FAILURE を返します。
修正前の署名タイムスタンプは合格できない。 厳格束縛修正より前の NextPDF バージョンが生成したトークンは、異なる入力をインプリントしていました。それらは Appendix A 束縛に恒久的に失敗します。肯定的な結果を回復するには、再署名して再タイムスタンプしてください。これは意図的で文書化された BC 破壊です。
重複または重なり合う DocTimeStamp。 同一リビジョンの重複、等しいまたは重なるカバレッジ、あるいは先行トークンの署名ホールを含まない後続トークンは、順序ゲートに失敗します。
スキャナは全域的かつバイトレベル。 scan() は不正またはスプーフされた候補を黙ってスキップします。コンテンツストリーム内のおとりの /ByteRange は拒否されます。間接オブジェクトの解決やクロスリファレンステーブルの走査は行いません。
カバレッジであって到達可能性ではない。 validateArchivalTimestampChain() は、ファイル末尾までの暗号的バイト範囲カバレッジを証明します。オブジェクトレベルの到達可能性解析（例えば、カバーされたリビジョン内で再ポイントされたドキュメントルート）は対象外と宣言されています。
Pki の直接使用はスローする。 PathValidatorInterface 実装を直接呼び出すと、構造的に無効なチェーン、破られたキャップ、未サポートの制約形式、および OpenSSLCertificate ハンドルの PEM エクスポート失敗に対して PathValidationException が表面化します。エンジンはこのクラスを捕捉しますが、あなた自身の呼び出し側はこれを処理しなければなりません。

FIPS モードの挙動

検証側は、SHA-2 を伴う RSA PKCS#1 v1.5 と、P-256/P-384/P-521 上の ECDSA を受け付けます。RSASSA-PSS、EdDSA、および SHA-3 のトークンは未サポートとしてフェイルクローズし、SHA-1 は CRYPTO_CONSTRAINTS_FAILURE に格下げされます。Enterprise FIPS 140-3 暗号ポリシープロファイル（セキュリティモジュールとともに文書化）の下では、制約はどのアルゴリズムが受け付けられるかに適用されます。検証フロー自体 — ダイジェスト再計算、署名チェック、束縛、パス検証 — は変更されません。NextPDF は FIPS 140-3 証明書を保持しておらず、このページはいかなる主張もしません。

適合性

主張	標準	節
基本署名検証は、タイムスタンプおよび時刻付き検証のための再利用可能なビルディングブロック。	ETSI EN 319 102-1	§5.3.1
完全性の失敗は `HASH_FAILURE` に、失敗した署名チェックは `SIG_CRYPTO_FAILURE` にマップ。	ETSI EN 319 102-1	§5.2.7.4
フォーマットチェックが最初に実行され、非合格は処理を停止。	ETSI EN 319 102-1	§5.3.4
失効関連の不確定は時刻証拠で解決可能。	ETSI EN 319 102-1	§5.3.4
有効な証明書パスは、入力として供給されたトラストアンカーから始まる。	RFC 5280	§6.1
検証器はコンテンツダイジェストを再計算し、それは `messageDigest` 署名付き属性と等しくなければならない。	RFC 5652	§5.6
署名タイムスタンプの `messageImprint` は SignerInfo の `signature` フィールド値をハッシュする。	RFC 3161	Appendix A
`signature-time-stamp` 属性は正確に 1 つの `AttributeValue` を持つ。	ETSI EN 319 122-1	§5.3

すべての節は言い換えであり、NextPDF は規範テキストを複製しません。NextPDF は AdES / PAdES の適合または認証をいかなる主張もしません。 標準のサポートはそれへの適合ではなく、適合は認証ではありません。NextPDF はいかなる認証も保持せず、いかなる認証も付与しません。エンジンは引用された検証手順を能力として実装します。それは適格または認証された検証サービスではなく、TOTAL_PASSED レポートは暗号的な言明であって法的判定ではありません。enum 値は、レポートデータの相互運用性のために ETSI URN 識別子パターンを再利用しますが、その再利用はいかなる推奨も主張しません。

開発ノート

節ラベルのマッピング。 パッケージソースは、エントリポイントを EN 319 102-1 の節 5.2、5.3、5.4 として注釈します。コンプライアンスコーパスは、基本署名検証プロセス自体を節 5.3 に、暗号ビルディングブロックを 5.2.7.4 に配置します。このページは取得された節番号を引用します。ラベルではなく挙動契約が権威的です。
決定論的テスト。 すべての時刻比較は、注入された PSR-20 ClockInterface を通じて流れます。ウィンドウチェック、300 秒の genTime スキュー境界、および CRL 鮮度の判定をテストするには、凍結クロックを注入してください。
コンポジション。 すべてのエンジンコラボレータはコンストラクタ注入かつオプションであり、フェイルクローズの既定を持ちます。既定のパス検証器はエンジンクロック上の CertificateChainValidator::withDefaults() です。既定オプションは、適合し制約のない入力に対して、ポリシーおよび名前制約処理を no-op に保ちます。
名前空間。 エンジンサーフェスは NextPDF\Enterprise\Security\Validation に、パス検証サーフェスは NextPDF\Enterprise\Security\Pki に、バッチオーケストレータは NextPDF\Enterprise\Signature に存在します。
レポートの衛生。 レポートは不変であり、toArray() によりシリアライズ可能です。診断コンテキストは各エントリポイントでリセットされるため、レポートが同一エンジンインスタンス上の前回実行の証拠を運ぶことはありません。

公開境界

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを文書化します。内部名前空間パス、ヘルパークラス、メカニズム表、ランブックのファイル名、およびチケットプレフィックスは対象外です。