doca-sha-offload-engine

DOCA SHA オフロードエンジン

例

• 「既存の OpenSSL パイプラインを作り直さずに、SHA をオフロードできますか？」 — これは対象範囲内です。エンジンをロードしてください。ここでは新しい doca-sha パイプラインを開始しないでください。
• 「OpenSSL が CPU SHA ではなく DOCA SHA を使ったことを証明するにはどうすればよいですか？」 — SHA-224 のネガティブテストを使用してください。ダイジェストが正常に生成されたことを、オフロードの証拠として扱わないでください。

簡単な回答（このファイルに基づいて回答）

1. まずデバイスを確認します。 DOCA SHA エンジンが存在するのは BlueField-2 のみです。BlueField-3 には SHA アクセラレーションエンジンがありません（DOCA SHA の公開ガイド）。そのため、そこでオフロードできる処理はありません。そう伝えて終了してください。
2. ロードの確認： openssl engine dynamic -pre NO_VCHECK:1 -pre SO_PATH:<engine .so> -pre LOAD -vvv -t -c。
3. ポジティブテスト： openssl dgst -sha256 -engine <engine .so> -engine_impl <file> は、エンジンが設定されたことを報告します。
4. ネガティブテスト： サポートされていないダイジェスト（-sha224）を、エンジンを選択した状態で実行すると失敗しなければなりません。暗黙的にフォールバックしてはいけません。
5. パフォーマンス： エンジンありとなしで openssl speed -evp sha256 を比較します（並列処理には -async_jobs を追加します）。測定値のみを報告し、記憶に頼って数値を引用しないでください。

手順

以下の「ロード手順」に従ってください。設定／実行にはタスクのコンパニオンファイルを参照してください。オフロードが有効なケースと検証方法については、機能のコンパニオンファイルを参照してください。すべてのコンパニオンファイルを開く必要はありません。

最初に確認する項目： これは、DOCA SOURCE ツリーの doca/tools/sha_offload_engine/ に含まれ、ホスト上の ${DOCA_DIR}/tools/doca_sha_offload_engine/ に libdoca_sha_offload_engine.so としてインストールされる OpenSSL ENGINE のツールスキルです。ディレクトリ名がソースレイアウトの sha_offload_engine からインストールレイアウトの doca_sha_offload_engine に変わるのは、NVIDIA のパッケージング規約によるものであり、バンドルの不整合ではありません。以下ではどちらの形式も登場しますが、ライフサイクル上の段階が異なる同一のアーティファクトです。質問がビルド元ソースか実行時のロードかに応じて、該当する形式を引用してください。これは CLI ではありません。OpenSSL ベースのアプリケーションまたは openssl 自体によってロードされる共有オブジェクトで、SHA-1／SHA-256／SHA-512（EVP_Digest インターフェイス経由のワンショット処理のみ）を DOCA SHA ハードウェアパスに振り分けます。タスクのコンパニオンファイルを開き、PCIe アドレスの設定と OpenSSL の前提条件については ## configure から始めてください。「エンジンをロードして、実際に動作することを確認する」手順に進むには、## run に移動してください。エンジンが実際にオフロードする処理とフォールバックする処理、エンジンがパフォーマンス上の利点をもたらす場合とそうでない場合、またはオフロードが実際に有効になったことの検証方法について質問された場合は、機能のコンパニオンファイルを参照してください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。 既存の OpenSSL ベースのパイプラインをラップするのではなく、新しい SHA パイプラインを一から構築する場合、このスキルは適切な対象ではありません。その場合は ../../libs/doca-sha/SKILL.md（doca-sha/SKILL.md）に案内してください。

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

doca-sha-offload-engine に関する、このスキルが回答できる質問のクラスを、実例とともに紹介します。 重要なのは質問のクラスであり、実例はその一例です。

