Enterprise エディション

トラステッドリスト — 詳細リファレンス

概要

このページは、NextPDF Enterprise におけるトラステッドリストサーフェスの詳細リファレンスです。このサーフェスは、NextPDF\Enterprise\Security\Tsl 名前空間の 12 個の公開クラスから構成されます。NextPDF\Enterprise\Security\Tsl\TslPolicyEnforcer はオーケストレーションされたエントリポイントであり、HTTP フェッチ、XMLDSig 検証、構造パース、nextUpdate の失効ゲートがすべて通過した場合にのみ TslDocument を返します。続いて TslTrustAnchorProvider::buildBundle() が、アクティブな CA/QC サービスからトラストアンカーバンドルを導出し、アンカーを抽出する前に呼び出し側が指定した時点で鮮度を再度確認します。すべての失敗は型付き例外を送出し、いずれの段階も暗黙のうちに劣化することはありません。このパイプラインは、EU 加盟国のトラステッドリストの検証と、呼び出し側から供給された LOTL（List of Trusted Lists）由来のトラストアンカーをサポートします。LOTL の自動探索、ポーリング、ピボット処理は対象外です。

提供とライセンス

この機能は NextPDF Enterprise（nextpdf/enterprise）に同梱され、Enterprise 階層のライセンスエンベロープでアクティブ化されます。この権限を持たないデプロイメントでは、当該機能のクラスはロードされません。エディションを比較してライセンスを取得する。

公開 API サーフェス

