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.