doca-sha-offload-engine

# DOCA SHA Offload Engine ## Examples - **"Can I offload SHA in an existing OpenSSL pipeline without rewriting?"** — this is in scope. Load the engine; do not start a new `doca-sha` pipeline here. - **"How do I prove OpenSSL used DOCA SHA, not CPU SHA?"** — use the SHA-224 negative test; do not treat a successful digest as proof of offload. ## Quick answer (answer from this file) 1. **Device gate first.** The DOCA SHA engine exists only on BlueField-2; BlueField-3 has no SHA acceleration engine (public DOCA SHA guide), so there is nothing to offload there: say so and stop. 2. **Load probe:** `openssl engine dynamic -pre NO_VCHECK:1 -pre SO_PATH:<engine .so> -pre LOAD -vvv -t -c`. 3. **Positive test:** `openssl dgst -sha256 -engine <engine .so> -engine_impl <file>` reports the engine was set. 4. **Negative test:** an unsupported digest (`-sha224`) must fail with the engine selected; it must not silently fall back. 5. **Performance:** compare `openssl speed -evp sha256` with and without the engine (add `-async_jobs` for parallelism). Report measured numbers only; never quote numbers from memory. ## Instructions Follow Loading order below. Open the tasks companion for configure / run. Open the capabilities companion for when offload wins and how to verify it. Do not open every companion file. **Where to start:** This is a tool skill for the OpenSSL ENGINE shipped in the DOCA SOURCE tree under `doca/tools/sha_offload_engine/` and INSTALLED on the host under `${DOCA_DIR}/tools/doca_sha_offload_engine/` as `libdoca_sha_offload_engine.so`. The directory-name shift (`sha_offload_engine` in the source layout vs `doca_sha_offload_engine` in the install layout) is an NVIDIA packaging convention, not a bundle inconsistency; both forms appear below and are the same artifact at different lifecycle stages — quote whichever the prompt is about (build-from-source vs runtime-load). It is **not a CLI** — it is a shared object loaded by an OpenSSL-based application or by `openssl` itself, that re-routes SHA-1 / SHA-256 / SHA-512 (one-shot only, via the `EVP_Digest` interface) onto the DOCA SHA hardware path. Open the tasks companion and start at `## configure` for the PCIe-address configuration and the OpenSSL prerequisites; jump to `## run` for the *"load the engine and prove it actually runs"* flow. Open the capabilities companion when the question is *what the engine actually offloads vs falls back to*, *when the engine is a perf win vs not*, or *how to verify offload actually engaged*. If DOCA is not installed yet, route to `doca-setup/SKILL.md` first. If the user is building a new SHA pipeline from scratch (not wrapping an existing OpenSSL-based one), this skill is the wrong surface — route to `../../libs/doca-sha/SKILL.md` (`doca-sha/SKILL.md`) instead. ## Example questions this skill answers well The CLASSES of `doca-sha-offload-engine` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance. - **"I have an existing OpenSSL-based pipeline doing SHA; can I offload the SHA to DOCA without rewriting the app?"** — worked example: *"the app uses `EVP_DigestInit_ex` / `EVP_DigestUpdate` / `EVP_DigestFinal_ex` against `EVP_sha256()`; can I drop in DOCA-SHA offload via an engine load?"*. Answered by the *"when this engine is the right surface"* rule in the capabilities companion + the engine-load mechanics in the tasks companion. - **"Did the engine actually load? Or did OpenSSL just fall back to software SHA?"** — worked example: *"my `openssl dgst` invocation completed; how do I know DOCA SHA actually did the work and OpenSSL did not silently use the software path?"*. Answered by the *"prove the engine actually ran"* pattern in the capabilities companion (the SHA-224 negative test and the `-engine_impl` flag) + the verification flow in the tasks companion. - **"For what message-size range is the engine offload a win vs CPU SHA?"** — worked example: *"my pipeline hashes 4 KB blocks at a time; is the engine a win there, or does the round-trip to DOCA SHA cost more than the CPU hash itself?"*. Answered by the message-size-window rule in the capabilities companion + the `openssl speed` perf-comparison pattern in the tasks companion. - **"What SHA algorithms does the engine actually support — and what happens for the ones it does not?"** — worked example: *"my pipeline mixes SHA-1, SHA-256, SHA-512, and SHA-224 — what does the engine do for each?"*. Answered by the algorithm-coverage matrix in the capabilities companion. - **"Should I use this engine, or call doca-sha directly?"** — worked example: *"I am writing a new service from scratch; does the engine save me work or does it add complexity I do not need?"*. Answered by the *"engine vs library"* selection table in the capabilities companion. - **"What OpenSSL versions does the engine require, and what about OpenSSL 3.x's deprecation of the ENGINE API?"** — worked example: *"my host has OpenSSL 3.0; will the engine still load?"*. Answered by the version overlay in the capabilities companion (verified surface: the engine is documented for OpenSSL 1.1.1f on Ubuntu 20.04 and OpenSSL 3.0.2 on Ubuntu 22.04 per the shipped `readme.md`). ## When to load this skill Load this skill when the user is — or the agent needs to — deploy the DOCA SHA Offload Engine into an OpenSSL-based pipeline on a host with DOCA installed and a SHA-capable device. Concretely: - Wiring the engine into an existing OpenSSL-based application or `openssl` CLI invocation, with the intent of no source-level code changes (or only the minimum `ENGINE_load_dynamic` / `ENGINE_by_id` block shown in the verified `readme.md`). - Verifying the engine actually engaged for the hot-path digests (the *"is offload real or did OpenSSL fall back to software"* question). - Characterizing the message-size range over which the engine is a perf win vs the CPU `sha1` / `sha256` / `sha512` paths. - Deciding between *"adopt the engine"* (existing pipeline, minimal change) and *"rewrite to doca-sha"* (new pipeline, fine-grained control needed). Do **not** load this skill for users building a new SHA-pipeline from scratch — route to `../../libs/doca-sha/SKILL.md` (`doca-sha/SKILL.md`). Do not load this skill for users wanting algorithms the engine does not implement (MD5, SHA-3, SHA-224, HMAC-SHA, streaming/incremental SHA via `EVP_DigestUpdate` chains that the engine treats as one-shot only). ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - the capabilities companion — what the engine offloads (verified: one-shot SHA-1, SHA-256, SHA-512 via the OpenSSL `EVP_Digest` high-level interface), what it does NOT offload (anything else — including SHA-224, MD5, SHA-3, HMAC-SHA, and any chained `EVP_DigestInit_ex` / `EVP_DigestUpdate` / `EVP_DigestFinal_ex` pattern that the engine implements by buffering and then calling DOCA SHA in one shot at `Final`), the engine-vs-library selection rule, the message-size-window rule for when offload is a perf win, the verified ctrl-cmd surface (`set_pci_addr`), the version overlay (OpenSSL ≥ 1.1.1; the engine's shipped tests cover OpenSSL 1.1.1f and OpenSSL 3.0.2 per the `readme.md`; OpenSSL 3.x deprecates the ENGINE API but still supports it via the legacy code path), the layered error taxonomy, the observability surface (the *"prove offload engaged"* pattern using the SHA-224 negative test and `-engine_impl`), and the safety overlay. - the tasks companion — step-by-step workflows for the in-scope task verbs: `install`, `configure` (PCIe address selection — the engine defaults to `03:00.0` and exposes the `set_pci_addr` ctrl-cmd plus a build-time override per the shipped `test_cmdline_mode/readme.md`), `build` (the `meson` flow), `modify` (refuses source patching; modify the load-time invocation and the PCIe address instead), `run` (load the engine via `openssl engine dynamic`; the verification pattern; the OpenSSL programmatic `ENGINE_load_dynamic` block), `test` (the *"prove the engine ran"* SHA-224 negative test; the `openssl speed` perf comparison; the message-size window characterization), `debug` (walk the error taxonomy layer by layer), `use` (the engine-vs-library decision for the user's specific pipeline), plus a `Deferred task verbs` block. The skill assumes a host where DOCA is already installed, OpenSSL ≥ 1.1.1 is present (`libssl-dev` or equivalent), and the deploying user can access the selected DOCA SHA PCIe device. Verify device visibility and run the engine-load smoke as that same user before integration; if either fails with a permission error, stop and route to `doca-setup` rather than guessing a group, ACL, or `sudo` policy. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or scripts bundle. It deliberately does not contain — and pull requests should not add: - **Pre-written OpenSSL ENGINE application source code** beyond the verbatim verified block in the shipped `readme.md` (the `ENGINE_load_dynamic` / `ENGINE_by_id` / `ENGINE_ctrl_cmd_string` / `ENGINE_init` / `ENGINE_set_default_digests` sequence, cross-referenced into the tasks companion). The shipped readme is the worked example. - **A `samples/`, `bindings/`, or `reference/` subtree.** This is a thin loader for a shipped shared-object; substantive material lives in the shipped `readme.md` and the doca-sha library docs. - **Performance numbers from agent memory.** The message-size-window where the engine wins is device-, firmware-, OpenSSL-version-, and workload-specific. The `openssl speed` comparison pattern in the tasks companion is the way to capture it on the user's actual hardware; quoting a number from memory is the cross-platform failure mode this skill exists to prevent. - **Wrappers, parsers, or scripts** in any language that consume the engine's stdout or the `openssl speed` output format. ## Loading order 1. Read this skill first to confirm the user's question is in scope (the user actually has an existing OpenSSL-based pipeline and wants to offload to DOCA SHA *without* code changes; if the user is building from scratch, route to `../../libs/doca-sha/` (`doca-sha/SKILL.md`)). 2. **For what the engine offloads vs falls back, the engine-vs-library selection rule, the message-size- window rule, the version overlay, the error taxonomy, the observability surface (and the prove-offload- actually-engaged pattern), and the safety overlay, see the capabilities companion.** 3. **For step-by-step workflows — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see the tasks companion.** ## Related skills - `../../libs/doca-sha/SKILL.md` (`doca-sha/SKILL.md`) — the underlying DOCA SHA library. The engine is a thin OpenSSL-ENGINE wrapper around doca-sha; when the user needs fine-grained control over the SHA task surface (partial-hash, custom buffer permissions, cap-query for unusual message sizes), the library is the right answer. The engine wraps the *one-shot* task; the library exposes both one-shot and partial- hash per `doca-sha/SKILL.md`. - `doca-version/SKILL.md` — the canonical version-detection chain. The engine has a TWO-axis version overlay (DOCA-side and OpenSSL-side); the version skill carries the four-way match rule this skill layers on top of. - `doca-debug/SKILL.md` — the cross-cutting debug ladder. The engine surfaces its own error taxonomy; when the cause is below DOCA (driver, firmware), the taxonomy hands off here. - `doca-setup/SKILL.md` — env preparation, install verification, the `libssl-dev` install path, and the NGC DOCA container path. - `doca-public-knowledge-map/SKILL.md` — routing to the public DOCA SHA documentation set on `docs.nvidia.com/doca/sdk/` and to the OpenSSL ENGINE / `openssl-engine` upstream documentation on `openssl.org`. - `doca-hardware-safety/SKILL.md` — the bundle-wide hardware-safety meta-policy. The engine binds to a specific PCIe device; the `set_pci_addr` ctrl is the artifact-specific overlay, but any host-side change underneath (firmware burn, BFB reflash) runs through the meta-policy.