シンボル	パラメータ	デフォルト動作	戻り値	スロー/失敗	備考
`TslPolicyEnforcer`	`TslFetcher $fetcher`、`TslSignatureVerifier $verifier`、`TslXmlParser $parser`	フェッチ、署名検証、パース、失効ゲートを 1 つのエントリポイントに統合	—	下記のパイプライン例外を伝播	`final`、構造上フェイルクローズ
`TslPolicyEnforcer::fetchAndVerify`	`string $url`	TSL を 1 つフェッチし、そのバイト列に対して `verifyXml()` を実行	`TslDocument`	`TslFetchException`、`NetworkPolicyViolation`、`TslSignatureException`、`TslParseException`	4 段階すべてが通過した場合のみ返す
`TslPolicyEnforcer::verifyXml`	`string $xml`	署名を検証し、パースし、古いリストを拒否	`TslDocument`	`TslSignatureException`、`TslParseException`	失効は現在のシステム時刻に対して評価
`TslFetcher`	`ClientInterface $httpClient`、`RequestFactoryInterface $requestFactory`、`?CacheInterface $cache = null`、`int $defaultTtlSeconds = 3600`、`int $maxBytes = 16_777_216`、`NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE`	ETag ベースのキャッシュを備えた HTTPS 専用の TSL/LOTL 取得	—	—	`final`、SSRF ガードがプライベート・ループバック・リンクローカル・メタデータのホストを DNS リバインディング緩和とともにブロック
`TslFetcher::fetch`	`string $url`	`If-None-Match` による再検証つき GET。ボディと ETag を設定された TTL でキャッシュ	`string`（生の XML バイト列）	`TslFetchException`、`NetworkPolicyViolation`	最大 `$maxBytes` バイトまで読み取る。`STRICT_OFFLINE` ではキャッシュされたボディのみ提供
`TslSignatureVerifier`	`array $trustAnchorsPem`、`int $clockTolerance = 0`	設定されたトラストアンカーにピン留めされた XMLDSig 検証器	—	アンカーリストが空の場合 `InvalidArgumentException`	`final`、`ALLOWED_SIG_ALG` と `ALLOWED_DIGEST_ALG` でアローリスト化
`TslSignatureVerifier::verify`	`string $xml`	エンベロープ型 XMLDSig 署名をフェイルクローズで検証	`string`（署名者証明書の PEM）	機械可読な理由コードつきの `TslSignatureException`	KeyInfo 証明書は単独では信頼されない。署名者は設定されたアンカーへチェーンしなければならない
`TslXmlParser::parse`	`string $xml`	`TslDocument` への構造パース。署名非依存	`TslDocument`	`TslParseException`	パース前に DOCTYPE をフェイルクローズで拒否。`LIBXML_NONET` でロード。呼び出し側は結果を信頼する前に検証が必要
`TslTrustAnchorProvider::buildBundle`	`TslDocument $tsl`、`DateTimeImmutable $now`	最初に鮮度を確認し、続いてアクティブな CA/QC サービスの証明書を収集	`EnterpriseCaTrustAnchorBundle`	`TslParseException`	鮮度ゲートはアンカー抽出に先行。結果集合が空の場合はスロー
`TslDocument`	昇格された 8 個の `readonly` プロパティ（コンストラクタフェンス参照）	イミュータブルなパース済み TSL 値オブジェクト	—	—	`final readonly`、ソース注釈 `@api`
`TslDocument::isStale`	`DateTimeImmutable $now`	フェイルクローズな UTC パースの後、`nextUpdate` を `$now` と比較	`bool`	`TslParseException`	明示的な `Z` または数値オフセットの指定子が必須
`TslDocument::assertFresh`	`DateTimeImmutable $now`	リストが古い、または `nextUpdate` がパース不能な場合にスロー	`void`	`TslParseException`	コンシューマー境界の鮮度ゲート
`TslDocument::servicesOfType`	`string $serviceTypeIdentifier`	ETSI サービスタイプ URI でサービスをフィルタリング	`list<TspService>`	スローしない	—
`TslDocument::activeServices`	—	granted ステータスのサービスのみを返す	`list<TspService>`	スローしない	granted は `TspService::STATUS_GRANTED` を意味
`TspService`	昇格された 8 個の `readonly` プロパティ	TSL 内の 1 つのトラストサービスエントリ	—	—	`final readonly`、ステータスとサービスタイプ URI の定数を保持
`TspService::isGranted`	—	granted URI に対するステータス等価判定	`bool`	スローしない	—
`TspService::isQualifiedCa`	—	CA/QC URI に対するタイプ等価判定	`bool`	スローしない	—
`TspServiceQualifier`	`string $qualifierUri`、`string $criteriaListAssert = 'all'`、`array $policyOidConditions = []`、`array $keyUsageConditions = []`	オプションの基準を伴う 1 つの ETSI サービス修飾子	—	—	`final readonly`、定数 `FOR_ESIG`、`FOR_ESEAL`、`FOR_WSA`、`QSCD_STATEMENT`、`NO_QSCD`
`EnterpriseCaTrustAnchorBundle`	`array $anchorsPem`、`string $bundleVersion`、`string $bundleSha256`	ピン留めアンカーバンドル。構築時に供給されたダイジェストを供給されたアンカーに対して検証	—	`InvalidArgumentException`	`buildBundle()` から取得。手動で構築しない。`TrustAnchorStoreInterface` を実装
`EnterpriseCaTrustAnchorBundle::containsFingerprint`	`string $anchorDerSha256Hex`	DER 本体に対する 16 進 SHA-256 でのアンカー所属判定	`bool`	スローしない	—
`EnterpriseCaTrustAnchorBundle::computeBundleSha256`	`array $anchorsPem`	改行正規化された PEM 連結に対する正準 SHA-256	`string`	スローしない	`static`
`TslFetchException`	—	TSL 取得の失敗を通知	—	—	`final`、`RuntimeException` を継承
`TslParseException`	—	構造または鮮度の失敗を通知	—	—	`final`、`RuntimeException` を継承
`TslSignatureException`	`string $reason`、`string $message`	理由コードつきで XMLDSig 検証失敗を通知	—	—	`final`、公開 `readonly` の `$reason`（下記の理由コード参照）

