doca-sha-offload-engine

DOCA SHA 卸载引擎

示例

• “我能否在现有的 OpenSSL 流程中卸载 SHA，而无需重写？”——这属于本技能范围。加载引擎；不要在这里启动新的 doca-sha 流程。
• “如何证明 OpenSSL 使用了 DOCA SHA，而不是 CPU 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/ 下提供的 OpenSSL ENGINE，以及主机上安装在 ${DOCA_DIR}/tools/doca_sha_offload_engine/ 下的 libdoca_sha_offload_engine.so。目录名变化（源码布局中的 sha_offload_engine 与安装布局中的 doca_sha_offload_engine）是 NVIDIA 的打包惯例，并非组件包不一致；下文两种形式均有出现，指的是处于不同生命周期阶段的同一构件——根据问题所涉阶段（从源码构建或运行时加载）引用相应形式。这不是 CLI——它是由基于 OpenSSL 的应用或 openssl 本身加载的共享对象，可通过 EVP_Digest 接口，将 SHA-1 / SHA-256 / SHA-512（仅支持单次计算）重新路由到 DOCA SHA 硬件路径。打开任务配套文件，从 ## configure 开始，了解 PCIe 地址配置和 OpenSSL 先决条件；如需了解“加载引擎并证明它确实在运行”的流程，则跳转到 ## run。如果问题涉及引擎实际卸载哪些操作、哪些操作会回退、何时使用引擎能提升性能、何时不能，或如何验证卸载确实生效，请打开功能配套文件。如果尚未安装 DOCA，请先转到 doca-setup/SKILL.md。 如果用户要从零开始构建新的 SHA 流程（而非封装现有的基于 OpenSSL 的流程），则此技能并不适用——请改为转到 ../../libs/doca-sha/SKILL.md（doca-sha/SKILL.md）。

此技能擅长回答的示例问题

此技能旨在回答有关 doca-sha-offload-engine 的以下问题类别，每类都附有一个完整示例。 类别才是关键；完整示例只是其中一个实例。

• “我有一个基于 OpenSSL 的现有流水线在计算 SHA；能否将 SHA 卸载到 DOCA，而不重写应用？” — 完整示例：“应用使用 EVP_DigestInit_ex / EVP_DigestUpdate / EVP_DigestFinal_ex 配合 EVP_sha256()；我能否通过加载引擎直接启用 DOCA-SHA 卸载？”。由能力配套文档中的 “何时适合使用此引擎” 规则，以及任务配套文档中的引擎加载机制解答。
• “引擎真的加载了吗？还是 OpenSSL 只是回退到了软件 SHA？” — 完整示例：“我的 openssl dgst 调用已完成；如何确认确实由 DOCA SHA 执行了计算，而不是 OpenSSL 悄悄使用了软件路径？”。由能力配套文档中的 “证明引擎确实运行” 模式（SHA-224 负向测试和 -engine_impl 标志），以及任务配套文档中的验证流程解答。
• “对于多大的消息，引擎卸载相比 CPU SHA 更有优势？” — 完整示例：“我的流水线每次计算 4 KB 数据块的哈希；在这种情况下，引擎有优势吗？还是往返调用 DOCA SHA 的开销超过了 CPU 计算哈希本身的成本？”。由能力配套文档中的消息大小范围规则，以及任务配套文档中的 openssl speed 性能对比模式解答。
• “引擎实际支持哪些 SHA 算法？不支持的算法会怎样？” — 完整示例：“我的流水线混用 SHA-1、SHA-256、SHA-512 和 SHA-224；引擎对每种算法会如何处理？”。由能力配套文档中的算法覆盖矩阵解答。
• “我应该使用此引擎，还是直接调用 doca-sha？” — 完整示例：“我正在从头编写一项新服务；引擎能减少工作量吗？还是会增加不必要的复杂性？”。由能力配套文档中的 “引擎与库” 选择表解答。
• “引擎需要什么版本的 OpenSSL？OpenSSL 3.x 弃用 ENGINE API 又会有什么影响？” — 完整示例：“我的主机安装了 OpenSSL 3.0；引擎还能加载吗？”。由能力配套文档中的版本说明解答（已验证的适用范围：随附的 readme.md 记载，此引擎适用于 Ubuntu 20.04 上的 OpenSSL 1.1.1f，以及 Ubuntu 22.04 上的 OpenSSL 3.0.2）。

何时加载此技能

当用户要在安装了 DOCA 且配有支持 SHA 的设备的主机上，将 DOCA SHA Offload Engine 部署到基于 OpenSSL 的流水线时，或 Agent 需要执行此操作时，加载此技能。具体场景包括：

• 将引擎接入现有的基于 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），也不要加载此技能。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• 功能配套文件——说明引擎卸载了哪些工作（已验证：通过 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 模式）；引擎与库之间的选择规则；卸载能带来性能优势时的消息大小范围规则；已验证的 ctrl-cmd 接口（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，并提供 set_pci_addr ctrl-cmd 和构建时覆盖选项，详见随附的 test_cmdline_mode/readme.md）、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 设备。集成前，请以同一用户身份确认设备可见，并运行引擎加载冒烟测试；如果任一操作因权限错误失败，请停止并转交给 doca-setup，不要擅自猜测组、ACL 或 sudo 策略。

此技能明确不提供的内容

此技能提供的是Agent 指引，而非示例或脚本包。它明确不包含以下内容，且拉取请求不应添加：

• 预先编写的 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-sha 库文档中。
• 根据 Agent 记忆提供的性能数据。 引擎能够带来性能优势的消息大小范围取决于设备、固件、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 任务范围进行精细控制（partial-hash、自定义缓冲区权限、针对特殊消息大小的 cap-query）时，库才是合适的选择。该引擎包装的是 一次性 任务；根据 doca-sha/SKILL.md，库同时提供一次性任务和 partial-hash。
• doca-version/SKILL.md—— 规范的版本检测链。该引擎有一个双轴版本覆盖层（DOCA 侧和 OpenSSL 侧）；版本技能包含此技能在此基础上采用的四路匹配规则。
• 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 控制项是针对该组件的覆盖层，但任何底层主机端更改（固件烧录、BFB 重刷）都必须遵循元策略。