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) inCapabilities and modes
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 inVersion 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 inError taxonomy
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 that path. Other-language consumers (Rust, Go,
Python, …) consume the same *.so through FFI or language-specific
bindings; the skill's contribution in that case is to keep the
lifecycle, capability-discovery, permission, error-taxonomy, and
one-shot-vs-partial guidance language-neutral, and to route the
agent to the public C ABI as the authoritative surface that any
wrapper will eventually call.
When to load this skill
Load this skill when the user is doing hands-on DOCA SHA work, in
any language. Concretely:
- Initializing a
doca_sha context on a doca_dev and configuring
at least one task type (doca_sha_task_hash and/or
doca_sha_task_partial_hash) before doca_ctx_start().
- Choosing between the one-shot task (
doca_sha_task_hash —
input fits in a single source buffer, output digest lands in a
single destination buffer) and the partial / incremental task
(doca_sha_task_partial_hash — input streamed in chunks, finalized
separately) for the user's data shape.
- Setting permissions on
doca_mmap correctly for the source buffer
(DOCA_ACCESS_FLAG_LOCAL_READ_ONLY at minimum) and the destination
buffer (DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).
- Sizing the destination buffer against
doca_sha_cap_get_min_dst_buf_size(devinfo, algorithm) and
the source buffer against
doca_sha_cap_get_max_src_buf_size(devinfo).
- Checking which SHA algorithm enums
(
DOCA_SHA_ALGORITHM_SHA1, DOCA_SHA_ALGORITHM_SHA256,
DOCA_SHA_ALGORITHM_SHA512) the active device's accelerator
advertises, via
doca_sha_cap_task_hash_get_supported(devinfo, algorithm) and
doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm) —
both fold task-support and algorithm-support into one call.
- Validating a digest against a published test vector before pushing
bulk input through the accelerator.
- Debugging a
DOCA_ERROR_* returned from a SHA call (lifecycle vs.
buffer-sizing vs. permission vs. unsupported-algorithm) and the
task-completion event on the progress engine.
- Designing or extending non-C bindings (Rust, Go, Python, …) that
wrap the SHA C ABI — for the lifecycle, permission, capability,
and one-shot-vs-partial rules the wrapper must honor.
Do not load this skill for general DOCA orientation, install of
DOCA itself, non-SHA hashing libraries on CPU (use OpenSSL or
similar), or other DOCA libraries. For those, use
doca-public-knowledge-map/SKILL.md.
What this skill provides
This is a thin loader. The body keeps only the orientation
needed to pick the right next file. The substantive SHA-specific
material lives in two companion files:
- the capabilities companion — what DOCA SHA can express on this version:
the two task types (one-shot hash and partial / incremental
hash), the three algorithm enums, the capability-query surface
(
doca_sha_cap_* for algorithm support and buffer sizing), the
SHA error taxonomy (mapped onto the cross-library DOCA_ERROR_*
set), the observability surface (per-task completion events on
the progress engine), the safety policy that gates source /
destination mmap permission decisions, and the path-selection
rule (when to use doca-sha versus a CPU hash or a different
DOCA crypto library).
- the tasks companion — step-by-step workflows for the six in-scope SHA
verbs:
configure, build, modify, run, test, debug.
Plus a Deferred task verbs block that points out-of-scope
questions at the right next skill.
The skill assumes a host or BlueField where DOCA is already
installed at the standard location and the user has the privileges
their public install profile expects. It does not cover installing
DOCA — that path goes through
doca-setup/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- Pre-written DOCA SHA application source code, in any
language. The verified SHA source code is the shipped C samples
at
/opt/mellanox/doca/samples/doca_sha/, plus the File Integrity
reference application linked from the public DOCA SHA guide. The
agent's job is to route the user to those files and prescribe a
minimum-diff modification on them via the universal
modify-a-sample workflow in
doca-programming-guide/SKILL.md,
layered with the SHA-specific overrides inmodify.
- Pre-computed digest tables for arbitrary inputs. The skill
tells the agent to use a published test vector (e.g. the NIST
SHA test vectors for the empty string, "abc", and the
million-
a input) as the known-vector smoke; it does not ship a
vector bank of its own.
- Standalone build manifests (
meson.build, CMakeLists.txt,
Cargo.toml, …) parked inside the skill. The agent constructs
the build manifest in the user's project directory against the
user's installed DOCA, where pkg-config --modversion doca-sha
is the source of truth.
- A
samples/, bindings/, or reference/ subtree of any
kind. A mock or incomplete artifact in this skill's tree, even
one labeled "reference", is misleading: users will read it as
buildable.
Loading order
- Read this skill first to confirm the user's question is in
scope.
- For the SHA capability matrix, algorithm enums, one-shot vs
partial task split, capability-query rules, permission matrix,
error taxonomy, observability, and safety / path-selection
policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Both companion files cross-link to each other,
doca-version/SKILL.md for the canonical
version-handling rules, and
doca-public-knowledge-map/SKILL.md
whenever the right answer is "look it up in the public docs or the
installed package layout" rather than "SHA-specific guidance".
Related skills
doca-public-knowledge-map/SKILL.md —
the routing table for every public DOCA documentation source and
the on-disk layout of an installed DOCA package. The DOCA SHA
page lives at docs.nvidia.com/doca/sdk/DOCA-SHA/; the File
Integrity reference application is the canonical worked example.
doca-setup/SKILL.md — env preparation,
install verification, and the I have no install yet path with
the public NGC DOCA container. This skill assumes its
preconditions are satisfied.
doca-version/SKILL.md — canonical DOCA
version-handling rules. This skill's
## Version compatibility
cross-links the four-way match rule and adds only the SHA-specific
"discover algorithms + buffer sizes via cap query" overlay.
doca-structured-tools-contract/SKILL.md —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
the tasks companion honors this contract.
doca-programming-guide/SKILL.md —
general DOCA programming patterns shared by every library: the
canonical pkg-config + meson build pattern, the universal
modify-a-shipped-sample first-app workflow, the universal
lifecycle, the cross-library DOCA_ERROR_* taxonomy, and the
program-side debug order. This skill layers SHA specifics on
top.
doca-debug/SKILL.md — the cross-cutting
debug ladder (install / version / build / link / runtime /
program / driver). SHA-specific debug (algorithm-not-supported,
destination-buffer-too-small, partial-hash-out-of-order) overlays
on top of that ladder.
1---2license: Apache-2.03name: doca-sha4description: >5 Use this skill when the user needs SHA-1, SHA-256, or SHA-512 digest6 acceleration on BlueField-2 silicon via doca_sha (absent on BF-3) —7 selecting one-shot `doca_sha_task_hash` versus incremental8 `doca_sha_task_partial_hash` for chunked input, consulting9 `doca_sha_cap_*` for per-algorithm digest-size limits and input10 alignment, or decoding DOCA_ERROR_* statuses such as BAD_STATE on a11 resumed partial hash. Also load it for implied asks like "accelerate12 SHA-256 on the NIC", "streaming digest over chunks", "digest output13 size mismatch", or "is SHA-512 present on this card". Refuse and14 route to the proper owner for cryptographic-hash theory (collision15 resistance, SHA-3 selection), the AES-GCM / Compress / DMA16 libraries, or SDK install and BFB bring-up.17metadata:18 source: https://skillmd.com/skills/nvidia/doca-sha19 author: NVIDIA <doca-feedback@nvidia.com>20 kind: library21 doca_version: "3.5"22 tags:23 - doca24 - sha25 - hash26compatibility: >27 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu28 22.04/24.04 or RHEL/SLES) with a BlueField-2 DPU attached29 (BlueField-3 has no SHA engine). Reads the user's local install via `pkg-config doca-sha` and inspects30 /opt/mellanox/doca/{lib,include,samples,applications}.31 The validation steps require a live DOCA install.32---3334# DOCA SHA3536## Examples3738- **"Offload SHA-256 to the BlueField."** — this is in scope. Use the39 shipped SHA sample and `doca_sha_cap_*` before picking SHA-1 /40 SHA-256 / SHA-512.41- **"Partial hash returns BAD_STATE."** — stay on the incremental42 `doca_sha_task_partial_hash` lifecycle; do not switch to a CPU43 hash library mid-stream.4445## Instructions4647Follow Loading order below. Open the tasks companion for configure /48build / run. Open the capabilities companion for one-shot vs49partial hash and algorithm support. Do not open every companion file.5051**Where to start:** This skill assumes DOCA is already installed and52the user is doing **hands-on SHA-acceleration work** on a BlueField-253DPU (Arm side or its host) with DOCA. BlueField-3 has no SHA engine. Open the tasks companion if the user54wants to *do* something (configure / build / modify / run / test /55debug); open the capabilities companion when the question56is *what can DOCA SHA express* on this version. If the user has not57installed DOCA yet, route to58`doca-setup/SKILL.md` first. If the user is59asking *"should I even use the accelerator for this hash?"*, the60path-selection rule in61## Capabilities and modes62is the first stop.6364**How to use this skill.** Read this file, then search the companion file65for the `## <name>` heading the question needs and read that whole section.66Answer completely from it, quoting only its symbols and commands. Do not67browse docs; use the entry points in `doca-public-knowledge-map`. Give68environment checks as commands for the user's DOCA host. For out-of-scope69requests, name the skill that owns them and stop.7071## Example questions this skill answers well7273The CLASSES of DOCA SHA questions this skill is built to answer,74each with one worked example. The agent should treat the *class* as75the load-bearing piece — the worked example is a single instance.7677- **"Should I offload this hash to DOCA SHA, or just compute it on78 the CPU?"** — worked example: *"I am verifying file integrity on79 a 4 GiB image; is doca-sha worth the setup vs OpenSSL on the80 CPU?"*. Answered by the path-selection table in81 ## Capabilities and modes82 + the *"when NOT to use doca-sha"* bullets in83 ## Safety policy.84- **"Does my device support the SHA algorithm I want?"** — worked85 example: *"is SHA-256 in the accelerator on this BlueField, and86 what is the minimum destination buffer size for it?"*. Answered87 by the algorithm + buffer-sizing capability-query rule88 (`doca_sha_cap_task_hash_get_supported(devinfo, algorithm)`89 for the one-shot path; `_task_partial_hash_get_supported(devinfo, algorithm)`90 for the partial-hash path; `doca_sha_cap_get_min_dst_buf_size`,91 `doca_sha_cap_get_max_src_buf_size`) in92 ## Capabilities and modes93 + the discovery step in94 ## configure.95- **"How do I pick between the one-shot and the partial / incremental96 hash task?"** — worked example: *"my input is 1 GiB and the device97 cap says max source buffer is 64 MiB"*. Answered by the98 one-shot-vs-partial table in99 ## Capabilities and modes100 + the task-config workflow in101 ## modify.102- **"What permissions does the source / destination mmap need?"** —103 worked example: *"my `doca_sha_task_hash` returns104 `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix105 in ## Safety policy106 + the mmap-set-permissions checklist in107 ## test.108- **"Is this DOCA SHA API available on my installed DOCA version?"**109 — worked example: *"is `doca_sha_task_partial_hash` in the DOCA110 I have installed?"*. Answered by the version-compatibility111 overlay in112 ## Version compatibility,113 which cross-links the canonical detection chain in114 `doca-version/SKILL.md` and adds the115 SHA-specific *"discover, do not assume"* bullets.116- **"What does this `DOCA_ERROR_*` from a SHA call mean and which117 layer caused it?"** — worked example: *"`DOCA_ERROR_INVALID_VALUE`118 on `doca_sha_task_hash_alloc_init`"*. Answered by the SHA overlay119 on the cross-library taxonomy in120 ## Error taxonomy121 + the layered ladder in122 ## debug that escalates to123 `doca-debug/SKILL.md`.124125## Audience126127This skill serves **external developers building applications that128consume the DOCA SHA library** — i.e., users whose code calls129`doca_sha_*` (directly in C/C++, or through FFI/bindings from130another language) to offload SHA hashing onto the BlueField-2 SHA131engine (BlueField-3 has none). It is *not* for NVIDIA developers contributing132to DOCA SHA itself.133134**Language scope.** DOCA SHA ships as a C library with `pkg-config`135module name `doca-sha`. The shipped samples are written in C. C and136C++ consumers are the canonical case and the worked examples in137the tasks companion assume that path. Other-language consumers (Rust, Go,138Python, …) consume the same `*.so` through FFI or language-specific139bindings; the skill's contribution in that case is to keep the140lifecycle, capability-discovery, permission, error-taxonomy, and141one-shot-vs-partial guidance language-neutral, and to route the142agent to the public C ABI as the authoritative surface that any143wrapper will eventually call.144145## When to load this skill146147Load this skill when the user is doing hands-on DOCA SHA work, in148any language. Concretely:149150- Initializing a `doca_sha` context on a `doca_dev` and configuring151 at least one task type (`doca_sha_task_hash` and/or152 `doca_sha_task_partial_hash`) before `doca_ctx_start()`.153- Choosing between the **one-shot** task (`doca_sha_task_hash` —154 input fits in a single source buffer, output digest lands in a155 single destination buffer) and the **partial / incremental** task156 (`doca_sha_task_partial_hash` — input streamed in chunks, finalized157 separately) for the user's data shape.158- Setting permissions on `doca_mmap` correctly for the source buffer159 (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum) and the destination160 buffer (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`).161- Sizing the destination buffer against162 `doca_sha_cap_get_min_dst_buf_size(devinfo, algorithm)` and163 the source buffer against164 `doca_sha_cap_get_max_src_buf_size(devinfo)`.165- Checking which SHA algorithm enums166 (`DOCA_SHA_ALGORITHM_SHA1`, `DOCA_SHA_ALGORITHM_SHA256`,167 `DOCA_SHA_ALGORITHM_SHA512`) the active device's accelerator168 advertises, via169 `doca_sha_cap_task_hash_get_supported(devinfo, algorithm)` and170 `doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm)` —171 both fold task-support and algorithm-support into one call.172- Validating a digest against a published test vector before pushing173 bulk input through the accelerator.174- Debugging a `DOCA_ERROR_*` returned from a SHA call (lifecycle vs.175 buffer-sizing vs. permission vs. unsupported-algorithm) and the176 task-completion event on the progress engine.177- Designing or extending non-C bindings (Rust, Go, Python, …) that178 wrap the SHA C ABI — for the lifecycle, permission, capability,179 and one-shot-vs-partial rules the wrapper must honor.180181Do **not** load this skill for general DOCA orientation, install of182DOCA itself, non-SHA hashing libraries on CPU (use OpenSSL or183similar), or other DOCA libraries. For those, use184`doca-public-knowledge-map/SKILL.md`.185186## What this skill provides187188This is a **thin loader**. The body keeps only the orientation189needed to pick the right next file. The substantive SHA-specific190material lives in two companion files:191192- the capabilities companion — what DOCA SHA can express on this version:193 the two task types (one-shot hash and partial / incremental194 hash), the three algorithm enums, the capability-query surface195 (`doca_sha_cap_*` for algorithm support and buffer sizing), the196 SHA error taxonomy (mapped onto the cross-library `DOCA_ERROR_*`197 set), the observability surface (per-task completion events on198 the progress engine), the safety policy that gates source /199 destination mmap permission decisions, and the path-selection200 rule (when to use doca-sha versus a CPU hash or a different201 DOCA crypto library).202- the tasks companion — step-by-step workflows for the six in-scope SHA203 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.204 Plus a `Deferred task verbs` block that points out-of-scope205 questions at the right next skill.206207The skill assumes a host or BlueField where DOCA is already208installed at the standard location and the user has the privileges209their public install profile expects. It does not cover installing210DOCA — that path goes through211`doca-setup/SKILL.md`.212213## What this skill deliberately does not ship214215This skill is **agent guidance**, not a samples or templates216bundle. To keep the boundary clean, it deliberately does not217contain — and pull requests should not add:218219- **Pre-written DOCA SHA application source code, in any220 language.** The verified SHA source code is the shipped C samples221 at `/opt/mellanox/doca/samples/doca_sha/`, plus the File Integrity222 reference application linked from the public DOCA SHA guide. The223 agent's job is to route the user to those files and prescribe a224 minimum-diff modification on them via the universal225 modify-a-sample workflow in226 `doca-programming-guide/SKILL.md`,227 layered with the SHA-specific overrides in228 ## modify.229- **Pre-computed digest tables for arbitrary inputs.** The skill230 tells the agent to use a *published* test vector (e.g. the NIST231 SHA test vectors for the empty string, "abc", and the232 million-`a` input) as the known-vector smoke; it does not ship a233 vector bank of its own.234- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,235 `Cargo.toml`, …) parked inside the skill. The agent constructs236 the build manifest *in the user's project directory* against the237 user's installed DOCA, where `pkg-config --modversion doca-sha`238 is the source of truth.239- **A `samples/`, `bindings/`, or `reference/` subtree** of any240 kind. A mock or incomplete artifact in this skill's tree, even241 one labeled "reference", is misleading: users will read it as242 buildable.243244## Loading order2452461. Read this skill first to confirm the user's question is in247 scope.2482. **For the SHA capability matrix, algorithm enums, one-shot vs249 partial task split, capability-query rules, permission matrix,250 error taxonomy, observability, and safety / path-selection251 policy, see the capabilities companion.**2523. **For step-by-step workflows — configure, build, modify, run,253 test, debug — see the tasks companion.**254255Both companion files cross-link to each other,256`doca-version/SKILL.md` for the canonical257version-handling rules, and258`doca-public-knowledge-map/SKILL.md`259whenever the right answer is "look it up in the public docs or the260installed package layout" rather than "SHA-specific guidance".261262## Related skills263264- `doca-public-knowledge-map/SKILL.md` —265 the routing table for every public DOCA documentation source and266 the on-disk layout of an installed DOCA package. The DOCA SHA267 page lives at `docs.nvidia.com/doca/sdk/DOCA-SHA/`; the File268 Integrity reference application is the canonical worked example.269- `doca-setup/SKILL.md` — env preparation,270 install verification, and the *I have no install yet* path with271 the public NGC DOCA container. This skill assumes its272 preconditions are satisfied.273- `doca-version/SKILL.md` — canonical DOCA274 version-handling rules. This skill's275 `## Version compatibility`276 cross-links the four-way match rule and adds only the SHA-specific277 *"discover algorithms + buffer sizes via cap query"* overlay.278- `doca-structured-tools-contract/SKILL.md` —279 the bundle's structured-tools precedence rule (detect / prefer280 / fall back / report). The Command appendix in281 the tasks companion honors this contract.282- `doca-programming-guide/SKILL.md` —283 general DOCA programming patterns shared by every library: the284 canonical `pkg-config` + meson build pattern, the universal285 modify-a-shipped-sample first-app workflow, the universal286 lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the287 program-side debug order. This skill layers SHA specifics on288 top.289- `doca-debug/SKILL.md` — the cross-cutting290 debug ladder (install / version / build / link / runtime /291 program / driver). SHA-specific debug (algorithm-not-supported,292 destination-buffer-too-small, partial-hash-out-of-order) overlays293 on top of that ladder.