TslPolicyEnforcer

public function fetchAndVerify(string $url): TslDocument
public function verifyXml(string $xml): TslDocument

TslFetcher

public function __construct(
    private readonly ClientInterface $httpClient,
    private readonly RequestFactoryInterface $requestFactory,
    private readonly ?CacheInterface $cache = null,
    private readonly int $defaultTtlSeconds = 3600,
    private readonly int $maxBytes = 16_777_216,
    private readonly NetworkPolicy $networkPolicy = NetworkPolicy::ONLINE,
) {}

public function fetch(string $url): string

TslSignatureVerifier

public function __construct(private readonly array $trustAnchorsPem, private readonly int $clockTolerance = 0)

public function verify(string $xml): string

TslXmlParser

public function parse(string $xml): TslDocument

TslTrustAnchorProvider

public function buildBundle(TslDocument $tsl, DateTimeImmutable $now): EnterpriseCaTrustAnchorBundle

TslDocument

public function __construct(
    public string $schemeTerritory,
    public string $schemeOperatorName,
    public string $tslType,
    public int $sequenceNumber,
    public string $issueDateTime,
    public string $nextUpdate,
    public array $tspServices,
    public string $rawXmlSha256,
) {}

public function isStale(DateTimeImmutable $now): bool
public function assertFresh(DateTimeImmutable $now): void
public function servicesOfType(string $serviceTypeIdentifier): array
public function activeServices(): array

TspService

public function __construct(public string $tspName, public string $serviceName, public string $serviceTypeIdentifier, public string $serviceStatus, public string $statusStartingTime, public string $serviceCertificatePem, public array $qualifiers, public array $additionalServiceInformation) {}

public function isGranted(): bool
public function isQualifiedCa(): bool

TspServiceQualifier

public function __construct(public string $qualifierUri, public string $criteriaListAssert = 'all', public array $policyOidConditions = [], public array $keyUsageConditions = []) {}

EnterpriseCaTrustAnchorBundle

public function __construct(public array $anchorsPem, public string $bundleVersion, public string $bundleSha256)

public function containsFingerprint(string $anchorDerSha256Hex): bool
public static function computeBundleSha256(array $anchorsPem): string

TslSignatureException

public function __construct(public readonly string $reason, string $message)

TslSignatureException の理由コード: missing_signature、untrusted_signer、invalid_signature、digest_mismatch、unsupported_algorithm、unsupported_transform、expired_anchor。

動作契約

