doca-aes-gcm

DOCA AES-GCM

例

• 「復号時に認証タグを検証できません。」 — この範囲に含まれます。 タグ検証失敗はセキュリティ上の結果として扱い、 再試行可能なサイズエラーとして扱わないでください。
• 「この BlueField で AES-192-GCM は使えますか？」 — いいえ。key-128 と key-256 のみが存在します。AES-192 や CBC／CTR オフロードを 作り出さないでください。

手順

以下の読み込み順に従ってください。設定／テスト／デバッグについてはタスク用の補足ファイルを開いてください。 キーの種類と AEAD の安全性に関する注意事項については、機能用の補足ファイルを開いてください。すべての補足ファイルを開く必要はありません。

最初に確認する内容： このスキルは、DOCA がすでにインストールされており、ユーザーが BlueField／ConnectX／DOCA 搭載ホストで AES-GCM アクセラレーションを実際に利用する作業を行っていることを前提としています。ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ）したい場合はタスク用の補足ファイルを開いてください。このバージョンの DOCA AES-GCM で何が表現できるかが質問の場合は、機能用の補足ファイルを開いてください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーが*「この暗号化にアクセラレーターを使うべきですか？」*と尋ねている場合は、## 機能とモード のパス選択ルールを最初に確認してください。ユーザーが AES-GCM を機密性のみを提供するプリミティブ（raw AES-CTR／AES-CBC 形式）として扱っている場合は、まず ## 安全性ポリシー の AEAD に関する注意事項を読んでください。AES-GCM は認証付き暗号化であり、この2つを混同することは、このスキルが防ごうとしている最も重大な失敗です。

このスキルが適切に回答できる質問の例

このスキルが回答するよう設計されている、DOCA AES-GCM に関する質問のクラスを、それぞれ1つの具体例とともに示します。エージェントは、回答の要となるのは クラス であり、具体例はその1つのケースにすぎないと捉えてください。

• 「この AES-GCM 暗号化は DOCA AES-GCM にオフロードすべきですか？ それとも CPU 上で OpenSSL を使って処理すべきですか？」 — 具体例：「4 KiB の TLS レコードをラインレートで暗号化しています。CPU 上の OpenSSL EVP_aes_256_gcm と比べて、doca-aes-gcm のセットアップに見合う価値はありますか？」。回答は、## Capabilities and modes のパス選択表と、## Safety policy の 「doca-aes-gcm を使用すべきでない場合」 の箇条書きに記載されています。
• 「デバイスは使用したい AES-GCM の鍵サイズに対応していますか？」 — 具体例：「この BlueField のアクセラレーターで AES-256-GCM は使えますか？ ついでに、AES-192-GCM は利用できますか？」（回答：ライブラリが公開しているのは DOCA_AES_GCM_KEY_128 と DOCA_AES_GCM_KEY_256 のみです。AES-192 は列挙型に含まれておらず、サポートされていません。実際に利用できる2種類の鍵については、doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type) と、それに対応する _decrypt_is_key_type_supported で確認してください。AES-192 は利用できないため、CPU ライブラリに切り替えてください。）回答は、## Capabilities and modes の鍵タイプごとの機能クエリとタスクごとの doca_aes_gcm_cap_task_*_is_supported クエリ、および ## configure の検出手順に記載されています。
• 「AES-GCM メッセージを正しく復号し、認証タグを検証するにはどうすればよいですか？」 — 具体例：「doca_aes_gcm_task_decrypt の完了がエラーを報告しました。平文の出力を使っても安全ですか？」。回答は、## Safety policy の認証タグ検証ルール（認証タグが検証されなかった場合、平文を使用しないでください）と、## test および ## debug の復号完了処理ワークフローに記載されています。
• 「ソース／宛先の mmap に必要な権限は何ですか？」 — 具体例：「doca_aes_gcm_task_encrypt が DOCA_ERROR_NOT_PERMITTED を返します」。回答は、## Safety policy の権限マトリックスと、## test の mmap 権限設定チェックリストに記載されています。
• 「この DOCA AES-GCM API は、インストール済みの DOCA バージョンで利用できますか？」 — 具体例：「このデバイスにインストールした DOCA で AES-192-GCM は使えますか？」。回答は、## Version compatibility のバージョン互換性に関する補足に記載されています。ここでは、doca-version/SKILL.md の標準的な検出手順を参照し、AES-GCM 固有の 「cap クエリで鍵サイズを検出する」 の箇条書きを追加しています。
• 「AES-GCM の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どの層が原因ですか？」 — 具体例：「暗号化バッファーで DOCA_ERROR_NOT_PERMITTED が発生します」。回答は、## Error taxonomy のライブラリ横断のエラー分類に AES-GCM 固有の補足を加えた内容と、doca-debug/SKILL.md へのエスカレーションにつながる ## debug の段階的な手順に記載されています。

