Enterprise エディション

セキュリティ — 詳細リファレンス（HSM、PKCS#11、FIPS モード）

概要

このページは、NextPDF Enterprise セキュリティサーフェスの統合詳細リファレンスです。PKCS#11 によるハードウェアトークン署名、OpenSSL コマンドラインインターフェース（CLI）を介したサブプロセス署名、FIPS 暗号ポリシープリセット、実行時 FIPS ガード、電源投入時セルフテストガードを扱います。2 つの焦点を絞ったコンパニオンがあります。署名者の詳細については HSM — 詳細リファレンス、FIPS モジュールの詳細については FIPS 140 — 詳細リファレンスです。ポスト量子署名パスは、適合性の主張を伴わないプレビューです。NextPDF はいかなる認証も保有せず、付与もしません。サポートは適合性と等しくなく、適合性は認証と等しくありません。

提供とライセンス

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

パブリック API サーフェス

composer require nextpdf/enterprise:^3

署名型は NextPDF\Enterprise\Security\Signature\Hsm に、FIPS 型は NextPDF\Enterprise\Security\Fips に、コンポジションルートは NextPDF\Enterprise\Bootstrap にあります。どちらの署名者も、Core の NextPDF\Contracts\HsmSignerInterface コントラクトを実装します。ポリシーは、Core の NextPDF\Contracts\CryptoPolicyInterface および NextPDF\Contracts\PreOperationalSelfTestInterface コントラクトを実装します。

