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 / ConnectX / host with DOCA. 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 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 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.

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

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.

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

  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

1. Read this skill first to confirm the user's question is in scope.
2. 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.
3. 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 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 the tasks companion 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.