Doca Sha Offload Engine

DOCA SHA Offload Engine

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?". Answered by the "when this engine is the right surface" rule in CAPABILITIES.md ## Capabilities and modes
  • the engine-load mechanics in TASKS.md ## configure.
• "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 CAPABILITIES.md ## Observability (the SHA-224 negative test and the -engine_impl flag) + the verification flow in TASKS.md ## test.
• "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 CAPABILITIES.md ## Capabilities and modes
  • the openssl speed perf-comparison pattern in TASKS.md ## test.
• "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 CAPABILITIES.md ## Capabilities and modes.
• "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 CAPABILITIES.md ## Capabilities and modes.
• "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 CAPABILITIES.md ## Version compatibility (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).

Audience

This skill serves external developers and operators who have an existing OpenSSL-based pipeline doing SHA hashing and want to offload SHA onto DOCA SHA without rewriting their application against the doca-sha C API. Concretely:

• A developer integrating DOCA SHA acceleration into a service that already uses EVP_Digest for SHA-1 / SHA-256 / SHA-512.
• An operator deploying an openssl dgst / openssl speed based pipeline and wanting to measure the win from DOCA SHA offload without changing the pipeline's invocation surface.
• An SRE / performance engineer producing a "this is the engine-offload win vs CPU SHA on this message-size mix" artifact to inform a code-change decision (e.g. "should we adopt the engine as-is, or rewrite to doca-sha for finer control?").
• An AI agent answering "can I drop DOCA SHA into this OpenSSL-based app without code changes" honestly — with the verified algorithm-coverage matrix, the message-size window, and the verification pattern that proves the engine actually ran.

It is not for users building a new SHA pipeline from scratch (route to ../../libs/doca-sha/SKILL.md), not for users wanting MD5 / SHA-2-224 / SHA-3 / HMAC-SHA offload (the engine does not implement those — the verified surface per the engine's source is one-shot SHA-1, SHA-256, SHA-512 via EVP_Digest), and not a substitute for the public DOCA SHA programming guide.

Language scope

The DOCA SHA Offload Engine is shipped as a C dynamic shared object (libdoca_sha_offload_engine.so) built from doca/tools/sha_offload_engine/{engine/doca_sha_offload_engine.c, lib/doca_sha_offload_lib.{c,h}} via meson. Its consumer interface is OpenSSL's ENGINE API; any language that calls OpenSSL (C, C++, Rust via openssl crate, Python via cryptography and pyca/cryptography's backend, Node via node:crypto) can therefore use the engine, provided the language binding either calls ENGINE_load_dynamic / ENGINE_by_id directly or honors an OpenSSL engines config that loads it. The skill's language-neutral contribution is the engine-load mechanics and the verification pattern; the OpenSSL ENGINE API is the contract.

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, streaming/incremental SHA via EVP_DigestUpdate chains that the engine treats as one-shot only).