/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - sha
    - openssl
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField-2 DPU (not BF-3)
  attached, plus OpenSSL ≥ 1.1.1 (libssl-dev for ENGINE API callers)
  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}. The validation
  steps require a live DOCA install.

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 installed by the `doca-sha-offload-engine` package under `${DOCA_DIR}/tools/doca_sha_offload_engine/` as `libdoca_sha_offload_engine.so`, next to its `engine_readme.md`. 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?”*.