• 「SHA を実行する既存の OpenSSL ベースのパイプラインがあります。アプリを書き直さずに、SHA を DOCA にオフロードできますか？」 — 実例：「アプリは EVP_sha256() に対して EVP_DigestInit_ex ／ EVP_DigestUpdate ／ EVP_DigestFinal_ex を使用しています。エンジンを読み込むだけで DOCA-SHA オフロードに切り替えられますか？」。 capabilities コンパニオンの 「このエンジンが適切なインターフェースとなる場合」 のルールと、tasks コンパニオンのエンジン読み込みの仕組みが回答します。
• 「エンジンは実際に読み込まれましたか？ それとも OpenSSL はソフトウェア SHA にフォールバックしただけですか？」 — 実例：「openssl dgst の実行は完了しました。DOCA SHA が実際に処理を行い、OpenSSL がソフトウェアのパスをひそかに使わなかったことは、どうすれば確認できますか？」。 capabilities コンパニオンの 「エンジンが実際に実行されたことを証明する」 パターン（SHA-224 のネガティブテストと -engine_impl フラグ）と、tasks コンパニオンの検証フローが回答します。
• 「どのメッセージサイズの範囲なら、CPU SHA と比べてエンジンへのオフロードが有利ですか？」 — 実例：「パイプラインは一度に 4 KB のブロックをハッシュします。この場合、エンジンは有利ですか？ それとも DOCA SHA との往復にかかるコストが、CPU ハッシュ自体のコストを上回りますか？」。 capabilities コンパニオンのメッセージサイズ範囲のルールと、tasks コンパニオンの openssl speed によるパフォーマンス比較パターンが回答します。
• 「エンジンが実際にサポートしている SHA アルゴリズムは何ですか？ サポートされていないものはどうなりますか？」 — 実例：「パイプラインでは SHA-1、SHA-256、SHA-512、SHA-224 が混在しています。それぞれに対してエンジンはどのように動作しますか？」。 capabilities コンパニオンのアルゴリズム対応表が回答します。
• 「このエンジンを使うべきですか、それとも doca-sha を直接呼び出すべきですか？」 — 実例：「新しいサービスをゼロから作成しています。エンジンを使えば作業が減りますか？ それとも、不要な複雑さが増えるだけですか？」。 capabilities コンパニオンの 「エンジンとライブラリー」 の選択表が回答します。
• 「エンジンに必要な OpenSSL のバージョンは何ですか？ また、OpenSSL 3.x での ENGINE API の非推奨化についてはどうですか？」 — 実例：「ホストに OpenSSL 3.0 がインストールされています。エンジンは引き続き読み込めますか？」。 capabilities コンパニオンのバージョン情報が回答します（検証済みの対象環境：同梱の readme.md には、Ubuntu 20.04 上の OpenSSL 1.1.1f と Ubuntu 22.04 上の OpenSSL 3.0.2 が記載されています）。

このスキルを読み込む場合

ユーザーが DOCA をインストール済みで SHA 対応デバイスを備えたホスト上の OpenSSL ベースのパイプラインに DOCA SHA Offload Engine を導入する場合、またはエージェントがその導入を必要とする場合に、このスキルを読み込みます。具体的には、次のような場合です。

• 既存の OpenSSL ベースのアプリケーションや openssl CLI の呼び出しにエンジンを組み込み、ソースコードを変更しない（または、検証済みの readme.md に示されている ENGINE_load_dynamic ／ ENGINE_by_id ブロックだけを最小限変更する）ことを目指す場合。
• ホットパスのダイジェストでエンジンが実際に使用されたことを検証する場合（「オフロードは実際に行われたのか、それとも OpenSSL がソフトウェアにフォールバックしたのか」 という質問）。
• CPU の sha1 ／ sha256 ／ sha512 パスと比べて、エンジンのパフォーマンスが有利となるメッセージサイズの範囲を評価する場合。
• 「エンジンを採用する」（既存のパイプラインで、変更を最小限にする）か、「doca-sha に書き換える」（新しいパイプラインで、細かな制御が必要）かを判断する場合。

新しい SHA パイプラインをゼロから構築するユーザーには、このスキルを読み込まないでください。../../libs/doca-sha/SKILL.md（doca-sha/SKILL.md）に誘導してください。 エンジンが実装していないアルゴリズム（MD5、SHA-3、SHA-224、HMAC-SHA、およびエンジンがワンショットのみとして扱う EVP_DigestUpdate チェーンによるストリーミング／インクリメンタル SHA）を使いたいユーザーには、このスキルを読み込まないでください。

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

これは薄いローダーです。実質的な情報は、次の2つの補足ファイルに記載されています。

• 機能の補足 — エンジンがオフロードする処理（OpenSSL の EVP_Digest 高水準インターフェイスを介した、ワンショットの SHA-1、SHA-256、SHA-512 であることを検証済み）、オフロードしない処理（それ以外すべて。SHA-224、MD5、SHA-3、HMAC-SHA、およびエンジンがバッファーに蓄積してから Final で DOCA SHA をワンショットで呼び出すことで実装する、あらゆる EVP_DigestInit_ex／EVP_DigestUpdate／EVP_DigestFinal_ex の連鎖パターンを含みます）、エンジンとライブラリの選択ルール、オフロードがパフォーマンス上有利になるメッセージサイズの範囲のルール、検証済みの制御コマンド（set_pci_addr）、バージョンに関する補足（OpenSSL ≥ 1.1.1。エンジンに同梱されているテストは、readme.md によると OpenSSL 1.1.1f と OpenSSL 3.0.2 を対象としています。OpenSSL 3.x では ENGINE API は非推奨になっていますが、レガシーコードパスを通じて引き続きサポートされています）、階層化されたエラー分類、可観測性に関する情報（SHA-224 の否定テストと -engine_impl を使って「オフロードが実行されたことを証明する」パターン）、および安全性に関する補足です。
• タスクの補足 — 対象範囲内のタスク動詞に対応する、手順ごとのワークフローです。install、configure（PCIe アドレスの選択 — エンジンのデフォルトは 03:00.0 で、同梱の test_cmdline_mode/readme.md によると、set_pci_addr 制御コマンドとビルド時のオーバーライドを利用できます）、build（meson のフロー）、modify（ソースへのパッチ適用は拒否します。代わりに、ロード時の呼び出し方法と PCIe アドレスを変更してください）、run（openssl engine dynamic でエンジンをロードする方法、検証パターン、OpenSSL のプログラムから呼び出す ENGINE_load_dynamic ブロック）、test（「エンジンが実行されたことを証明する」SHA-224 の否定テスト、openssl speed によるパフォーマンス比較、メッセージサイズ範囲の評価）、debug（エラー分類を階層ごとに確認）、use（ユーザー固有のパイプラインにおけるエンジンとライブラリの選択）に加え、Deferred task verbs ブロックも含まれます。

