/doca-sha-offload-engine

license: Apache-2.0
name: doca-sha-offload-engine
description: >
  Use this skill when wiring the DOCA SHA Offload Engine
  (an OpenSSL ENGINE) into an existing OpenSSL pipeline
  to offload one-shot SHA-1, SHA-256, or SHA-512
  (EVP_Digest) onto DOCA SHA hardware without rewriting
  against doca-sha. Covers engine load mechanics
  (`openssl engine dynamic`, `set_pci_addr` ctrl,
  `-engine_impl`), the SHA-224 negative test that proves
  offload engaged, the message-size window where offload
  beats CPU SHA, and engine-vs-library selection.
  Trigger even when the user does not say "DOCA SHA
  Offload Engine" or "OpenSSL ENGINE" — typical implicit
  phrasings: "speed up openssl SHA on BlueField",
  "offload SHA without code changes", "is openssl using
  the accelerator or falling back to software", "prove
  DOCA SHA actually ran", "openssl dgst hashed but I'm
  not sure it was offloaded". Refuse and route elsewhere
  for new SHA pipelines (use doca-sha), MD5 / SHA-3 /
  SHA-224 / HMAC-SHA offload, incremental hashing via
  chained `EVP_DigestUpdate`, or OpenSSL PROVIDER authoring.
metadata:
  kind: tool
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on
  Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a
  BlueField DPU or ConnectX NIC attached, plus OpenSSL
  ≥ 1.1.1 and libssl-dev (or distro equivalent) on the
  build host. The engine ships under
  /opt/mellanox/doca/tools/doca_sha_offload_engine/ as
  libdoca_sha_offload_engine.so; reads the user's local
  install via `pkg-config doca-sha` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.

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`](TASKS.md) and start at [`## configure`](TASKS.md#configure) for the PCIe-address configuration and the OpenSSL prerequisites; jump to [`## run`](TASKS.md#run) for the *"load the engine and prove it actually runs"* flow. Open [`CAPABILITIES.md`](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`](../../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`](../../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`](CAPABILITIES.md#capabilities-and-modes)

• the engine-load mechanics in

[`TASKS.md ## configure`](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`](CAPABILITIES.md#observability) (the SHA-224 negative test and the `-engine_impl` flag) + the verification flow in [`TASKS.md ## test`](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`](CAPABILITIES.md#capabilities-and-modes)

• the `openssl speed` perf-comparison pattern in

[`TASKS.md ## test`](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`](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`](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`](CAPABILITIES.md#version-compatibility) (verifi