シンボル	パラメーター	デフォルト挙動	戻り値	スロー/失敗条件	備考
`Pkcs11Signer::__construct()`	`string $libraryPath`, `int $slotId`, `string $pin`, `string $certLabel`, `?string $keyLabel = null`, `array $chainDer = []`, `bool $enablePostQuantum = false`, `?FipsSignatureEnforcer $fipsEnforcer = null`	ベンダーライブラリを開き、スロットにログインし、証明書と鍵アルゴリズムのメタデータをロード	—	`ext-pkcs11` がない、またはトークンアクセスが失敗した場合に `HsmOperationException`	PIN とラベルは `#[SensitiveParameter]`。モジュールハンドルはプロセスごと・ライブラリパスごとに 1 つキャッシュ
`Pkcs11Signer::isAvailable()`	なし	`ext-pkcs11` がロードされているかを報告	`bool`	なし	静的。構築前にチェック
`Pkcs11Signer::sign()`	`string $data`, `string $algorithm = 'sha256WithRSAEncryption'`	トークン上で署名。生の ECDSA 出力は DER 形式の `ECDSA-Sig-Value` に変換	`string`（生の署名バイト）	`HsmOperationException`（鍵が見つからない、トークン障害）、`InvalidArgumentException`（マッピングされていないアルゴリズム）、エンフォーサーが配線されている場合は署名前に `FipsViolationException` / `FipsModuleErrorStateException`	閉じたアルゴリズム集合。挙動契約を参照
`Pkcs11Signer::signPqs()`	`string $data`, `Pkcs11PqsAlgorithm $algorithm`, `string $context = ''`, `bool $randomized = true`	`$enablePostQuantum` が設定されていない限り拒否。暫定的な PKCS#11 ポスト量子メカニズムをディスパッチ	`string`（生の署名バイト）	`HsmOperationException`（無効化、トークン障害、署名長の不一致）、`InvalidArgumentException`（コンテキストが 255 バイト超）	プレビュー。適合性の主張なし
`Pkcs11Signer` アクセサーサーフェス	なし	読み取り専用の構築結果	`bool` / `string` / `array<string>`	なし	`isPostQuantumEnabled`, `getCertificateDer`, `getCertificateChainDer`, `getPublicKeyAlgorithm`
`OpenSslCliSigner::__construct()`	`string $keyUri`, `string $certPath`, `string $pin`, `array $extraCertPaths = []`, `OpenSslCliBackend $backend = OpenSslCliBackend::Auto`, `string $opensslBinary = 'openssl'`, `int $timeoutSeconds = 30`, `?string $modulePath = null`, `?string $configPath = null`, `bool $legacyPinDelivery = false`, `?FipsSignatureEnforcer $fipsEnforcer = null`	`proc_open` を検証し、バイナリをプローブし、バックエンドを解決し、証明書をロード	—	`HsmOperationException`（`proc_open` の無効化、モジュール/構成/証明書ファイルの欠落、バックエンドなし）、`InvalidArgumentException`（`$keyUri` 内の `pin-value`）	`Auto` は OpenSSL 3.x プロバイダーを優先し、次にエンジン
`OpenSslCliSigner::sign()`	`string $data`, `string $algorithm = 'sha256WithRSAEncryption'`	`openssl` サブプロセスで署名。PIN はデフォルトで一時的な `0600` の pin-source ファイルを経由	`string`（生の署名バイト）	`HsmOperationException`（タイムアウト、PIN 拒否、鍵が見つからない、空出力）、`InvalidArgumentException`（マッピングされていないアルゴリズム）、署名前の FIPS ゲート例外	サブプロセスは `$timeoutSeconds` 後に強制終了。stderr はレダクト
`OpenSslCliSigner` アクセサーサーフェス	なし	読み取り専用の構築結果	`string` / `array<string>` / `OpenSslCliBackend`	なし	`getCertificateDer`, `getCertificateChainDer`, `getPublicKeyAlgorithm`, `getCertificatePem`, `getResolvedBackend`, `getOpensslVersion`
`OpenSslCliBackend`	—	列挙型: `Provider`、`Engine`、`Auto`	—	なし	CLI 署名者のバックエンド選択
`Pkcs11PqsAlgorithm`	—	ML-DSA および SLH-DSA のパラメーターセットの列挙型	—	なし	ヘルパー: `isMlDsa`, `isSlhDsa`, `mechanismId`, `parameterSetId`, `signatureLength`, `nistCategory`
`PqsCapabilityStatus::current()`	なし	プロセスの正直なポスト量子ポスチャーを構築	`PqsCapabilityStatus`	なし	すべての適合性主張のブール値はハードコードで `false`。どのフラグでもオンに切り替え不可
`HsmSignerProviderAdapter`	`HsmSignerInterface $hsm`, `string $providerId`, `SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15`	HSM の具象を統一された `SignerProviderInterface` として公開	SPI に準拠	`KeyManagementException`（非 null の鍵バージョン）、`SignatureFailedException`（ドライバー障害、空署名）	プロバイダー ID: `pkcs11-{module-id}`、`openssl-cli`
`HsmOperationException`	—	すべての HSM 署名パスの型付き失敗	—	—	Core の `NextPdfException` を継承
`FipsCryptoPolicy::strict()` / `::standard()`	`?FipsSelfTest $selfTest = null`	ファクトリプリセット。strict は FIPS 140-3 プロファイル、standard は AES-128-CBC を追加	`FipsCryptoPolicy`	なし	不変の許可リスト。FIPS モード挙動を参照
`FipsCryptoPolicy` 述語サーフェス	`string` / `int` 入力	許可リストのメンバーシップチェック	`bool` / `string`	なし	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsCryptoPolicy::assertPreOperational()`	なし	電源投入時セルフテストを実行（または再生）	`void`	`FipsModuleErrorStateException`	最初の暗号操作時に Core のエンフォースメントシームによって駆動
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	ポリシーをアサート形式の境界でラップ	—	なし	ブートガードがない場合、セルフテストゲートは存在しない（ポリシーのみ）
`FipsModeGuard` アサートサーフェス	`string` / `int` 入力	まず拒否カタログ、次に許可リスト。スローの前に監査記録	`void`	`FipsViolationException`、`FipsModuleErrorStateException`（ブートガード配線時）	`assertHashAllowed`, `assertSignatureAlgorithmAllowed`, `assertEncryptionAllowed`, `assertKeyStrengthAllowed`、および `getPolicy`
`FipsBootGuard::report()` / `::rerun()`	なし	セルフテストバッテリーを実行（キャッシュ/強制）	`FipsSelfTestReport`	なし	ERROR レポートはプロセスをラッチ。合格した再実行でもラッチは解除されない
`FipsBootGuard::assertOperational()`	なし	モジュールが OPERATIONAL であることをアサート	`void`	`FipsModuleErrorStateException`	スティッキー。プロセスにラッチされた ERROR はクリーンなインスタンスでも拒否
`FipsBootGuard::status()`	なし	キャッシュされたステータスを報告	`FipsSelfTestStatus`	なし	`PRE_OPERATIONAL`、`OPERATIONAL`、または `ERROR`
`FipsSelfTest::run()`	なし	完全な既知応答テストバッテリーを実行。決して短絡しない	`FipsSelfTestReport`	なし	コンストラクターは、決定論的テストのために注入可能なハッシュおよびランダムバイトプロバイダーを受け付ける
`FipsSelfTestReport` / `FipsSelfTestResult` / `FipsSelfTestStatus`	—	レポートの値オブジェクトとステータス列挙型	—	`FipsSelfTestReport::assertOperational()` は `FipsModuleErrorStateException` をスロー	`results` は監査証跡のために常にすべての結果を列挙
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	署名 OID と鍵強度を解決し、ガードに委譲	`void`	`FipsViolationException`（許可されていない、または分類不能。フェイルクローズ）	FIPS モードで両署名者が `sign()` の先頭で呼び出すチョークポイント
`FipsAuditLogger`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	決定ごとに ALLOW（INFO）/DENY（WARNING）レコードを発行	ログ呼び出しごとに `bool`	なし	`logHashOperation`, `logSignatureOperation`, `logEncryptionOperation`, `logKeyStrengthCheck`
`FipsTransitioningAlgorithms`	`string` / `int` 入力	静的な NIST SP 800-131A 拒否カタログ	`bool` / `array`	なし	すべてのガード境界の下にある明示的拒否レイヤー
`FipsBootstrap::boot()` / `::lazy()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`, `?LoggerInterface $auditLogger = null`	ブートガード、ポリシー、モードガードを構成。`boot()` はセルフテストを即座に実行し、`lazy()` は最初の境界まで遅延	`FipsModeGuard`	`boot()`: テスト失敗時に `FipsModuleErrorStateException`	デフォルトは strict ポリシー
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	モジュールをブートし、署名者のための生成時ゲートを返す	`FipsSignatureEnforcer`	`FipsModuleErrorStateException`	結果を署名者の `$fipsEnforcer` パラメーターに渡す
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	オンデマンドでバッテリーを実行し、要約する	`array{status, operational, failed}`	なし	ヘルスエンドポイントおよび CLI サブコマンド向け
`FipsViolationException` / `FipsModuleErrorStateException`	—	型付きの FIPS 失敗	—	—	それぞれ `policyName` / `violatingItem` / `reason` および `failedResults` を公開

public function __construct(private readonly string $libraryPath, private readonly int $slotId, #[SensitiveParameter] private readonly string $pin, #[SensitiveParameter] private readonly string $certLabel, #[SensitiveParameter] private readonly ?string $keyLabel = null, array $chainDer = [], private readonly bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null)
public static function isAvailable(): bool
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function signPqs(string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true): string

public function __construct(private string $keyUri, string $certPath, #[SensitiveParameter] private string $pin, array $extraCertPaths = [], private OpenSslCliBackend $backend = OpenSslCliBackend::Auto, private string $opensslBinary = 'openssl', private int $timeoutSeconds = 30, private ?string $modulePath = null, private ?string $configPath = null, private bool $legacyPinDelivery = false, private ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string

public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void

public function __construct(private CryptoPolicyInterface $policy, private ?FipsBootGuard $bootGuard = null, private ?FipsAuditLogger $auditLogger = null)
public function assertHashAllowed(string $algorithm): void
public function assertSignatureAlgorithmAllowed(string $oid): void
public function assertEncryptionAllowed(string $algorithm): void
public function assertKeyStrengthAllowed(string $keyType, int $bitLength): void
public function getPolicy(): CryptoPolicyInterface

public static function boot(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function lazy(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function signatureEnforcer(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null): FipsSignatureEnforcer
public static function selfTestReport(?FipsSelfTest $selfTest = null): array

挙動契約

コントラクト解決。 どちらの署名者も Core の HsmSignerInterface を実装し、ポリシーは Core の CryptoPolicyInterface を実装します。呼び出し側はコントラクトに依存するため、エディションのアップグレードはコンポジションを変えるだけで、呼び出しサイトは変えません。
鍵の保管。 秘密鍵はトークン境界を離れることはありません。Pkcs11Signer は操作をトークンに委譲します。OpenSslCliSigner は PKCS#11 URI の鍵参照をサブプロセスに渡します。NextPDF は署名鍵を保存、生成、またはそのセキュリティを保証しません。鍵保護はオペレーターの保管責任です（NIST SP 800-57 Part 1 Rev.5 §5.5.2）。
セッションとログイン。 トークンの署名操作、セッション、ユーザーログインは PKCS#11 v3.1 §5 に従います。証明書ラベルと秘密鍵ラベルは異なる場合があり、コンストラクターはそのようなトークンのために別個の鍵ラベルを受け付けます。
閉じたアルゴリズム集合。 署名者は次のものだけを受け付けます。SHA-256/384/512 を使用する RSA PKCS#1 v1.5、SHA-256/384/512 を使用する RSASSA-PSS、SHA-256/384/512 を使用する ECDSA（Pkcs11Signer は ecdsa-raw も受け付けます）。それ以外の識別子は InvalidArgumentException を発生させます。代替アルゴリズムが署名されることは決してありません。
PSS ソルトバインディング。 すべての PSS バリアントで、ソルト長はダイジェスト長（32、48、または 64 バイト）と等しく、ハッシュおよびマスク生成パラメーターは選択されたダイジェストと一致します（PKCS#11 v3.1 §5）。
ECDSA 変換。 トークンの ECDSA メカニズムは生の署名を返します。sign() は、PDF および OpenSSL との相互運用性のために、それを DER エンコードの ECDSA-Sig-Value 形式に変換します。署名生成は FIPS 186-5 §6.3.2 に従います。
プリセットの内容。 strict プリセットは、SHA-256/384/512、それらのハッシュを使用する RSA および ECDSA の署名 OID、RSASSA-PSS、AES-256-CBC および AES-256-GCM、最小で RSA 2048 および EC 256 を許可します。standard プリセットは、レガシー相互運用性のために AES-128-CBC を追加で許可します。AES-GCM の使用には、鍵ごとに一意の初期化ベクトルが必要です（NIST SP 800-38D §5）。
2 層エンフォースメント。 すべてのガード境界は、まず明示的な NIST SP 800-131A 拒否カタログを参照し、次にポリシーの許可リストを参照します。拒否レイヤーは監査で明確な「許可されていない」シグナルを生成し、許可リストが権威を保ちます。
電源投入時セルフテスト。 バッテリーは、SHA-256/384/512、HMAC-SHA-256、AES-256-CBC、AES-256-GCM、ECDSA P-256 のペアワイズ整合性テスト、およびランダムビットのヘルスチェックをカバーします。Core パス上でポリシーの下での最初の暗号操作が、プロセスごとに 1 回、フェイルクローズで実行します。失敗はモジュールを ERROR 状態にし、リセットまで暗号サービスは拒否されます。これは ISO/IEC 19790:2025 §7.10、§7.10.2、§7.10.3、§7.10.3.p3 に従います。
スティッキー ERROR 状態。 観測された ERROR はプロセス全体でラッチします。新しいポリシーやブートガードを構築してもそれを洗い流すことはできず、合格した再実行でも解除されません。プロセスの再起動（真の電源サイクル）のみが状態をリセットします。
生成ゲートのみ。 FipsSignatureEnforcer は新しい署名の生成を統制します。既存の署名の検証はレガシー使用であり、エンフォーサーを経由することは決してありません。
監査証跡。 ガードが監査ロガーと構成されると、すべての境界は操作を許可または拒否する前に ALLOW または DENY レコードを発行します。ロガーはガードが強制するのと同じポリシーを参照するため、記録された決定が乖離することはありません。

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

ext-pkcs11 なしで Pkcs11Signer を構築すると、直ちに HsmOperationException が発生します。この拡張は標準の PHP ディストリビューションには同梱されていません。
どのトークンオブジェクトにも一致しない証明書ラベルまたは秘密鍵ラベルは、欠落しているオブジェクトクラスを示す HsmOperationException を発生させます。
OpenSslCliSigner は、pin-value を含む $keyUri を構築時にフェイルクローズで拒否します。代わりに PIN は安全な pin-source パスを経由します。
FIPS モードでは、既知の署名 OID にマッピングできないアルゴリズム識別子はフェイルクローズで拒否されます。公開鍵強度を判定できない証明書も同様です。
未知の鍵タイプはデフォルトで拒否されます。ポリシーがより弱いアルゴリズムにフォールバックすることは決してありません。
失敗した既知応答テストは、失敗した結果を伴う FipsModuleErrorStateException を発生させます。プロセス内の以降のすべての境界は、再起動まで失敗を繰り返します。
ブートガードなしで構築されたガードは許可リストを強制しますが、セルフテストゲートは提供しません。本番の FIPS コンポジションは、ブートストラップを通じてそれを供給します。
signPqs() は、コンストラクターのオプトインが設定されていない限り実行を拒否します。255 バイトを超えるコンテキスト文字列は InvalidArgumentException を発生させます（FIPS 204 §5.4）。選択されたパラメーターセットとバイト長が一致しない返された署名は、エンコードに到達する前に拒否されます。

FIPS モード挙動

strict モードで FIPS が許可するもの: SHA-256/384/512、それらのハッシュを使用する RSA PKCS#1 v1.5 および RSA-PSS、それらのハッシュを使用する ECDSA、AES-256-CBC および AES-256-GCM、RSA は最小 2048 ビット、EC は最小 256 ビット。strict モードで FIPS が拒否するもの: より弱いまたはレガシーなハッシュ、承認されていない署名 OID、AES-128（standard プリセットでのみ許可）、および最小強度を下回るすべての鍵。最小の RSA 鍵長と移行ステータスは NIST SP 800-131A Rev.2 §3 に従います。ECDSA の曲線とハッシュのペアリングは FIPS 186-5 §6.1.1 に従います。このパスはフェイルクローズであり、より弱いアルゴリズムに置き換えることは決してありません。

NextPDF Enterprise は FIPS 検証済みの暗号モジュールではなく、FIPS 認証の主張を一切行いません。 NextPDF Enterprise は、FIPS 検証済みの暗号プロバイダー（たとえば FIPS 検証済みの OpenSSL プロバイダー）または FIPS 検証済みの HSM と構成された場合にのみ、FIPS 互換モードで動作します。FIPS モードポリシーはコンプライアンスを支援します。認証ではありません。このリポジトリには FIPS 認証アーティファクトは存在しません。

適合性

主張	標準	条項
トークンの署名操作、セッション、ユーザーログインのセマンティクス	PKCS#11 v3.1	§5 (sign)
PSS ソルト長はダイジェスト長と等しい	PKCS#11 v3.1	§5 (PSS sLen)
ECDSA 署名生成、曲線とハッシュのペアリング	FIPS 186-5	§6.3.2; §6.1.1
最小の RSA 鍵長と署名生成の移行ステータス	NIST SP 800-131A Rev.2	§3
セルフテストのカテゴリ、ドキュメント化、条件付きトリガー、互いに素な集合	ISO/IEC 19790:2025	§7.10, §7.10.2, §7.10.3, §7.10.3.p3
AES-GCM 初期化ベクトルの一意性	NIST SP 800-38D	§5
鍵保護と保管の責任	NIST SP 800-57 Part 1 Rev.5	§5.5.2
ポスト量子署名のコンテキスト文字列は 255 バイトに制限	FIPS 204	§5.4

すべての条項はパラフレーズであり、規範的テキストは複製していません。これらは NextPDF コードに関する機能の主張であり、認証ではありません。生成された署名が検証されるかどうかは、検証者自身のトラスト構成に対する検証者の決定です。FIPS モードポリシーはコンプライアンス支援機能であり、法的意見ではありません。ご自身のコンプライアンスおよび法務の助言者にご相談ください。このモジュールは暗号機能に関わるため、ご自身のレビューではセキュリティに敏感なものとして扱ってください。

開発上の注意

FIPS モードはブートストラップを通じて構成します。起動時ゲートには boot()、バッテリーを最初の境界まで遅延させるには lazy()、署名者の $fipsEnforcer パラメーターにはエンフォーサーファクトリを使用します。非 FIPS のデプロイでは null を渡し、挙動は変わりません。
bin/nextpdf-enterprise の fips:self-test サブコマンドは、オンデマンドでバッテリーを実行し、ERROR 状態では非ゼロで終了します。メンテナンスジョブまたは管理者専用のヘルスエンドポイントに配線してください（ISO/IEC 19790:2025 のオンデマンドセルフテスト）。
FipsBootGuard::resetProcessErrorLatchForTesting() は @internal かつテスト専用です。スティッキー ERROR 状態を無効化してしまうため、本番コードが呼び出すことは決してありません。
署名者は一度構築して再利用してください。構築時にログインして証明書を読み取り、ライブラリごとのモジュールキャッシュにより、同じライブラリに対する繰り返しの構築が安全になります。
PIN はシークレットマネージャーから供給してください。これは #[SensitiveParameter] であり、ログ記録もシリアライズもされません。構成にコミットしないでください。
オペレーターは、トークンのプロビジョニング、PIN の取り扱い、スロット構成、ネットワーク接続された HSM のネットワーク保護、およびトラスト構成を所有します。このページは、トークンの PIN ポリシーの内部やベンダーの認証情報マテリアルを公開しません。
本番の AdES 署名のためにポスト量子プレビューを有効にしないでください。AdES 暗号スイートカタログはポスト量子スイートをまだ認識しておらず、ほとんどの PDF ビューアーはそのような署名を拒否し、ハードウェアラウンドトリップ検証は完了していません。内部メカニズムの詳細はソースリポジトリの内部ドキュメントに留まり、このマニュアルの対象外です。

公開境界

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