/doca-sha

license: Apache-2.0
name: doca-sha
description: >
  Use this skill when the user is doing hands-on DOCA SHA programming —
  offloading SHA-1, SHA-256, or SHA-512 hashing onto a BlueField DPU or
  ConnectX accelerator, picking between one-shot `doca_sha_task_hash` and
  incremental `doca_sha_task_partial_hash`, querying `doca_sha_cap_*`
  for algorithm support and min destination / max source buffer sizes, setting
  source / destination `doca_mmap` permissions, or decoding DOCA_ERROR_*
  returns from the SHA API. Trigger even when the user does not explicitly
  mention "DOCA SHA" or "doca_sha_task" — typical implicit phrasings
  include "hash a multi-GiB file on the DPU", "offload SHA-256 to the
  BlueField", "streaming hash over chunks", "partial hash returns
  BAD_STATE", "destination buffer too small for digest", or "is SHA-512
  available on this card". Refuse and route elsewhere for general
  cryptographic-hash theory (collision resistance, SHA-3 selection), other
  DOCA crypto libraries (AES-GCM, Compress, DMA), or DOCA install / BFB
  bring-up — those belong to other skills.
metadata:
  kind: library
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC attached.
  Reads the user's local install via `pkg-config doca-sha` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.

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`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](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`](../../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.md ## Capabilities and modes`](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`](CAPABILITIES.md#capabilities-and-modes)

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

[`CAPABILITIES.md ## Safety policy`](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`](CAPABILITIES.md#capabilities-and-modes)

• the discovery step in

[`TASKS.md ## configure`](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`](CAPABILITIES.md#capabilities-and-modes)

• the task-config workflow in

[`TASKS.md ## modify`](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`](CAPABILITIES.md#safety-policy)

• the mmap-set-permissions checklist in

[`TASKS.md ## test`](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`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../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 [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../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 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, a