doca-sha-offload-engine

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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?”*. 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 `engine_readme.md`).

## When to load this skill

Load this skill when the user is — or the agent needs to

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills