Doca Sha

DOCA SHA

Where to start: This skill assumes DOCA is already installed and

the user is doing hands-on SHA-acceleration work on a BlueField

/ ConnectX / host with DOCA. Open TASKS.md if the user

wants to *do* something (configure / build / modify / run / test /

debug); open CAPABILITIES.md when the question

is *what can DOCA SHA express* on this version. If the user has not

installed DOCA yet, route to

doca-setup first. If the user is

asking *"should I even use the accelerator for this hash?"*, the

path-selection rule in

CAPABILITIES.md ## Capabilities and modes

is the first 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.md ## Capabilities and modes

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

CAPABILITIES.md ## 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.md ## Capabilities and modes

+ the discovery step in

TASKS.md ## 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.md ## Capabilities and modes

+ the task-config workflow in

TASKS.md ## 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 CAPABILITIES.md ## Safety policy

+ the mmap-set-permissions checklist in

TASKS.md ## 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

CAPABILITIES.md ## Version compatibility,

which cross-links the canonical detection chain in

doca-version 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

CAPABILITIES.md ## Error taxonomy

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

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 a BlueField DPU or

ConnectX accelerator. 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

TASKS.md 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.

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:

• CAPABILITIES.md — 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).

• TASKS.md — 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.

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,

layered with the SHA-specific overrides in

TASKS.md ## modify.

• 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.md 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 CAPABILITIES.md.**

• **For step-by-step workflows — configure, build, modify, run,

test, debug — see TASKS.md.**

Both companion files cross-link to each other,

doca-version for the canonical

version-handling rules, and

doca-public-knowledge-map

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 —

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 — 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 — 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 —

the bundle's structured-tools precedence rule (detect / prefer

/ fall back / report). The Command appendix in

TASKS.md honors this contract.

• doca-programming-guide —

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 — 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.