パイプラインの順序は固定です。フェッチ、XMLDSig 検証、構造パース、失効ゲートの順です。TslPolicyEnforcer は 4 段階すべてが成功した場合にのみ TslDocument を返します。トラステッドリストは、依拠当事者が真正性と完全性を確認できるよう、そのスキーム運営者によって署名されます — ETSI TS 119 612 §5.7.1。
TslXmlParser は設計上署名非依存です。呼び出し側は、パースされたフィールドを信頼する前に署名を検証しなければなりません。TslPolicyEnforcer::verifyXml() はその順序を強制します。
鮮度の不変条件は、すべてのコンシューマー境界で強制されます。nextUpdate を過ぎたリストは失効しており、拒否されます — ETSI TS 119 612 §5.3.15。verifyXml() は現在のシステム時刻に対してゲートし、TslDocument::assertFresh() と buildBundle() は呼び出し側が指定した時点に対してゲートします。
鮮度パースはフェイルクローズです。日時フィールドは明示的な指定子を伴う ISO 8601 UTC 値です — ETSI TS 119 612 §5.1.3。明示的な Z または数値オフセットを持たない nextUpdate は TslParseException を送出し、その値がサーバーのローカルタイムゾーンで再解釈されることは決してありません。
buildBundle() は、いかなるアンカーも抽出する前に assertFresh($now) を呼び出し、続いて granted かつ CA/QC の両方であるサービスのみを受け入れます。granted と withdrawn は適格サービスのステータス URI です — ETSI TS 119 612 §5.5.4。CA/QC は適格 CA のサービスタイプ URI です — ETSI TS 119 612 §5.5.1.1。
バンドルバージョンは、スキーム領域と TSL シーケンス番号から導出されます。シーケンス番号はリースをまたいで単調増加します — ETSI TS 119 612 §5.3.2。バンドルダイジェストはアンカー PEM に対する正準 SHA-256 であり、containsFingerprint() は DER SHA-256 によって所属を判定します。
検証器は設定されたアンカーのみを信頼します。KeyInfo に含まれる証明書は署名者リーフおよび候補中間証明書として機能します。チェーンは深さ 8 以内で設定されたアンカーへ到達しなければならず、すべてのリンクが時間的に有効でなければならず、発行証明書は basicConstraints cA=TRUE（keyUsage が存在する場合は keyCertSign も）を備えていなければなりません。
検証プロファイルはアローリストです。RSA または ECDSA と SHA-256、SHA-384、SHA-512 のいずれか、ダイジェストメソッドは SHA-256、SHA-384、SHA-512、排他的正準化のみ、そしてリストを網羅する ds:Reference 上での正確にエンベロープ型署名変換と排他的 C14N 変換のペアです。それ以外はすべて unsupported_algorithm または unsupported_transform で失敗します。
TslFetcher は非 HTTPS URL を拒否し、いかなる送信の前にも SSRF ガードを適用します。NetworkPolicy::STRICT_OFFLINE では、以前にキャッシュされたボディを提供するか、NetworkPolicyViolation を送出します。送信リクエストが発行されることは決してありません。

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

古いリスト。 verifyXml()、assertFresh()、buildBundle() からの TslParseException は、トラストソースが使用不能であることを意味します。署名の判定ではなく、運用上のリフレッシュ失敗として扱ってください。
非正準な nextUpdate。 明示的な Z または数値オフセットを持たない値は、寛容にパースするのではなくスローします。ETSI TS 119 612 §5.1.3 は UTC の Z 形式を義務付けており、ゲートは明示的な数値オフセットも受け入れ、それ以外はすべて拒否します。
使用時刻のドリフト。 verifyXml() は検証時刻でゲートします。nextUpdate を過ぎてもメモリ内に保持されたドキュメントは、後続の buildBundle($tsl, $now) ゲートでやはり失敗します。
空のアンカー設定。 TslSignatureVerifier は空のアンカーリストでの構築を拒否します（InvalidArgumentException）。
使用可能なサービスなし。 granted な CA/QC サービスを持たない新鮮なリストは、buildBundle() から TslParseException を送出します。空のバンドルが生成されることは決してありません。
オフライン姿勢。 キャッシュされたボディのない STRICT_OFFLINE は NetworkPolicyViolation を送出します。キャッシュ参照はポリシーチェックに先行するため、キャッシュされたリストによってエアギャップ環境での検証が引き続き機能します。
過大または空のレスポンス。 fetch() は最大 $maxBytes バイト（デフォルト 16 MiB）まで読み取ります。切り詰められたリストは、その後ダウンストリームのダイジェスト検証で失敗します。空のボディは TslFetchException を送出します。
XML 内の DOCTYPE。 いかなる DOCTYPE も、libxml がエンティティテーブルを構築する前と、ロード後の再度の両方で拒否されます。これにより XXE とエンティティ展開（billion-laughs）の入力クラスが閉じられます。
複数の署名。 検証済みのエンベロープ型 ds:Signature のみがダイジェスト計算の前に除去され、兄弟署名およびカウンター署名は保持されます。追加の XAdES 参照は許可されますが、ドキュメントルートを網羅する ds:Reference は正確に 1 つでなければなりません。
期限切れのチェーン素材。 期限切れまたは未発効の署名者、中間証明書、アンカーは、理由 expired_anchor で失敗します。clockTolerance は受け入れウィンドウを対称的に広げ、デフォルトは 0 です。

