Enterprise エディション

Contracts — 詳細リファレンス

概要

Contracts モジュールは、RFC 3161 Time Stamp Authority クライアントのための Enterprise 連携シームです。

TsaClientInterface は 1 つの操作を宣言します。事前計算されたドキュメントダイジェストに対する DER エンコードされた TimeStampToken をリクエストします。
TsaClientAdapter は、final クラスである Core のタイムスタンプクライアントを、挙動を変えずにそのインターフェイスへ橋渡しします。
LtvManager や DocumentTimestamp などの Enterprise コンポーネントはこのインターフェイスを受け取るため、TSA の挙動はテストで注入・差し替え可能です。
シームを越えるのはドキュメントハッシュのみです。ドキュメントコンテンツが越えることはありません。

ワークフローのガイダンスについては、まず Contracts 機能ページをお読みください。

提供状況とライセンス

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

インターフェイス自体は何の処理も行わず、単独でゲートを行うこともありません。利用する Enterprise サーフェスは、コンプライアンス証跡サーフェスにおける enterprise.compliance.evidence のような、独自の機能コードを適用します。

ティア	提供内容
Core	RFC 3161 リクエストを実行する具体的な `TsaClient`（`final`）
Pro	Contracts モジュールの同等品なし
Enterprise	`TsaClientInterface` シームと `TsaClientAdapter` ブリッジ

composer require nextpdf/enterprise:^3

パブリック API サーフェス

シンボル	パラメーター	デフォルトの挙動	戻り値	スロー/失敗	備考
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	事前計算されたドキュメントダイジェストに対するタイムスタンプトークンリクエストを宣言	`string` — DER エンコードされた TimeStampToken	実装依存。インターフェイスは例外を宣言しない	唯一の操作。ソースは SHA-256 ダイジェスト入力を記載
`TsaClientAdapter::__construct()`	`TsaClient $client`	Core のタイムスタンプクライアントを保持	`TsaClientAdapter`	宣言なし	`final readonly`。コンストラクタープロモーション
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	`TsaClient::getDocumentTimestamp()` へそのまま転送	`string` — DER エンコードされた TimeStampToken	Core クライアントからの `TsaException` をそのまま転送	挙動を追加しない。何も握りつぶさない

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

挙動コントラクト

TsaClientInterface::getDocumentTimestamp(string $documentHash): string は、ドキュメントハッシュに対する DER エンコードされた RFC 3161 TimeStampToken を返します。外部から観測可能なルールは次のとおりです。

このインターフェイスは 1 つの操作を宣言します。トークンを検証したり、TSA を保証したり、法的効力を主張したりすることはありません。
TsaClientAdapter は、呼び出しを Core のタイムスタンプクライアントへそのまま転送します — 追加の挙動なし、追加のリトライなし、例外の握りつぶしなし、追加の保証なし。その唯一の目的は、final な Core クライアントが、依存性逆転とテストのために Enterprise 向けのインターフェイスを満たせるようにすることです。
境界を越えるのはドキュメントハッシュのみです。ドキュメントコンテンツは渡されません。
アダプターの背後では、Core クライアントは、設定されたインプリントアルゴリズムと長さが一致しないダイジェストを、いかなるネットワーク活動よりも前に、フェイルクローズドで TsaException により拒否します。そうでなければ、誤ってラベル付けされたインプリントは、適合するバリデーターが結び付けられないトークンを生成してしまいます。
利用するサーフェス: LtvManager は任意の TsaClientInterface を受け取り、PAdES B-LTA では必須とします。DocumentTimestamp はこのコントラクトを使用して、/DocTimeStamp 署名ディクショナリの /Contents を埋めます。LTV アーカイブ更新エグゼキューター（LtvaRenewalExecutor）は、ドキュメントタイムスタンプを更新する際に Core クライアントの周りに TsaClientAdapter を配線します。

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

アダプターは、基盤となるクライアントからの例外をそのまま転送します。TSA の失敗は呼び出し箇所で処理しなければなりません。
ダイジェストは、具体的なクライアントに設定されたインプリントアルゴリズム（デフォルト SHA-256、32 バイト）における生のバイナリでなければなりません。16 進エンコードされたダイジェストは長さが誤っており、リクエストが送信される前に拒否されます。
返されるトークンは判定ではなくバイト列です。必要な箇所で検証してください。
カスタム実装は、独自の失敗サーフェスを所有します。コントラクトが固定するのは戻り値の形状のみです。すなわち DER エンコードされた TimeStampToken です。

FIPS モードの挙動

このモジュールは暗号操作を一切実行しません。アルゴリズムの選択と FIPS モードの挙動は、具体的な TSA クライアントと Security モジュールが管理します。FIPS 140 詳細リファレンスを参照してください。

適合性

挙動	参照
タイムスタンプトークンのリクエストと結び付け	IETF RFC 3161 §2
TimeStampReq は MessageImprint を保持する。すなわちハッシュアルゴリズム識別子と、タイムスタンプ対象データのハッシュ	IETF RFC 3161 §2.4.1
トークンの messageImprint はリクエストの値と等しくなければならず、ハッシュサイズは識別されたアルゴリズムと一致	IETF RFC 3161 §2.4.2

コントラクトは RFC 3161 に沿って形作られています。実際のトークンリクエストおよび検証は、具体的なクライアントと Evidence/Signature サーフェスが実行します。インターフェイスは適合性や証明の主張を行いません。NextPDF は認証の主張を一切行いません。

開発上の注意

両方の型は @since 3.0.0 を持ちます。このリファレンスは、nextpdf/enterprise 3.1.0 で出荷されたサーフェスを記載しています。
タイムスタンプを必要とするコンポーネントには TsaClientInterface を注入します。コンポジションルートで TsaClientAdapter、またはカスタム実装を配線してください。ユニットテストでは、稼働中の TSA の代わりにテストダブルを差し替えます。
オペレーターは、アダプターの背後にある具体的な TSA クライアントを所有します。レジデンシー、TSA エンドポイントの信頼境界、および証明書チェーンの検証は、このインターフェイスではなく、そのクライアントに適用されます。
このコントラクトサーフェスには輸出管理の制限は適用されません。タイムスタンプトークンの取得は、監査および長期検証ワークフローをサポートします。法的な証明や認証ではありません。このリファレンスは法的意見ではありません。
内部メカニズムの詳細は、ソースリポジトリの内部ドキュメントに留まり、このマニュアルの対象外です。

公開範囲の境界

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