復号完了時の IO_FAILED は、デバッグに関する問題ではありません。 認証タグの検証に失敗したことを意味し、コードや設定の不具合ではなくセキュリティ上のイベントです。層ごとに分類することも、doca-debug/SKILL.md にエスカレーションすることもありません。このタスクが生成した平文は汚染されているため、使用してはいけません。復号を再試行してはいけません。入力の暗号文は改ざんまたは破損されているため、信頼できないデータとして扱わなければなりません。結果の扱いは、改ざんされた入力に対する呼び出し元のアプリケーション層のポリシーに従います。まずこの点を明確に伝えてください。既知の正しいベクトルでテストしている場合に限り、設定に起因する可能性（誤った鍵、IV、AAD、またはタグ長）を挙げる価値があります。その場合でも、これらは2番目に述べてください。詳細なルールは ## Error taxonomy と ## Safety policy に記載されています。

対象読者

このスキルは、DOCA AES-GCM ライブラリを利用するアプリケーションを構築する外部開発者、つまり、BlueField DPU または ConnectX アクセラレーターに AES-GCM 認証付き暗号化／復号をオフロードするために、（C/C++ から直接、または別の言語から FFI／バインディング経由で）doca_aes_gcm_* を呼び出すコードを使用するユーザーを対象としています。NVIDIA の開発者で、DOCA AES-GCM 自体に貢献する方は対象ではありません。

言語の範囲。 DOCA AES-GCM は、pkg-config のモジュール名 doca-aes-gcm を持つ C ライブラリとして提供されています。付属のサンプルは C で記述されています。C および C++ の利用者が標準的なケースであり、タスクの関連資料にある実例もこの利用方法を前提としています。他の言語（Rust、Go、Python など）の利用者は、FFI または言語固有のバインディングを通じて同じ *.so を利用します。その場合、このスキルでは、ライフサイクル、機能の検出、権限、エラー分類、AEAD のセマンティクス、暗号化と復号の使い分けに関するガイダンスを言語に依存しない形で提供し、ラッパーが最終的に呼び出す公式の C ABI を信頼できる仕様としてエージェントに案内します。

キーの取り扱いは対象外です。 このスキルでは、DOCA AES-GCM ライブラリの使用方法をエージェントに教えます。AES-GCM キーの生成、保存、ローテーション、配布方法は扱いません。キー管理はユーザーの責任です（KMS、HSM、シールされたファイル、またはユーザーが信頼する環境変数など）。このスキルでキーの取り扱いに関して定めるのは、## Safety policy: に記載された運用上のルールのみです。キーをログに記録しないこと、ソースにコミットしないこと、プログラムが保持するキーのバッファーを機密メモリとして扱うこと。

このスキルを読み込むタイミング

ユーザーが、どの言語を使っている場合でも、DOCA AES-GCM を実際に扱っているときにこのスキルを読み込みます。具体的には、次のような場合です。

