Accelerator — GPU サイドカーと KMS プロバイダーファクトリ

概要

NextPDF Enterprise は、2 つのアクセラレーション機能を追加します。CPU フォールバックを備えたテキスト埋め込み用の GPU サイドカーと、コレクションレベルのデータ暗号化鍵のメタデータおよびローテーションを提供する KMS プロバイダーファクトリです。このページでは、挙動、境界、そして鍵保管のスタンスを記載します。

提供状況とライセンス

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

概念の概要

GPU サイドカーは、テキストからベクトルへの埋め込みを高速化します。Enterprise パッケージは、ローカル HTTP リクエストを介して、別個のサイドカープロセスへテキストを送信します。サイドカーは、GPU が利用可能な場合はその GPU 上で埋め込みモデルを実行します。GPU が利用できない場合、サイドカーは同じモデルを CPU 上で実行し、デグレードモードで実行したことを報告します。いずれの場合も、結果は同じベクトル形状になります。埋め込みモデルは最初のリクエスト時に読み込まれるため、最初のリクエストは後続のものより遅くなります。サイドカーはオプションです。可用性チェックが公開されており、サイドカーが存在しない場合は、サイレントな失敗ではなく型付き例外を発生させます。

KMS プロバイダーファクトリは、構成から鍵管理プロバイダーを選択します。ファクトリは環境変数を読み取ってプロバイダーを選びます。デフォルトプロバイダーは、コレクション識別子をドメインセパレーターとして、構成済みのマスターキーから HKDF-SHA256 を用いてコレクション固有のデータ暗号化鍵をローカルで導出します。ローカルプロバイダーは外部サービスに接続しません。導出は決定論的かつインプロセスです。ファクトリは、ローカルプロバイダー向けの明示的な構成形式も受け付けます。クラウドプロバイダー — AWS KMS、GCP Cloud KMS、Azure Key Vault、HashiCorp Vault Transit — は認識されるプロバイダー名です。対応する統合がインストールされていない状態でいずれかを選択すると、欠落している依存関係を名指しする型付き構成エラーを発生させます。

プロバイダーは、生の鍵バイトではなく、鍵のメタデータを返します。メタデータは、鍵識別子、単調増加する鍵バージョン、暗号化アルゴリズム名、およびプロバイダー名を記録します。ローテーション呼び出しは鍵バージョンを進め、新しいメタデータを返します。ローテーション後に新しい鍵バージョンでコレクションデータを再暗号化する責任は、呼び出し元にあります。鍵バージョンとローテーションのライフサイクルは、NIST SP 800-57 Part 1 Rev.5 §4 に従います。

なぜこの仕組みなのか

埋め込みは、PHP リクエスト内ではなく、別個の GPU サイドカープロセスで実行されます。GPU のモデル読み込みはコストが高いため、サイドカーはモデルを一度だけ読み込み、そのコストを多数のリクエストにわたって償却します。GPU が存在しない場合、サイドカーは同じモデルを CPU 上で実行し、デグレードモードを報告します。スループットは低下する可能性がありますが、正しさは低下しません。ベクトル形状はいずれの場合も同一です。サイドカーはオプションのままです。可用性チェックと、サイドカーが存在しない場合の型付き例外により、アクセラレーションは隠れた依存関係ではなく、意図的なオプトインとして保たれます。この分離により、大量の埋め込みは専用ハードウェア上でスケールし、一方でドキュメントパイプラインはプレーンな PHP 呼び出しのままになります。

設計の背景: High-volume document generation。

API サーフェス

公開サーフェス	種別	目的	安定性	導入バージョン
KMS プロバイダーファクトリ	class	環境または明示的な構成から KMS プロバイダーを構築する	stable	2.1.0
KMS プロバイダー	interface	鍵メタデータの取得、鍵のローテーション、プロバイダー名の報告	stable	2.1.0
ローカル KMS プロバイダー	class (プロバイダーインターフェースを実装)	ローカル HKDF-SHA256 鍵導出。外部サービスに接続しない	stable	2.1.0
暗号化鍵の結果	value object	不変の鍵メタデータ: 鍵 ID、バージョン、アルゴリズム、プロバイダー — 生の鍵バイトは含まない	stable	2.1.0
GPU 埋め込みサービス	class (Core の埋め込みサービスインターフェースを実装)	CPU フォールバックを備えた GPU サイドカー上でのテキスト埋め込み	stable	2.1.0