FIPS モードの動作

検証器のアローリストは RSA と ECDSA、SHA-2 ファミリーに固定されており、SHA-1 と MD5 は構造的に除外されます。署名演算はバンドルされたソフトウェア暗号（phpseclib）で実行されます。NextPDF はその演算について FIPS 140-3 検証の主張を行いません。Enterprise の FIPS 140-3 暗号ポリシープロファイルはセキュリティモジュールとともに文書化されており、アルゴリズム選択を制約しますが、トラステッドリストの構造やこのモジュールのフェイルクローズ動作は変更しません。

適合性

主張	標準	条項
Next update を過ぎたトラステッドリストは失効として破棄される。	ETSI TS 119 612	§5.3.15
日時フィールドは `Z` 指定子つきの UTC における ISO 8601 文字列である。	ETSI TS 119 612	§5.1.3
スキーム運営者は真正性と完全性のためにトラステッドリストに署名する。	ETSI TS 119 612	§5.7.1
適格サービスのステータスは granted または withdrawn のステータス URI である。	ETSI TS 119 612	§5.5.4
適格 CA は `Svctype/CA/QC` サービスタイプ URI によって識別される。	ETSI TS 119 612	§5.5.1.1
TSL シーケンス番号は 1 から始まり、各リリースで増加する。	ETSI TS 119 612	§5.3.2

すべての条項は言い換えであり、NextPDF は規範テキストを複製しません。NextPDF は ETSI TS 119 612 への適合性の主張も、eIDAS 認証の主張も行いません。 トラステッドリストを消費しても、署名、証明書、または NextPDF の出力が「適格（qualified）」になるわけではありません。適格性は加盟国の監督下にあるトラストサービスプロバイダーに帰属し、法的効果はこのモジュールの範囲外です。XMLDSig 処理モデルの制約（エンベロープ型署名変換、排他的正準化、ルートを網羅する参照）は製品の検証プロファイルから文書化されており、W3C XML Signature 仕様は引用済みの証拠集合の範囲外です。このモジュールは、リストがトラスト入力として受け入れ可能かどうかのみを判定します。結果として得られるアンカーに対する証明書パス検証は、証明書検証レイヤーに帰属します。

開発上の注意

依存は PSR インターフェースです。PSR-18 クライアント、PSR-17 リクエストファクトリ、そしてオプションの PSR-16 キャッシュです。テストではインメモリのダブルを注入してください。コールドな fetch() を除き、どの段階もライブネットワークアクセスを必要としません。
トップアンカーは帯域外でピン留めしてください。加盟国リストの場合、LOTL アンカーがリスト署名者を認可します。検証器が KeyInfo の内容からトラストをブートストラップすることは決してありません。
バックグラウンドポーリング、ピボット LOTL 処理、相互 TLS またはプロキシ認証は、このバージョンではフェッチャーの範囲外です。リフレッシュは外部でスケジュールし、各 nextUpdate の前に再フェッチしてください。
buildBundle() には、構築時点ではなく検証時点を渡してください。各リフレッシュの後にバンドルを再構築し、ソースリストの nextUpdate を過ぎたバンドルを決してキャッシュしないでください。
bundleVersion は tsl-<territory>-seq<sequenceNumber> という観測可能な形状を持ちます。TslDocument の rawXmlSha256 は証拠記録とリプレイ検出を支援します。
不正な形式のサービスエントリは防御的なプレースホルダー値でパースされます。バンドル構築に到達する不正な形式のデジタルアイデンティティは InvalidArgumentException でフェイルクローズします。
これらのクラスはパッケージの @since 1.10.0 ソース注釈を持ちます（TslFetchException は 3.2.0）。TslDocument、TspService、TspServiceQualifier はソース注釈 @api を持ちます。

公開境界

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