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).

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 (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.

• 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),

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 TASKS.md ## run).

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 TASKS.md ## test 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

• Read this SKILL.md 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/).

• **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.**

• **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

../../libs/doca-sha/CAPABILITIES.md#capabilities-and-modes.

• 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.