プロバイダーファクトリは、「環境から」のエントリーポイントと、明示的な「作成」のエントリーポイントを公開します。マスターキーの構成値は、ローカルプロバイダー内で機密としてマークされます。正規のパラメーターおよび型のコントラクトは、nextpdf/enterprise パッケージの公開 API リファレンスです。このページではなく、そのリファレンスをコントラクトとして扱ってください。

コードサンプル — クイックスタート

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Build the local KMS provider and read key metadata

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

コードサンプル — 本番

Rotate a collection key, then re-encrypt collection data

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

環境変数名、明示的な構成キー、および例外型は、Accelerator 詳細リファレンスに記載されています。

エッジケースと注意点

• ローカル KMS プロバイダーには、少なくとも 32 バイトの 16 進エンコードされたマスターキーが必要です。これより短い値や 16 進でない値は、構築時に型付き引数例外を発生させます。
• 対応する統合がインストールされていない状態でクラウドプロバイダー名を選択すると、欠落している依存関係を名指しする型付き構成エラーを発生させます。
• 不明なプロバイダー名は、サポートされる名前を列挙する型付きエラーを発生させます。
• GPU サイドカーは、CPU にフォールバックするとデグレードモードを報告します。GPU スループットに依存する場合は、そのフィールドを確認してください。
• 埋め込みモデルは最初のリクエスト時に読み込まれます。最初のリクエストのタイムアウトはそれに応じて設定してください。

パフォーマンス

ローカル鍵導出は、コストが一定の HKDF 演算です。外部サービスには接続しません。GPU 埋め込みリクエストは、サイドカーへのローカルラウンドトリップ 1 回とモデル推論時間を追加します。最初のリクエストは、1 回限りのモデル読み込みコストも負担します。CPU フォールバックは正しい結果を返しますが、同じバッチでは GPU パスより低速です。

セキュリティに関する注意

• KMS プロバイダーは、生の鍵バイトではなく、鍵のメタデータを返します。暗号化鍵の結果である value object が鍵マテリアルを保持することはありません。
• ローカルプロバイダーのマスターキーは、機密なコンストラクターパラメーターです。ログ記録もシリアライズもされません。
• ローカルプロバイダーは外部サービスに接続しません。導出は決定論的かつインプロセスです。
• AES-GCM の使用には、NIST SP 800-38D §5 に従い、鍵ごとに一意の初期化ベクトルが必要です。

データレジデンシーと PII の緩和策

ローカル KMS プロバイダーはインプロセスで実行され、外部サービスには接続しません。ローカル鍵導出のために鍵マテリアルやドキュメントコンテンツがホストの外に出ることはありません。GPU サイドカーは、埋め込むテキストをローカルリクエストで受け取ります。無関係なドキュメントコンテンツを受け取ることはありません。クラウド KMS プロバイダーは、構成された場合、選択したクラウドプロバイダーに接続します。お客様の管轄区域については、そのプロバイダーのデータレジデンシーのスタンスを確認してください。

安全なテレメトリとログのスクラブ

ローカルプロバイダーのマスターキーは機密なコンストラクターパラメーターであり、ログおよびシリアライズから除外されます。マスターキー、導出された鍵、またはプロバイダーの資格情報を、お客様独自のアプリケーションログに追加しないでください。ログおよびトレースのポリシーにおいて、すべての鍵マテリアルを秘密として扱ってください。

脅威モデル

プロバイダーは鍵バイトではなくメタデータを返すため、メタデータの漏洩が鍵マテリアルを露出させることはありません。ローカルプロバイダーのセキュリティは、構成されたマスターキーの秘匿性に依存します。クラウドプロバイダーのセキュリティは、そのプロバイダーとお客様の構成に依存します。鍵の保護は、KMS またはマスターキーの秘密、デプロイメント、およびオペレーターに依存し、このソフトウェア単独には依存しません。デプロイメントの境界を参照してください。

適合性

• データ暗号化鍵のバージョンとローテーションのライフサイクルは、NIST SP 800-57 Part 1 Rev.5 §4 に整合します。
• 鍵保護の責任は、NIST SP 800-57 Part 1 Rev.5 §5.5.2 に整合します。
• AES-GCM の初期化ベクトルの一意性は、NIST SP 800-38D §5 に整合します。

