Pro エディション

クラウド KMS 署名 — 詳細リファレンス

概要

このページは、NextPDF Pro のクラウド KMS 署名サーフェスの契約レベルのリファレンスです。このサーフェスは、1 つの Service Provider Interface である NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface と、3 つのプロバイダー署名器 AwsKmsSigner、AzureKeyVaultSigner、GcpKmsSigner で構成されます。2 つのアダプター AwsKmsSigningStrategy と AzureKeyVaultSigningStrategy が、署名器を Pro の SigningStrategy 契約へと橋渡しします。各署名器は、PSR-18 HTTP 経由でメッセージダイジェストのみをプロバイダーに送信します。秘密鍵とドキュメントは境界を越えることがありません。このページでは、公開 API、観測可能な動作契約、そして型付けされた失敗モードを規定します。セッションのオーケストレーション（RemoteSigningSession、SequentialSigner）とタイムスタンプ（PadesBtTimestamper）は、それぞれ独自のページで扱います。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得する。

公開 API サーフェス

シンボル	パラメータ	既定の動作	戻り値	スロー/失敗	備考
`KmsSignerInterface`	—	Core の `HsmSignerInterface` 契約を拡張	—	—	KMS および HSM ドライバー向けの SPI。予約済み組み込み ID: `aws-kms`、`azure-keyvault`、`gcp-kms`、`pkcs11`、`openssl-cli`
`KmsSignerInterface::providerId()`	なし	安定したレジストリ検索キー	`non-empty-string`	—	サードパーティ製ドライバーは識別子に名前空間を付ける必要あり
`KmsSignerInterface::signWithVersion()`	`$data`、`$algorithm = 'sha256WithRSAEncryption'`、`$keyVersion = null`	`null` のキーバージョンはプロバイダー既定にフォールバック	`string` の署名オクテット: RSA はプロバイダーが返したまま（直接 `SignerInfo.signature` に配置）、ECDSA は CMS 規則に従い DER `ECDSA-Sig-Value` として	`KeyManagementException`、`UnsupportedAlgorithmException`、`SignatureFailedException`	プロバイダーごとに `null` のセマンティクスが異なる。動作契約を参照
`KmsSignerInterface::supportsAlgorithm()`	`string $algorithm`	能力プローブ。I/O は行わない	`bool`	—	プロバイダー選択前に呼び出される
`KmsSignerInterface::supportedAlgorithms()`	なし	プロバイダーが受け付ける OpenSSL 形式の名前を列挙	`list<non-empty-string>`	—	—
`AwsKmsSigner`	コンストラクタ: `AwsKmsConfig`、証明書 DER、チェーン DER、PSR-18 クライアント、PSR-17 ファクトリ、PSR-3 ロガー	アルゴリズムは `KmsSigningAlgorithm::RsaPkcs1Sha256` が既定	—	メソッドを参照	`final`。`PROVIDER_ID = 'aws-kms'`
`AwsKmsSigner::create()`	キー ID、証明書 DER、PSR 依存、任意のチェーン、config、logger	`$config` が `null` のとき `AwsKmsConfig::fromEnvironment($keyId)` を構築	`self`	—	標準の `AWS_*` 環境変数を読み取る
`AwsKmsSigner::withAlgorithm()`	`KmsSigningAlgorithm $algorithm`	変更したクローンを返す	`self`	—	AWS KMS にプロビジョニングされたキー種別に一致する必要あり
`AwsKmsSigner::sign()`	`$data`、`$algorithm = 'sha256WithRSAEncryption'`	`signWithVersion($data, $algorithm, null)` に委譲	`string`	`signWithVersion()` と同じ	レガシーな 2 引数の Core 契約パス
`AzureKeyVaultSigner`	コンストラクタ: `AzureKeyVaultConfig`、証明書 DER、チェーン DER、PSR-18 クライアント、PSR-17 ファクトリ、PSR-3 ロガー	アルゴリズムは `AzureSigningAlgorithm::Rs256` が既定。config のアクセストークンがベアラートークンの起点となる	—	メソッドを参照	`final`。`PROVIDER_ID = 'azure-keyvault'`
`AzureKeyVaultSigner::create()`	vault 名、キー名、証明書 DER、PSR 依存、任意のチェーン、config、logger	`$config` が `null` のとき `AzureKeyVaultConfig::fromEnvironment()` を構築	`self`	—	取得済みトークンまたはサービスプリンシパル資格情報をサポート
`AzureKeyVaultSigner::withAlgorithm()`	`AzureSigningAlgorithm $algorithm`	変更したクローンを返す	`self`	—	RSA キーは RS/PS 値、EC キーは ES 値を使用
`GcpKmsSigner`	コンストラクタ: `GcpKmsConfig`、証明書 DER、チェーン DER、PSR-18 クライアント、PSR-17 ファクトリ、PSR-3 ロガー	アルゴリズムは `GcpKmsSigningAlgorithm::RsaSignPkcs1_2048Sha256` が既定	—	メソッドを参照	`final`。`PROVIDER_ID = 'gcp-kms'`、`API_VERSION = 'v1'`
`GcpKmsSigner::create()`	プロジェクト ID、ロケーション、キーリング、暗号鍵、証明書 DER、PSR 依存、任意のチェーン、config、logger	`$config` が `null` のとき `GcpKmsConfig::fromEnvironment()` を構築	`self`	—	ベアラートークンの取得は呼び出し側に委譲
`GcpKmsSigner::withAlgorithm()`	`GcpKmsSigningAlgorithm $algorithm`	設定時のプレビューのみ。署名時は呼び出しごとのワイヤ名が優先	`self`	—	キーサイズはプロビジョニング済みの CryptoKeyVersion で固定
`AwsKmsSigningStrategy`	コンストラクタ: `AwsKmsSigner $signer`	同期。`isAsync()` は `false` を返す	—	ラップした署名器の例外を伝播	`RemoteSigningSession::complete()` 向けアダプター
`AzureKeyVaultSigningStrategy`	コンストラクタ: `AzureKeyVaultSigner $signer`	同期。`isAsync()` は `false` を返す	—	ラップした署名器の例外を伝播	`RemoteSigningSession::complete()` 向けアダプター
`KmsSigningAlgorithm`	列挙型、9 ケース（RSA PKCS#1、RSA-PSS、ECDSA; SHA-256/384/512）	—	AWS KMS `SigningAlgorithm` のワイヤ値	`fromOpenSslName()` からの `InvalidArgumentException`	`resolveForWireName()` は設定された PSS ダイジェストを保持
`AzureSigningAlgorithm`	列挙型、9 ケース（`RS256`…`ES512`）	—	Azure Key Vault の JWA 形式の値	`fromOpenSslName()` からの `InvalidArgumentException`	`isEcdsa()` は出力の DER 変換が必要な値を印付ける
`GcpKmsSigningAlgorithm`	列挙型、10 ケース（EC P-256/P-384、RSA PKCS#1、RSA-PSS）	—	GCP CryptoKeyVersion のアルゴリズム値	`fromOpenSslName()` からの `UnsupportedAlgorithmException`	ワイヤ名の解決は一致する最小のキーサイズを選択