このスキルは、DOCA がすでにインストールされ、OpenSSL ≥ 1.1.1（libssl-dev または同等のもの）が存在し、デプロイするユーザーが選択した DOCA SHA PCIe デバイスにアクセスできるホストを前提としています。統合の前に、その同じユーザーでデバイスが認識されることを確認し、エンジンのロード確認テストを実行してください。どちらかが権限エラーで失敗した場合は、グループ、ACL、sudo ポリシーを推測せず、作業を中止して doca-setup に引き継いでください。

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

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

• OpenSSL ENGINE アプリケーションのソースコードの事前作成版。ただし、同梱の readme.md にある、検証済みのコードブロックをそのまま掲載したものは除きます（ENGINE_load_dynamic／ENGINE_by_id／ENGINE_ctrl_cmd_string／ENGINE_init／ENGINE_set_default_digests の一連の処理で、タスクの補足から相互参照されています）。動作例は同梱の README に記載されています。
• samples/、bindings/、または reference/ のサブツリー。 これは同梱の共有オブジェクトを読み込むための薄いローダーです。実質的な情報は、同梱の readme.md と doca-sh ライブラリのドキュメントに記載されています。
• エージェントの記憶に基づくパフォーマンス数値。 エンジンが有利になるメッセージサイズの範囲は、デバイス、ファームウェア、OpenSSL のバージョン、ワークロードによって異なります。ユーザーが実際に使用するハードウェアでその値を取得する方法は、タスクの補足に記載されている openssl speed の比較パターンです。記憶に基づく数値を示すことは、このスキルが防ごうとしているプラットフォーム間の不具合につながります。
• エンジンの標準出力や openssl speed の出力形式を処理する、あらゆる言語のラッパー、パーサー、スクリプト。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認してください（ユーザーは実際に既存の OpenSSL ベースのパイプラインを使用しており、コードを変更せずに DOCA SHA へオフロードしたいと考えています。新規に構築する場合は、../../libs/doca-sha/（doca-sha/SKILL.md）を案内してください）。
2. エンジンがオフロードする処理とフォールバックする処理、エンジンとライブラリの選択ルール、メッセージサイズの範囲に関するルール、バージョンのオーバーレイ、エラーの分類、可観測性の範囲（およびオフロードが実際に有効になったことを証明するパターン）、安全性のオーバーレイについては、機能に関する補足資料を参照してください。
3. 手順ごとのワークフロー（install、configure、build、modify、run、test、debug、use）については、タスクに関する補足資料を参照してください。

関連スキル

• ../../libs/doca-sha/SKILL.md（doca-sha/SKILL.md）— 基盤となる DOCA SHA ライブラリです。エンジンは doca-sha をラップする薄い OpenSSL-ENGINE ラッパーです。SHA タスクの範囲を細かく制御する必要がある場合（部分ハッシュ、カスタムバッファー権限、特殊なメッセージサイズに対する cap-query）は、ライブラリが適切です。エンジンは ワンショット タスクをラップし、ライブラリは doca-sha/SKILL.md に従ってワンショットと部分ハッシュの両方を提供します。
• doca-version/SKILL.md — バージョン検出の標準的な手順です。エンジンには DOCA 側と OpenSSL 側の 2 軸のバージョンオーバーレイがあり、バージョンスキルにはこのスキルが重ねる 4 通りの一致ルールが記載されています。
• doca-debug/SKILL.md — 複数領域にまたがるデバッグ手順です。エンジンは独自のエラー分類を提示します。原因が DOCA の下層（ドライバー、ファームウェア）にある場合は、この分類からこちらへ引き継ぎます。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、libssl-dev のインストール手順、NGC DOCA コンテナーの手順です。
• doca-public-knowledge-map/SKILL.md — docs.nvidia.com/doca/sdk/ にある公開 DOCA SHA ドキュメント一式、および openssl.org にある OpenSSL ENGINE／openssl-engine の上流ドキュメントへの案内です。
• doca-hardware-safety/SKILL.md — バンドル全体に適用されるハードウェア安全性メタポリシーです。エンジンは特定の PCIe デバイスにバインドされます。set_pci_addr ctrl はこの成果物固有のオーバーレイですが、その下層でホスト側に変更を加える場合（ファームウェアの書き込み、BFB の再フラッシュ）は、いずれもメタポリシーに従います。