すべての規範的なソースはパラフレーズです。このページに規範的なテキストは複製されていません。このページは鍵管理に関わるものです。

FIPS モードの挙動

ローカルプロバイダーの HKDF 導出は SHA-256 を使用します。鍵メタデータに記録される暗号化アルゴリズムは AES-256-GCM です。アプリケーションが FIPS 検証済みの暗号プロバイダーに対して実行される場合、それらのプリミティブはその検証済み境界内で実行されます。プロバイダーファクトリ自体はプロバイダーを選択して構築するものであり、暗号境界を認証するものではありません。

NextPDF Enterprise は FIPS 検証済みの暗号モジュールではなく、いかなる FIPS 認証の主張も行いません。 FIPS 検証済みの暗号プロバイダーまたは FIPS 検証済みの KMS が構成されている場合にのみ、FIPS 互換モードで動作します。

エディションの境界

GPU 埋め込みサイドカーと KMS プロバイダーファクトリは、nextpdf/enterprise パッケージにのみ同梱されています。NextPDF Pro は、署名ストラテジー向けの KMS 統合 (AWS KMS、GCP Cloud KMS、Azure Key Vault) を提供しますが、Enterprise の KMS プロバイダーファクトリや GPU 埋め込みサイドカーは提供しません。内部のサイドカートランスポートと内部の埋め込みパイプラインクラスは、公開サーフェスの範囲外であり、ここでは複製していません。

Pro フォールバック

NextPDF Pro は、クラウド KMS の署名ストラテジーを提供します。KMS が署名鍵を保持し、Pro は署名済み属性のダイジェストをプロバイダーへ送信します。これは署名統合です。Enterprise のコレクションレベルのデータ暗号化鍵プロバイダーファクトリでも、GPU 埋め込みサイドカーでもありません。Pro のアクセラレーションサーフェスについては Accelerator — NextPDF Pro を参照してください。

Core フォールバック

NextPDF Core には GPU 埋め込みサイドカーも KMS プロバイダーファクトリもありません。埋め込みとコレクションレベルの鍵管理は Enterprise 専用の機能です。

Enterprise の境界に関する注記

GPU サイドカートランスポート、埋め込みモデル識別子、および内部パイプラインクラスは、挙動レベルでのみ記述しています。内部のトランスポートクライアント、内部のスコープトークン、および内部のパイプライン構成は、公開サーフェスの範囲外であり、ここでは複製していません。

デプロイメントの境界

NextPDF Enterprise は、KMS と統合するか、構成されたマスターキーの秘密から鍵を導出します。NextPDF Enterprise 自体が、そのマスターキーの秘密やクラウド KMS の鍵を保管したり、そのセキュリティを保証したりすることはありません。鍵のセキュリティは、KMS またはマスターキーの秘密、デプロイメント、およびオペレーターに依存し、NextPDF Enterprise 単独には依存しません。 オペレーターは、マスターキーのプロビジョニング、秘密の保管、KMS の構成、およびローテーションのスケジューリングに対して責任を負います。鍵保護の責任は、NIST SP 800-57 Part 1 Rev.5 §5.5.2 に従います。NextPDF Enterprise は、このドキュメントにおいて KMS の資格情報フローやマスターキーの取り扱いの内部を公開しません。

法令遵守の境界

対象は鍵管理です。FIPS モードに関する記述は互換性の記述であり、認証でも法的見解でもありません。ご自身の規制上の義務については、ご自身のコンプライアンスおよび法務の助言者にご相談ください。

公開の境界

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

挙動コントラクト

• プロバイダーファクトリは、構成からプロバイダーを選択し、プロバイダーコントラクトを満たすプロバイダーを返します。
• プロバイダーは不変の鍵メタデータを返し、生の鍵バイトを返すことはありません。
• ローテーション呼び出しは鍵バージョンを進め、新しいメタデータを返します。コレクションデータの再暗号化は呼び出し元が行います。
• GPU サイドカーは、CPU フォールバック時にデグレードモードを報告し、利用できない場合は型付き例外を発生させます。

関連項目

• Accelerator リファレンス — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — 用語集の用語。