エントリーポイントのシグネチャ

public function providerId(): string;

public function signWithVersion(
    string $data,
    string $algorithm = 'sha256WithRSAEncryption',
    ?string $keyVersion = null,
): string;

public function supportsAlgorithm(string $algorithm): bool;

public function supportedAlgorithms(): array;

public static function create(
    string $keyId,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?AwsKmsConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(KmsSigningAlgorithm $algorithm): self

public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string

public static function create(
    string $vaultName,
    string $keyName,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?AzureKeyVaultConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(AzureSigningAlgorithm $algorithm): self

public static function create(
    string $projectId,
    string $location,
    string $keyRing,
    string $cryptoKey,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?GcpKmsConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(GcpKmsSigningAlgorithm $algorithm): self

public function __construct(
    private AwsKmsSigner $signer,
) {}

public function sign(string $signedAttributesDer): string

public function __construct(
    private AzureKeyVaultSigner $signer,
) {}

public function sign(string $signedAttributesDer): string

動作契約

契約の解決

KmsSignerInterface は Core の HsmSignerInterface 契約を拡張します。これは providerId()、キーバージョンを認識する signWithVersion()、そして supportsAlgorithm() と supportedAlgorithms() の能力プローブを追加します。継承された 2 引数の sign() は、3 つの署名器すべてで null のキーバージョンを指定して signWithVersion() に委譲します。getCertificateDer()、getCertificateChainDer()、getPublicKeyAlgorithm() は、コンストラクタで供給されたマテリアルから実装されます。能力プローブは I/O を行いません。各署名器は、検査用に getSigningAlgorithm() と getConfig() のアクセサも公開します。

ダイジェストのみの送信

各署名器は、解決されたアルゴリズムのダイジェストで $data をローカルにハッシュ化し、そのダイジェストのみを送信します。AWS は MessageType: DIGEST を伴う base64 のダイジェストを受け取ります。Azure は sign リクエストのボディで base64url のダイジェストを受け取ります。GCP はアルゴリズム固有のダイジェストフィールドで base64 のダイジェストを受け取ります。ドキュメントのバイトがプロバイダーのリクエストに現れることはありません。すべてのトランスポートは、プロバイダーの HTTPS エンドポイント上で標準的な PSR-18 HTTP クライアントを使用します。クラウドベンダーの SDK は一切関与しません。

キーバージョンの解決

signWithVersion() は、いかなるリクエストが構築されるよりも前に、キーバージョン引数をフェイルクローズで検証します。プロバイダーの文法に適合しない値は KeyManagementException を送出し、URL セグメントや KeyId のインジェクションを防ぎます。

プロバイダー	`null` キーバージョン	空文字列	オーバーライドの文法
`AwsKmsSigner`	`AwsKmsConfig::$keyId` を使用。エイリアスや ARN はプロバイダー側で現在のキーに解決される	拒否	UUID（ダッシュあり/なし）、`alias/<name>`、または KMS キー/エイリアスの ARN
`AzureKeyVaultSigner`	設定されたキーバージョンを使用。空の config 値はサーバー側で最新の有効バージョンを選択する	拒否	32 文字の 16 進識別子
`GcpKmsSigner`	`GcpKmsConfig` にピン留めされたバージョンを使用。ピン留めがない場合は `KeyManagementException` を送出	拒否	10 進の CryptoKeyVersion ID、数字のみ

GCP にはサーバー側の「アクティブバージョン」プリミティブがありません。非対称署名エンドポイントは特定の cryptoKeyVersions/{n} リソースに対してのみ動作するため、バージョンは常に解決可能でなければなりません。

アルゴリズムの解決

ストラテジー層は OpenSSL 形式のワイヤ名を転送します。AWS と Azure は 7 つのワイヤ名（SHA-256/384/512 での PKCS#1 と ECDSA、加えて RSASSA-PSS）を受け付けます。GCP は 5 つ（sha256WithRSAEncryption、sha512WithRSAEncryption、RSASSA-PSS、ecdsa-with-SHA256、ecdsa-with-SHA384）を受け付けます。RSASSA-PSS のワイヤ名はダイジェストをエンコードしないため、ダイジェストが曖昧です。AwsKmsSigner はこれを KmsSigningAlgorithm::resolveForWireName() を通じて解決し、設定された PSS バリアントのダイジェストを保持します。AzureKeyVaultSigner は、この曖昧な名前について設定された PSS バリアントを信頼します。解決された PSS ダイジェストが設定されたものと食い違う場合は UnsupportedAlgorithmException を送出します。GcpKmsSigner は呼び出しのたびにワイヤ名から列挙型を再解決します。GCP における withAlgorithm() は設定時のプレビューであり、署名時の動作を変更しません。サポートされないワイヤ名は、いかなるネットワーク呼び出しよりも前に UnsupportedAlgorithmException を送出します。AwsKmsSigner と GcpKmsSigner では、sign 呼び出しが後で getSigningAlgorithm() によって報告される値を、解決された呼び出しごとのアルゴリズムに更新します。AzureKeyVaultSigner では、解決は呼び出しローカルであり、設定された値が権威を保ちます。

署名の正規化

AWS と GCP は、CMS が消費する形式で署名を返します。RSA の署名オクテットはそのまま SignerInfo.signature に入り、ECDSA は DER エンコードされて到着します。Azure は ECDSA を生の IEEE P1363（r||s）形式で返しますが、署名器はこれを返す前に DER ECDSA-Sig-Value に変換します。

CMS 統合と隣接領域

SigningStrategy アダプターは、セッションから供給された DER エンコード済みの署名対象属性に署名します。署名対象属性が存在する場合、CMS の署名入力は SignedAttrs 値の完全な DER エンコードのダイジェストです — RFC 5652 §5.4。アダプターの getSignatureAlgorithmOid() と getDigestAlgorithm() は、SignerInfo の signatureAlgorithm および digestAlgorithm フィールドに供給されます — RFC 5652 §5.3。返されたバイトは SignerInfo の署名 OCTET STRING になります — RFC 5652 §5.5。CMS の組み立て、ByteRange の処理、セッションのライフサイクルは RemoteSigningSession に属し、複数者フローは SequentialSigner に属します。messageImprint が SignerInfo の署名値をハッシュ化する PAdES B-T 署名タイムスタンプ — RFC 3161 Appendix A — は、これらの署名器ではなく PadesBtTimestamper によって適用されます。3 つすべては Pro セキュリティ詳細リファレンスに記載されています。

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

空文字列のキーバージョンは 3 つのプロバイダーすべてで拒否されます。設定された既定を継承するには null を渡してください。
不正なキーバージョンは、いかなるリクエストが構築されるよりも前に拒否され、問題の値が例外内で明示されます。
空の AwsKmsConfig::$keyId と null のキーバージョンを伴う AwsKmsSigner は KeyManagementException を送出します。
キー管理の失敗を示すプロバイダー応答は KeyManagementException にマップされます。AWS の NotFoundException、DisabledException、KeyUnavailableException、InvalidKeyUsageException、または HTTP 404、Azure の HTTP 404、KeyNotFound、KeyDisabled、または KeyNotActive、GCP の HTTP 404 または 409、NOT_FOUND、FAILED_PRECONDITION、あるいはバージョンを名指しするメッセージを持つ HTTP 400 です。
その他の非 200 のプロバイダー応答は、AWS と GCP では SignatureFailedException、Azure では AzureKeyVaultException を送出します。
署名中の PSR-18 トランスポート失敗は、クライアント例外を前段のスロー可能オブジェクトとして保持しつつ SignatureFailedException にマップされます。
アクセストークンもサービスプリンシパル資格情報も持たない AzureKeyVaultSigner は、いかなる vault 呼び出しよりも前に AzureKeyVaultException を送出します。Azure AD トークン取得の失敗も AzureKeyVaultException を送出します。
AzureKeyVaultSigner は、リクエストのチョークポイントで vault 名、キー名、キーバージョン、テナント ID を Azure の公表された文法に照らして検証します。URL 構造上の文字を含む値はフェイルクローズし、AzureKeyVaultException となります。
OAuth2 ベアラートークンを持たない GcpKmsSigner は SignatureFailedException を送出します。トークンの取得は呼び出し側の責任です。
有効な JSON ではない、または署名フィールドを欠くプロバイダー応答は SignatureFailedException を送出します（Azure: value フィールドの欠落は AzureKeyVaultException を送出）。
base64 デコードに失敗するプロバイダーの署名フィールドは、AWS と GCP では SignatureFailedException、Azure では AzureKeyVaultException を送出します。
GcpKmsSigner 向けの SigningStrategy アダプターは 3.1.0 では同梱されません。GCP 署名器は KmsSignerInterface 契約を通じて直接消費されます。

FIPS モードの動作

AwsKmsConfig::withFipsEndpoint() は、リクエストをリージョンの kms-fips エンドポイントへルーティングします。そのエンドポイントの FIPS 検証ステータスは AWS の属性であり、NextPDF の属性ではありません。AzureKeyVaultConfig と GcpKmsConfig は 3.1.0 では専用の FIPS エンドポイントヘルパーを公開しません。ダイジェスト計算は PHP の hash() 関数でインプロセスに実行され、それ自体は検証済みモジュールではありません。NextPDF Pro は FIPS 検証済みの KMS または HSM 境界に対して動作できますが、NextPDF は FIPS 検証済みの暗号モジュールではなく、FIPS 認証の主張は一切行いません。

適合性

主張	標準	節
ストラテジーは DER エンコード済みの署名対象属性に署名する。CMS の署名入力ダイジェストは SignedAttrs の完全な DER エンコードをカバーする。	RFC 5652	§5.4
SignedAttributes は DER エンコードされ、最低限 content-type と message-digest を保持する。signatureAlgorithm は署名器のアルゴリズムを識別する。	RFC 5652	§5.3
返される署名バイトは OCTET STRING としてエンコードされ、SignerInfo の署名フィールドに保持される。	RFC 5652	§5.5
署名タイムスタンプの messageImprint は SignerInfo の署名値をハッシュ化する（隣接する B-T サーフェスであり、これらの署名器ではない）。	RFC 3161	Appendix A

すべての節は言い換えであり、NextPDF は規範テキストを再現しません。これらは能力の記述であって、認証ではありません。NextPDF はいかなる認証も保有せず、いかなる認証も付与しません。生成された署名が検証されるかどうかは、検証者自身のトラストアンカーとポリシーに照らした検証者の判断です。署名器は署名バイトを返すだけで、信頼された結果を主張しません。キーの保管、キーの保護、プロバイダー側のアルゴリズム検証は、設定された KMS の属性であり、NextPDF の属性ではありません。

開発上の注意

Pro パッケージ内での提供状況: AwsKmsSigner は 1.9.0 以降、AzureKeyVaultSigner は 2.0.0 以降、GcpKmsSigner と KmsSignerInterface は 2.1.0 以降。すべて nextpdf/pro 3.1.0 で現行です。
署名器は PSR-18、PSR-17、PSR-3 のみに依存します。AWS、Azure、Google のいずれの SDK も必須ではなく、同梱もされません。
互換性のないプロバイダーがセッション途中ではなく選択時に拒否されるよう、署名前に supportsAlgorithm() をプローブしてください。
資格情報フィールドはコンストラクタ注入され、機密パラメータとして印付けられています。ログメッセージは構造的フィールドのみを含み、資格情報、トークン、ドキュメント内容がログに書き込まれることはありません。
規制対象のデプロイではキーバージョンを明示的にピン留めしてください。エイリアス解決（AWS）や最新有効バージョン（Azure）の既定は便利ですが、ローテーションをまたいで決定論的ではありません。
サードパーティ製ドライバーは KmsSignerInterface を実装し、予約済みの組み込み識別子との衝突を避けるために providerId() に名前空間を付ける必要があります。

公開範囲の境界

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