Loading
>
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add NVIDIA/skills --skill doca-aes-gcm -a cursor -y
>
doca_aes_gcm_task_encrypt / _task_decrypt, querying
doca_aes_gcm_cap_* for per-key-type (only DOCA_AES_GCM_KEY_128 /
_256 — AES-192 not supported) and per-task support, sizing plaintext
against the max-buf cap, setting source / destination mmap
permissions, validating with a NIST GCMVS or RFC 5288 vector, or
debugging DOCA_ERROR_* including the security-critical
tag-verification-failed outcome on decrypt. Trigger even when the user
does not explicitly mention "DOCA AES-GCM" or "AEAD" — typical
implicit phrasings: "decrypt completion IO_FAILED", "auth tag isn't
verifying", "NOT_PERMITTED on my encrypt buffer", "is AES-192-GCM on
this BlueField" (no), or "encrypted record came back tampered". Refuse
and route elsewhere for non-GCM AES modes (CBC / CTR / XTS — CPU
OpenSSL), key management (KMS / HSM / rotation), SHA (doca-sha), or
general AEAD background.
metadata:
author: NVIDIA
kind: library
tags:
- doca
- aes-gcm
- aead
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 local install via
and inspects
/opt/mellanox/doca/{lib,include,samples,applications}.
Only / are supported (not AES-192).
The validation steps require a live DOCA install.pkg-config doca-aes-gcmDOCA_AES_GCM_KEY_128_256Follow Loading order below. Open the tasks companion for configure / test / debug. Open the capabilities companion for key types and the AEAD safety note. Do not open every companion file.
Where to start: This skill assumes DOCA is already installed and
the user is doing hands-on AES-GCM-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 AES-GCM 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 encryption?",
the path-selection rule in
is the first stop. If the user is treating AES-GCM as a confidentiality-only primitive (raw AES-CTR / AES-CBC style), stop and read the AEAD note in ## Safety policy first — AES-GCM is authenticated encryption, and confusing the two is the most expensive failure mode this skill exists to prevent.
The CLASSES of DOCA AES-GCM 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.
EVP_aes_256_gcm on the CPU?". Answered by
the path-selection table in
DOCA_AES_GCM_KEY_128 / DOCA_AES_GCM_KEY_256;
AES-192 is not in the enum and is not supported. For the two
real key types, gate on
doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)
and the matching _decrypt_is_key_type_supported. AES-192 is
not available — route to a CPU library.) Answered by the
per-key-type capability queries and the per-task
doca_aes_gcm_cap_task_*_is_supported queries in
doca_aes_gcm_task_decrypt
completion reports an error — is the plaintext output safe to
use?". Answered by the auth-tag verification rule in
doca_aes_gcm_task_encrypt returns
DOCA_ERROR_NOT_PERMITTED". Answered by the permission matrix
in ## Safety policy
doca-version/SKILL.md and adds the
AES-GCM-specific "discover key sizes via cap query" bullets.DOCA_ERROR_* from an AES-GCM call mean and
which layer caused it?" — worked example: "DOCA_ERROR_NOT_PERMITTED
on my encrypt buffer". Answered by the AES-GCM overlay on the
cross-library taxonomy in
doca-debug/SKILL.md.
IO_FAILEDon a decrypt completion is not a debugging question. It means auth tag verification failed, and that is a security event, not a code or configuration bug — there is nothing to classify by layer and nothing to escalate todoca-debug/SKILL.md. The plaintext that task produced is poisoned and must not be consumed; the decrypt must not be retried; the input ciphertext is tampered or corrupted and must be treated as untrusted; the outcome belongs to the caller's application-layer policy for tampered input. Lead with that. Only if the user is testing against known-good vectors is a configuration cause (wrong key, IV, AAD, or tag length) worth raising, and even then it comes second. Full rule inError taxonomy
and
## Safety policy.
This skill serves external developers building applications that
consume the DOCA AES-GCM library — i.e., users whose code calls
doca_aes_gcm_* (directly in C/C++, or through FFI/bindings from
another language) to offload AES-GCM authenticated encryption /
decryption onto a BlueField DPU or ConnectX accelerator. It is not
for NVIDIA developers contributing to DOCA AES-GCM itself.
Language scope. DOCA AES-GCM ships as a C library with
pkg-config module name doca-aes-gcm. 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, AEAD-semantics, and encrypt-vs-decrypt guidance
language-neutral, and to route the agent to the public C ABI as the
authoritative surface that any wrapper will eventually call.
Key handling is out of scope. This skill teaches the agent how to use the DOCA AES-GCM library; it does not teach the user how to generate, store, rotate, or distribute AES-GCM keys. Key-management is the user's responsibility (a KMS, an HSM, a sealed file, an env var the user trusts). The skill's only key-handling rule is the operational one in
do not log keys, do not commit them to source, and treat any key buffer the program holds as sensitive memory.
Load this skill when the user is doing hands-on DOCA AES-GCM work, in any language. Concretely:
doca_aes_gcm context on a doca_dev and
configuring at least one task type (doca_aes_gcm_task_encrypt
and/or doca_aes_gcm_task_decrypt) before doca_ctx_start().doca_aes_gcm_task_encrypt —
takes key + IV + AAD + plaintext, produces ciphertext + auth
tag) and decrypt (doca_aes_gcm_task_decrypt — takes key +
IV + AAD + ciphertext + expected auth tag, produces plaintext
and verifies the tag) for the user's data shape.doca_mmap correctly for the source buffer
(DOCA_ACCESS_FLAG_LOCAL_READ_ONLY at minimum — the plaintext on
encrypt or the ciphertext on decrypt) and the destination buffer
(DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).DOCA_AES_GCM_KEY_128 /
DOCA_AES_GCM_KEY_256 — AES-192 is not in the library) the
active device's accelerator advertises via
doca_aes_gcm_cap_task_encrypt_is_key_type_supported /
doca_aes_gcm_cap_task_decrypt_is_key_type_supported, and which task types via
doca_aes_gcm_cap_task_encrypt_is_supported /
_task_decrypt_is_supported.doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo).DOCA_ERROR_* returned from an AES-GCM call
(lifecycle vs. unsupported key size vs. permission vs. tag
verification failure on decrypt) and the task-completion event on
the progress engine.Do not load this skill for general DOCA orientation, install of
DOCA itself, AES modes that are not GCM (CBC / CTR / XTS — those are
not in this library and CPU + OpenSSL is the right answer), SHA
hashing on the same accelerator family (use
doca-sha/SKILL.md), or other DOCA libraries. For
those, use
doca-public-knowledge-map/SKILL.md.
This is a thin loader. The body keeps only the orientation needed to pick the right next file. The substantive AES-GCM-specific material lives in two companion files:
doca_aes_gcm_cap_* for task presence, key-type
support, and buffer sizing), the
AES-GCM error taxonomy (mapped onto the cross-library
DOCA_ERROR_* set, with explicit treatment of the
tag-verification-failure outcome as security-critical), the
observability surface (per-task completion events on the progress
engine), the safety policy that gates source / destination mmap
permission decisions and key-handling cautions, and the
path-selection rule (when to use doca-aes-gcm versus CPU OpenSSL
or a different DOCA crypto library).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.
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:
/opt/mellanox/doca/samples/doca_aes_gcm/. 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 AES-GCM-specific overrides in
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-aes-gcm is the source of truth.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.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 "AES-GCM-specific guidance".
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 AES-GCM
page lives at docs.nvidia.com/doca/sdk/DOCA-AES-GCM/; it is a
member of the DOCA Crypto Acceleration family alongside
doca-sha/SKILL.md.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
AES-GCM-specific "discover key sizes + task presence 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 AES-GCM specifics on
top.doca-sha/SKILL.md — the sibling library in the
DOCA Crypto Acceleration family for hardware-accelerated SHA
hashing. Load alongside this skill when the user's flow is
authenticated-encryption with a separate keyed hash (rare —
AES-GCM already provides authentication via its tag) or when the
user is comparing offload paths between the two.doca-debug/SKILL.md — the cross-cutting
debug ladder (install / version / build / link / runtime /
program / driver). AES-GCM-specific debug (key-size-not-supported,
oversized input, tag-verification failure on decrypt) overlays on
top of that ladder.