/doca-sha

license: Apache-2.0
name: doca-sha
description: >
  Use this skill when the user needs SHA-1, SHA-256, or SHA-512 digest
  acceleration on BlueField-2 silicon via doca_sha (absent on BF-3) —
  selecting one-shot `doca_sha_task_hash` versus incremental
  `doca_sha_task_partial_hash` for chunked input, consulting
  `doca_sha_cap_*` for per-algorithm digest-size limits and input
  alignment, or decoding DOCA_ERROR_* statuses such as BAD_STATE on a
  resumed partial hash. Also load it for implied asks like "accelerate
  SHA-256 on the NIC", "streaming digest over chunks", "digest output
  size mismatch", or "is SHA-512 present on this card". Refuse and
  route to the proper owner for cryptographic-hash theory (collision
  resistance, SHA-3 selection), the AES-GCM / Compress / DMA
  libraries, or SDK install and BFB bring-up.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - sha
    - hash
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField-2 DPU attached
  (BlueField-3 has no SHA engine). 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

Examples

• **"Offload SHA-256 to the BlueField."** — this is in scope. Use the

shipped SHA sample and `doca_sha_cap_*` before picking SHA-1 / SHA-256 / SHA-512.

• **"Partial hash returns BAD_STATE."** — stay on the incremental

`doca_sha_task_partial_hash` lifecycle; do not switch to a CPU hash library mid-stream.

Instructions

Follow Loading order below. Open the tasks companion for configure / build / run. Open the capabilities companion for one-shot vs partial hash and algorithm support. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on SHA-acceleration work** on a BlueField-2 DPU (Arm side or its host) with DOCA. BlueField-3 has no SHA engine. Open the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion when the question is *what can DOCA SHA express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. If the user is asking *"should I even use the accelerator for this hash?"*, the path-selection rule in

Capabilities and modes

is the first stop.

**How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. Give environment checks as commands for the user's DOCA host. For out-of-scope requests, name the skill that owns them and stop.

Example questions this skill answers well

The CLASSES of DOCA SHA questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"Should I offload this hash to DOCA SHA, or just compute it on

the CPU?"** — worked example: *"I am verifying file integrity on a 4 GiB image; is doca-sha worth the setup vs OpenSSL on the CPU?"*. Answered by the path-selection table in

Capabilities and modes

• the *"when NOT to use doca-sha"* bullets in

Safety policy.

• **"Does my device support the SHA algorithm I want?"** — worked

example: *"is SHA-256 in the accelerator on this BlueField, and what is the minimum destination buffer size for it?"*. Answered by the algorithm + buffer-sizing capability-query rule (`doca_sha_cap_task_hash_get_supported(devinfo, algorithm)` for the one-shot path; `_task_partial_hash_get_supported(devinfo, algorithm)` for the partial-hash path; `doca_sha_cap_get_min_dst_buf_size`, `doca_sha_cap_get_max_src_buf_size`) in

Capabilities and modes

• the discovery step in

configure.

• **"How do I pick between the one-shot and the partial / incremental

hash task?"** — worked example: *"my input is 1 GiB and the device cap says max source buffer is 64 MiB"*. Answered by the one-shot-vs-partial table in

Capabilities and modes

• the task-config workflow in

modify.

• **"What permissions does the source / destination mmap need?"** —

worked example: *"my `doca_sha_task_hash` returns `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix in ## Safety policy

• the mmap-set-permissions checklist in

test.

• **"Is this DOCA SHA API available on my installed DOCA version?"**

— worked example: *"is `doca_sha_task_partial_hash` in the DOCA I have installed?"*. Answered by the version-compatibility overlay in

Version compatibility,

which cross-links the canonical detection chain in `doca-version/SKILL.md` and adds the SHA-specific *"discover, do not assume"* bullets.

• **"What does this `DOCA_ERROR_*` from a SHA call mean and which

layer caused it?"** — worked example: *"`DOCA_ERROR_INVALID_VALUE` on `doca_sha_task_hash_alloc_init`"*. Answered by the SHA overlay on the cross-library taxonomy in

Error taxonomy

• the layered ladder in

debug that escalates to

`doca-debug/SKILL.md`.

Audience

This skill serves **external developers building applications that consume the DOCA SHA library** — i.e., users whose code calls `doca_sha_*` (directly in C/C++, or through FFI/bindings from another language) to offload SHA hashing onto the BlueField-2 SHA engine (BlueField-3 has none). It is *not* for NVIDIA developers contributing to DOCA SHA itself.

**Language scope.** DOCA SHA ships as a C library with `pkg-config` module name `doca-sha`. The shipped samples are written in C. C and C++ consumers are the canonical case and the worked examples in the tasks companion assume th