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 plus engine logs and a known-answer comparison; 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. Pick the device. List devices with doca_caps --list-devs, confirm the SHA-capable PCIe address with the user, and pass it explicitly through the set_pci_addr ctrl-cmd at load time rather than relying on the built-in 03:00.0 default.
3. Confirm the engine file. Use the installed path ${DOCA_DIR}/tools/doca_sha_offload_engine/libdoca_sha_offload_engine.so. Confirm with the operator that ${DOCA_DIR} points at the DOCA install root and that the file came from the DOCA package, is owned by root, and is writable only by its owner. Take the path only from the verified install; any other path (including a local build) needs explicit user confirmation and the same check.
4. Check OpenSSL. Run openssl version. The engine is tested on 1.1.1f and 3.0.2; on other versions warn the user and ask before loading. Some OpenSSL builds leave out engine support and cannot load the engine at all.
5. Load probe: openssl engine dynamic -pre NO_VCHECK:1 -pre SO_PATH:${DOCA_DIR}/tools/doca_sha_offload_engine/libdoca_sha_offload_engine.so -pre LOAD -pre "set_pci_addr:<bdf>" -vvv -t -c. NO_VCHECK:1 turns off OpenSSL's version handshake, so use it only against the verified installed engine and only when the shipped readme calls for it on the detected OpenSSL version; a version mismatch can crash the process.
6. Positive test: openssl dgst -sha256 -engine ${DOCA_DIR}/tools/doca_sha_offload_engine/libdoca_sha_offload_engine.so -engine_impl <file> reports the engine was set.
7. Negative test: an unsupported digest (-sha224) with -engine_impl is expected to fail with the engine selected, per the shipped readme for the host OpenSSL version. This shows the engine was selected and consulted, not that the hardware computed the hash; corroborate with engine logs (raise DOCA_LOG_LEVEL) and a known-answer comparison against the software SHA result.
8. Performance: compare openssl speed -evp sha256 with and without the engine (add -async_jobs for parallelism). Run it only on an idle, non-production host after the user confirms the device is not serving live traffic; keep runs short, start with a modest -async_jobs value, and raise it only with user agreement. Report measured numbers only; never quote numbers from memory.

Instructions

Follow Loading order below. Open TASKS.md for configure / run. Open CAPABILITIES.md for when offload wins and how to verify it. The safety overlay and the install, build, and run safeguards live in those two files; read the relevant section before running those workflows. 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 TASKS.md 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 CAPABILITIES.md 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 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 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?". Chained calls that OpenSSL hands to the engine are buffered and offloaded once at Final; the whole message must fit within the device maximum source buffer size, and buffering costs memory. 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 "offload engaged" evidence pattern in the capabilities companion (the SHA-224 negative test and the -engine_impl flag, corroborated by engine logs and a known-answer comparison) + 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. Do not load this skill for users wanting algorithms the engine does not implement (MD5, SHA-3, SHA-224, HMAC-SHA), or true incremental hashing where the message is too large for one DOCA SHA task (chained EVP_DigestUpdate calls are buffered and offloaded once at Final).

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• CAPABILITIES.md — 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 (SHA-224, MD5, SHA-3, HMAC-SHA, and incremental hashing too large for one task; chained EVP_DigestInit_ex / EVP_DigestUpdate / EVP_DigestFinal_ex calls are buffered and sent to 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 "offload engaged" evidence pattern using the SHA-224 negative test and -engine_impl), and the safety overlay.
• TASKS.md — 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; always confirm the device and pass set_pci_addr explicitly), 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. That sequence makes the engine the process-wide provider for SHA-1, SHA-256 and SHA-512; TASKS.md describes the known-answer comparison and operator review required before production use.
• 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/).
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 CAPABILITIES.md.
3. For step-by-step workflows — install, configure, build, modify, run, test, debug, use — see TASKS.md.

Related skills

• ../../libs/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.
• doca-version — 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 — 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 — env preparation, install verification, the libssl-dev install path, and the NGC DOCA container path.
• doca-public-knowledge-map — 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 — 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.