• doca_dev 上で doca_aes_gcm コンテキストを初期化し、doca_ctx_start() の前に少なくとも 1 つのタスクタイプ（doca_aes_gcm_task_encrypt および／または doca_aes_gcm_task_decrypt）を設定する場合。
• ユーザーのデータ形状に応じて、暗号化（doca_aes_gcm_task_encrypt — 鍵 + IV + AAD + 平文を受け取り、暗号文 + 認証タグを生成）と復号（doca_aes_gcm_task_decrypt — 鍵 + IV + AAD + 暗号文 + 期待される認証タグを受け取り、平文を生成してタグを検証）を選択する場合。
• ソースバッファー（最低でも DOCA_ACCESS_FLAG_LOCAL_READ_ONLY。暗号化時は平文、復号時は暗号文）と宛先バッファー（DOCA_ACCESS_FLAG_LOCAL_READ_WRITE）に対して、doca_mmap のアクセス権限を正しく設定する場合。
• アクティブなデバイスのアクセラレーターが、どの AES-GCM 鍵タイプ（DOCA_AES_GCM_KEY_128／DOCA_AES_GCM_KEY_256 — ライブラリでは AES-192 はサポートされていません）をサポートしているかを doca_aes_gcm_cap_task_encrypt_is_key_type_supported／doca_aes_gcm_cap_task_decrypt_is_key_type_supported で確認し、どのタスクタイプをサポートしているかを doca_aes_gcm_cap_task_encrypt_is_supported／_task_decrypt_is_supported で確認する場合。
• 送信ごとの平文のサイズを doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo) に照らして決定する場合。
• アクセラレーターにユーザーデータを渡す前に、公開されている AES-GCM テストベクター（NIST GCMVS または RFC 5288 の例）を使って暗号化と復号の往復を検証する場合。
• 復号完了時の認証タグ検証結果をセキュリティ上重要なシグナルとして扱う場合 — タグ不一致を示す完了イベントは、暗号文が改ざんまたは破損されたことを意味し、そのタスクの平文出力は汚染されているため、使用してはいけません。
• AES-GCM 呼び出しから返された DOCA_ERROR_*（ライフサイクル、非対応の鍵サイズ、権限、復号時のタグ検証失敗など）や、プログレスエンジン上のタスク完了イベントをデバッグする場合。
• AES-GCM C ABI をラップする、C 以外のバインディング（Rust、Go、Python など）を設計または拡張する場合 — ラッパーがライフサイクル、権限、機能、AEAD のセマンティクス、暗号化と復号のルールを守る必要があります。

DOCA 全般の概要、DOCA 自体のインストール、GCM 以外の AES モード（CBC／CTR／XTS — これらはこのライブラリには含まれておらず、CPU + OpenSSL を使うのが適切です）、同じアクセラレーターファミリーでの SHA ハッシュ処理（doca-sha/SKILL.md を使用）、またはその他の DOCA ライブラリについては、このスキルを読み込まないでください。これらについては、doca-public-knowledge-map/SKILL.md を使用してください。

このスキルが提供するもの

これは薄いローダーです。本文には、次に適切なファイルを選ぶために必要な概要だけを残しています。AES-GCM固有の実質的な内容は、次の2つの補助ファイルにあります。

• 機能補助ファイル — このバージョンのDOCA AES-GCMで表現できる内容： 2種類のタスク（暗号化と復号）、AEADの出力形式 （暗号化では暗号文＋認証タグ、復号では検証済み平文）、 AES-GCMのキータイプの範囲（128ビットと256ビットのみ。AES-192 は列挙型に含まれず、いずれも機能クエリで確認）、機能クエリの 対象（タスクの有無、キータイプのサポート、バッファサイズに関する doca_aes_gcm_cap_*）、AES-GCMのエラー分類 （ライブラリ間で共通のDOCA_ERROR_*セットに対応付けられ、 タグ検証失敗の結果をセキュリティ上重要なものとして明示的に扱う）、 可観測性の範囲（プログレスエンジン上のタスクごとの完了イベント）、 ソース／宛先mmapの権限判断とキーの取り扱いに関する注意を制御する安全性ポリシー、 およびパス選択ルール（doca-aes-gcmとCPU OpenSSL、 または別のDOCA暗号ライブラリを使い分けるタイミング）。
• タスク補助ファイル — 対象範囲に含まれるAES-GCMの6つの動詞 configure、build、modify、run、test、debugに関する ステップごとのワークフロー。 さらに、対象範囲外の質問を適切な次のスキルへ案内する Deferred task verbsブロックもあります。

このスキルは、DOCAが標準の場所にすでにインストールされ、 ユーザーが公開インストールプロファイルで想定される権限を持つホストまたは BlueFieldを前提としています。DOCAのインストールは対象外です。 その手順については doca-setup/SKILL.mdを参照してください。

このスキルに意図的に含めていないもの

このスキルはエージェント向けガイダンスであり、サンプルやテンプレートの バンドルではありません。境界を明確に保つため、意図的に次のものを 含めていません。また、プルリクエストで追加しないでください。

• 言語を問わず、あらかじめ作成されたDOCA AES-GCMアプリケーションのソースコード。 検証済みのAES-GCMソースコードは、提供されているCの サンプル/opt/mellanox/doca/samples/doca_aes_gcm/です。エージェントの 役割は、ユーザーをこれらのファイルへ案内し、 doca-programming-guide/SKILL.mdに記載された 共通のサンプル変更ワークフローを通じて、最小限の差分で変更するよう指示し、 さらに## modifyにあるAES-GCM固有の上書き指示を適用することです。
• 事前計算済みのAES-GCMテストベクトル。 このスキルはエージェントに、 既知ベクトルのスモークテストとして 公開済み のテストベクトル （例：NIST GCMVS、RFC 5288の AES-GCMの例）を使うよう指示しますが、独自のベクトル集は含めていません。 ユーザーが出典を監査できるよう、エージェントはベクトルの出典を明記する必要があります。
• あらかじめ用意されたAES-GCMのキー、IV、AAD文字列。 この リポジトリ内のキーは、すべての顧客のリポジトリにあるキーでもあります。 その性質上、ここに置いてはなりません。このスキルは入力の 形式 を説明し、 実際のバイト列はユーザーが自身のキー管理システムから提供します。
• スタンドアロンのビルドマニフェスト （meson.build、CMakeLists.txt、 Cargo.tomlなど）をスキル内に置くこと。このスキルではビルドマニフェストを ユーザーのプロジェクトディレクトリ内で、ユーザーがインストールしたDOCAに対して 作成します。その際、pkg-config --modversion doca-aes-gcmを信頼できる情報源として使います。
• どのような種類のものでも、samples/、bindings/、またはreference/のサブツリー。 「reference」とラベル付けされていても、このスキルのツリー内にあるモックや不完全な成果物は 誤解を招きます。ユーザーがビルド可能なものとして受け取ってしまうためです。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します。
2. AES-GCM の機能マトリックス、タスクの種類、キーサイズの範囲、機能クエリのルール、権限マトリックス、AEAD のセマンティクス、エラー分類、可観測性、安全性／パス選択ポリシーについては、機能に関する補足資料を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、タスクに関する補足資料を参照してください。

どちらの補足資料も、相互にリンクしています。また、正規のバージョン処理ルールについては doca-version/SKILL.md に、答えが「AES-GCM 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージのレイアウトを調べる」である場合は doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての DOCA 公開ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティング表です。DOCA AES-GCM のページは docs.nvidia.com/doca/sdk/DOCA-AES-GCM/ にあります。これは doca-sha/SKILL.md と並ぶ、DOCA Crypto Acceleration ファミリーの一員です。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、公開 NGC DOCA コンテナーを使う まだインストールしていない場合 の手順を扱います。このスキルでは、前提条件が満たされているものとします。
• doca-version/SKILL.md — 正規の DOCA バージョン処理ルールです。このスキルの ## Version compatibility では、4 要素の一致ルールを相互参照し、「機能クエリでキーサイズとタスクの有無を調べる」という AES-GCM 固有の補足のみを追加しています。
• doca-structured-tools-contract/SKILL.md — このバンドルの構造化ツールに関する優先順位ルール（検出／優先／フォールバック／報告）です。 tasks 補足資料の Command 付録はこの契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンです。正規の pkg-config + meson ビルドパターン、出荷済みサンプルを変更する汎用的な初回アプリ開発ワークフロー、共通のライフサイクル、ライブラリ間で共通する DOCA_ERROR_* のエラー分類、プログラム側のデバッグ順序を扱います。このスキルでは、これらに AES-GCM 固有の内容を重ねています。
• doca-sha/SKILL.md — ハードウェアアクセラレーション対応の SHA ハッシュ処理を行う、DOCA Crypto Acceleration ファミリーの姉妹ライブラリです。ユーザーのワークフローが 別の鍵付きハッシュを用いる認証付き暗号化 の場合（まれなケースです。AES-GCM はすでにタグによる認証を提供します）、または 2 つのオフロード経路を比較する場合は、このスキルと一緒に読み込んでください。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーにまたがるデバッグ手順です。AES-GCM 固有のデバッグ（未対応のキーサイズ、入力サイズ超過、復号時のタグ検証失敗）は、この手順に追加して適用します。