DOCA AES-GCM
Examples
- "Auth tag isn't verifying on decrypt." — this is in scope.
Treat tag-verification-failed as a security outcome, not a
retryable size error.
- "Is AES-192-GCM on this BlueField?" — no. Only key-128 and
key-256 exist; do not invent AES-192 or CBC/CTR offload.
Instructions
Follow 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
Capabilities and modes
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.
Example questions this skill answers well
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.
- "Should I offload this AES-GCM encryption to DOCA AES-GCM, or
just do it on the CPU with OpenSSL?" — worked example: "I am
encrypting 4 KiB TLS records at line rate; is doca-aes-gcm worth
the setup vs OpenSSL
EVP_aes_256_gcm on the CPU?". Answered by
the path-selection table inCapabilities and modes
- the "when NOT to use doca-aes-gcm" bullets in
Safety policy.
- "Does my device support the AES-GCM key size I want?" — worked
example: "is AES-256-GCM in the accelerator on this BlueField?
And while we're here, is AES-192-GCM available?" (Answer: the
library exposes only
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 inCapabilities and modes
configure.
- "How do I correctly decrypt an AES-GCM message and verify the
auth tag?" — worked example: "my
doca_aes_gcm_task_decrypt
completion reports an error — is the plaintext output safe to
use?". Answered by the auth-tag verification rule inSafety policy
(do not use the plaintext if the auth tag did not verify) +
the decrypt completion-handling workflow intest and
debug.
- "What permissions does the source / destination mmap need?" —
worked example: "my
doca_aes_gcm_task_encrypt returns
DOCA_ERROR_NOT_PERMITTED". Answered by the permission matrix
in ## Safety policy
- the mmap-set-permissions checklist in
test.
- "Is this DOCA AES-GCM API available on my installed DOCA
version?" — worked example: "is AES-192-GCM in the DOCA I have
installed, on this device?". Answered by the version-compatibility
overlay in
Version compatibility,
which cross-links the canonical detection chain in
doca-version/SKILL.md and adds the
AES-GCM-specific "discover key sizes via cap query" bullets.
- "What does this
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 inError taxonomy
debug that escalates to
doca-debug/SKILL.md.
IO_FAILED on 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 to
doca-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 in
Error taxonomy
and ## Safety policy.
Audience
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
Safety policy:
do not log keys, do not commit them to source, and treat any key
buffer the program holds as sensitive memory.
When to load this skill
Load this skill when the user is doing hands-on DOCA AES-GCM work,
in any language. Concretely:
- Initializing a
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().
- Choosing between encrypt (
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.
- Setting permissions on
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).
- Checking which AES-GCM key types (
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.
- Sizing the per-submission plaintext against
doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo).
- Validating an encrypt + decrypt round-trip against a published
AES-GCM test vector (NIST GCMVS, or RFC 5288 examples) before
pushing any user data through the accelerator.
- Handling the auth-tag verification result on decrypt completions
as a security-critical signal — a tag-mismatch completion means
the ciphertext was tampered with or corrupted, and the plaintext
output of that task is poisoned and must not be consumed.
- Debugging a
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.
- Designing or extending non-C bindings (Rust, Go, Python, …) that
wrap the AES-GCM C ABI — for the lifecycle, permission,
capability, AEAD-semantics, and encrypt-vs-decrypt rules the
wrapper must honor.
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.
What this skill provides
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:
- the capabilities companion — what DOCA AES-GCM can express on this version:
the two task types (encrypt and decrypt), the AEAD output shape
(ciphertext + auth tag on encrypt; verified plaintext on decrypt),
the AES-GCM key-type surface (only 128-bit and 256-bit — AES-192
is not in the enum, both cap-queried), the capability-query
surface (
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).
- the tasks companion — step-by-step workflows for the six in-scope AES-GCM
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 AES-GCM application source code, in any
language. The verified AES-GCM source code is the shipped C
samples at
/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 inmodify.
- Pre-computed AES-GCM test vectors. The skill tells the agent
to use a published test vector (e.g. NIST GCMVS, RFC 5288
AES-GCM examples) as the known-vector smoke; it does not ship a
vector bank of its own. The agent must cite the vector source so
the user can audit it.
- Pre-baked AES-GCM keys, IVs, or AAD strings. A key in this
repo is a key in every customer's repo — by construction, it must
not be there. The skill teaches the shape of the inputs; the
user supplies the actual bytes from their own key-management
system.
- 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-aes-gcm 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 AES-GCM capability matrix, task types, key-size
surface, capability-query rules, permission matrix, AEAD
semantics, 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 "AES-GCM-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 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.
1---2license: Apache-2.03name: doca-aes-gcm4description: >5 Use this skill when the user is doing hands-on DOCA AES-GCM work on a6 BlueField DPU or ConnectX NIC — configuring7 `doca_aes_gcm_task_encrypt` / `_task_decrypt`, querying8 `doca_aes_gcm_cap_*` for per-key-type (only `DOCA_AES_GCM_KEY_128` /9 `_256` — AES-192 not supported) and per-task support, sizing plaintext10 against the max-buf cap, setting source / destination mmap11 permissions, validating with a NIST GCMVS or RFC 5288 vector, or12 debugging DOCA_ERROR_* including the security-critical13 tag-verification-failed outcome on decrypt. Trigger even when the user14 does not explicitly mention "DOCA AES-GCM" or "AEAD" — typical15 implicit phrasings: "decrypt completion IO_FAILED", "auth tag isn't16 verifying", "NOT_PERMITTED on my encrypt buffer", "is AES-192-GCM on17 this BlueField" (no), or "encrypted record came back tampered". Refuse18 and route elsewhere for non-GCM AES modes (CBC / CTR / XTS — CPU19 OpenSSL), key management (KMS / HSM / rotation), SHA (doca-sha), or20 general AEAD background.21metadata:22 source: https://skillmd.com/skills/nvidia/doca-aes-gcm23 author: NVIDIA <doca-feedback@nvidia.com>24 kind: library25 doca_version: "3.5"26 tags:27 - doca28 - aes-gcm29 - aead30compatibility: >31 Requires DOCA SDK installed at /opt/mellanox/doca on Linux32 (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or33 ConnectX NIC attached. Reads the local install via34 `pkg-config doca-aes-gcm` and inspects35 /opt/mellanox/doca/{lib,include,samples,applications}.36 Only `DOCA_AES_GCM_KEY_128` / `_256` are supported (not AES-192).37 The validation steps require a live DOCA install.38---3940# DOCA AES-GCM4142## Examples4344- **"Auth tag isn't verifying on decrypt."** — this is in scope.45 Treat tag-verification-failed as a security outcome, not a46 retryable size error.47- **"Is AES-192-GCM on this BlueField?"** — no. Only key-128 and48 key-256 exist; do not invent AES-192 or CBC/CTR offload.4950## Instructions5152Follow Loading order below. Open the tasks companion for configure /53test / debug. Open the capabilities companion for key types and54the AEAD safety note. Do not open every companion file.5556**Where to start:** This skill assumes DOCA is already installed and57the user is doing **hands-on AES-GCM-acceleration work** on a58BlueField / ConnectX / host with DOCA. Open the tasks companion if59the user wants to *do* something (configure / build / modify / run /60test / debug); open the capabilities companion when the61question is *what can DOCA AES-GCM express* on this version. If the62user has not installed DOCA yet, route to63`doca-setup/SKILL.md` first. If the user is64asking *"should I even use the accelerator for this encryption?"*,65the path-selection rule in66## Capabilities and modes67is the first stop. If the user is treating AES-GCM as a confidentiality-only68primitive (raw AES-CTR / AES-CBC style), stop and read the AEAD note69in ## Safety policy70first — AES-GCM is authenticated encryption, and confusing the two is71the most expensive failure mode this skill exists to prevent.7273## Example questions this skill answers well7475The CLASSES of DOCA AES-GCM questions this skill is built to answer,76each with one worked example. The agent should treat the *class* as77the load-bearing piece — the worked example is a single instance.7879- **"Should I offload this AES-GCM encryption to DOCA AES-GCM, or80 just do it on the CPU with OpenSSL?"** — worked example: *"I am81 encrypting 4 KiB TLS records at line rate; is doca-aes-gcm worth82 the setup vs OpenSSL `EVP_aes_256_gcm` on the CPU?"*. Answered by83 the path-selection table in84 ## Capabilities and modes85 + the *"when NOT to use doca-aes-gcm"* bullets in86 ## Safety policy.87- **"Does my device support the AES-GCM key size I want?"** — worked88 example: *"is AES-256-GCM in the accelerator on this BlueField?89 And while we're here, is AES-192-GCM available?"* (Answer: the90 library exposes only `DOCA_AES_GCM_KEY_128` / `DOCA_AES_GCM_KEY_256`;91 AES-192 is not in the enum and is not supported. For the two92 real key types, gate on93 `doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)`94 and the matching `_decrypt_is_key_type_supported`. AES-192 is95 not available — route to a CPU library.) Answered by the96 per-key-type capability queries and the per-task97 `doca_aes_gcm_cap_task_*_is_supported` queries in98 ## Capabilities and modes99 + the discovery step in100 ## configure.101- **"How do I correctly decrypt an AES-GCM message and verify the102 auth tag?"** — worked example: *"my `doca_aes_gcm_task_decrypt`103 completion reports an error — is the plaintext output safe to104 use?"*. Answered by the auth-tag verification rule in105 ## Safety policy106 (*do not use the plaintext if the auth tag did not verify*) +107 the decrypt completion-handling workflow in108 ## test and109 ## debug.110- **"What permissions does the source / destination mmap need?"** —111 worked example: *"my `doca_aes_gcm_task_encrypt` returns112 `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix113 in ## Safety policy114 + the mmap-set-permissions checklist in115 ## test.116- **"Is this DOCA AES-GCM API available on my installed DOCA117 version?"** — worked example: *"is AES-192-GCM in the DOCA I have118 installed, on this device?"*. Answered by the version-compatibility119 overlay in120 ## Version compatibility,121 which cross-links the canonical detection chain in122 `doca-version/SKILL.md` and adds the123 AES-GCM-specific *"discover key sizes via cap query"* bullets.124- **"What does this `DOCA_ERROR_*` from an AES-GCM call mean and125 which layer caused it?"** — worked example: *"`DOCA_ERROR_NOT_PERMITTED`126 on my encrypt buffer"*. Answered by the AES-GCM overlay on the127 cross-library taxonomy in128 ## Error taxonomy129 + the layered ladder in130 ## debug that escalates to131 `doca-debug/SKILL.md`.132133> **`IO_FAILED` on a decrypt completion is not a debugging134> question.** It means auth tag verification failed, and that is a135> security event, not a code or configuration bug — there is nothing136> to classify by layer and nothing to escalate to137> `doca-debug/SKILL.md`. The plaintext that task138> produced is poisoned and must not be consumed; the decrypt must not139> be retried; the input ciphertext is tampered or corrupted and must be140> treated as untrusted; the outcome belongs to the caller's141> application-layer policy for tampered input. Lead with that. Only if142> the user is testing against known-good vectors is a configuration143> cause (wrong key, IV, AAD, or tag length) worth raising, and even144> then it comes second. Full rule in145> ## Error taxonomy146> and `## Safety policy`.147148## Audience149150This skill serves **external developers building applications that151consume the DOCA AES-GCM library** — i.e., users whose code calls152`doca_aes_gcm_*` (directly in C/C++, or through FFI/bindings from153another language) to offload AES-GCM authenticated encryption /154decryption onto a BlueField DPU or ConnectX accelerator. It is *not*155for NVIDIA developers contributing to DOCA AES-GCM itself.156157**Language scope.** DOCA AES-GCM ships as a C library with158`pkg-config` module name `doca-aes-gcm`. The shipped samples are159written in C. C and C++ consumers are the canonical case and the160worked examples in the tasks companion assume that path. Other-language161consumers (Rust, Go, Python, …) consume the same `*.so` through FFI162or language-specific bindings; the skill's contribution in that case163is to keep the lifecycle, capability-discovery, permission,164error-taxonomy, AEAD-semantics, and encrypt-vs-decrypt guidance165language-neutral, and to route the agent to the public C ABI as the166authoritative surface that any wrapper will eventually call.167168**Key handling is out of scope.** This skill teaches the agent how to169*use* the DOCA AES-GCM library; it does not teach the user how to170generate, store, rotate, or distribute AES-GCM keys. Key-management171is the user's responsibility (a KMS, an HSM, a sealed file, an env172var the user trusts). The skill's only key-handling rule is the173operational one in174## Safety policy:175do not log keys, do not commit them to source, and treat any key176buffer the program holds as sensitive memory.177178## When to load this skill179180Load this skill when the user is doing hands-on DOCA AES-GCM work,181in any language. Concretely:182183- Initializing a `doca_aes_gcm` context on a `doca_dev` and184 configuring at least one task type (`doca_aes_gcm_task_encrypt`185 and/or `doca_aes_gcm_task_decrypt`) before `doca_ctx_start()`.186- Choosing between **encrypt** (`doca_aes_gcm_task_encrypt` —187 takes key + IV + AAD + plaintext, produces ciphertext + auth188 tag) and **decrypt** (`doca_aes_gcm_task_decrypt` — takes key +189 IV + AAD + ciphertext + expected auth tag, produces plaintext190 *and verifies the tag*) for the user's data shape.191- Setting permissions on `doca_mmap` correctly for the source buffer192 (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum — the plaintext on193 encrypt or the ciphertext on decrypt) and the destination buffer194 (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`).195- Checking which AES-GCM key types (`DOCA_AES_GCM_KEY_128` /196 `DOCA_AES_GCM_KEY_256` — AES-192 is not in the library) the197 active device's accelerator advertises via198 `doca_aes_gcm_cap_task_encrypt_is_key_type_supported` /199 `doca_aes_gcm_cap_task_decrypt_is_key_type_supported`, and which task types via200 `doca_aes_gcm_cap_task_encrypt_is_supported` /201 `_task_decrypt_is_supported`.202- Sizing the per-submission plaintext against203 `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`.204- Validating an encrypt + decrypt round-trip against a published205 AES-GCM test vector (NIST GCMVS, or RFC 5288 examples) before206 pushing any user data through the accelerator.207- Handling the auth-tag verification result on decrypt completions208 *as a security-critical signal* — a tag-mismatch completion means209 the ciphertext was tampered with or corrupted, and the plaintext210 output of that task is poisoned and must not be consumed.211- Debugging a `DOCA_ERROR_*` returned from an AES-GCM call212 (lifecycle vs. unsupported key size vs. permission vs. tag213 verification failure on decrypt) and the task-completion event on214 the progress engine.215- Designing or extending non-C bindings (Rust, Go, Python, …) that216 wrap the AES-GCM C ABI — for the lifecycle, permission,217 capability, AEAD-semantics, and encrypt-vs-decrypt rules the218 wrapper must honor.219220Do **not** load this skill for general DOCA orientation, install of221DOCA itself, AES modes that are not GCM (CBC / CTR / XTS — those are222not in this library and CPU + OpenSSL is the right answer), SHA223hashing on the same accelerator family (use224`doca-sha/SKILL.md`), or other DOCA libraries. For225those, use226`doca-public-knowledge-map/SKILL.md`.227228## What this skill provides229230This is a **thin loader**. The body keeps only the orientation231needed to pick the right next file. The substantive AES-GCM-specific232material lives in two companion files:233234- the capabilities companion — what DOCA AES-GCM can express on this version:235 the two task types (encrypt and decrypt), the AEAD output shape236 (ciphertext + auth tag on encrypt; verified plaintext on decrypt),237 the AES-GCM key-type surface (only 128-bit and 256-bit — AES-192238 is not in the enum, both cap-queried), the capability-query239 surface (`doca_aes_gcm_cap_*` for task presence, key-type240 support, and buffer sizing), the241 AES-GCM error taxonomy (mapped onto the cross-library242 `DOCA_ERROR_*` set, with explicit treatment of the243 tag-verification-failure outcome as security-critical), the244 observability surface (per-task completion events on the progress245 engine), the safety policy that gates source / destination mmap246 permission decisions and key-handling cautions, and the247 path-selection rule (when to use doca-aes-gcm versus CPU OpenSSL248 or a different DOCA crypto library).249- the tasks companion — step-by-step workflows for the six in-scope AES-GCM250 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.251 Plus a `Deferred task verbs` block that points out-of-scope252 questions at the right next skill.253254The skill assumes a host or BlueField where DOCA is already255installed at the standard location and the user has the privileges256their public install profile expects. It does not cover installing257DOCA — that path goes through258`doca-setup/SKILL.md`.259260## What this skill deliberately does not ship261262This skill is **agent guidance**, not a samples or templates263bundle. To keep the boundary clean, it deliberately does not264contain — and pull requests should not add:265266- **Pre-written DOCA AES-GCM application source code, in any267 language.** The verified AES-GCM source code is the shipped C268 samples at `/opt/mellanox/doca/samples/doca_aes_gcm/`. The agent's269 job is to route the user to those files and prescribe a270 minimum-diff modification on them via the universal271 modify-a-sample workflow in272 `doca-programming-guide/SKILL.md`,273 layered with the AES-GCM-specific overrides in274 ## modify.275- **Pre-computed AES-GCM test vectors.** The skill tells the agent276 to use a *published* test vector (e.g. NIST GCMVS, RFC 5288277 AES-GCM examples) as the known-vector smoke; it does not ship a278 vector bank of its own. The agent must cite the vector source so279 the user can audit it.280- **Pre-baked AES-GCM keys, IVs, or AAD strings.** A key in this281 repo is a key in every customer's repo — by construction, it must282 not be there. The skill teaches the *shape* of the inputs; the283 user supplies the actual bytes from their own key-management284 system.285- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,286 `Cargo.toml`, …) parked inside the skill. The agent constructs287 the build manifest *in the user's project directory* against the288 user's installed DOCA, where `pkg-config --modversion289 doca-aes-gcm` is the source of truth.290- **A `samples/`, `bindings/`, or `reference/` subtree** of any291 kind. A mock or incomplete artifact in this skill's tree, even292 one labeled "reference", is misleading: users will read it as293 buildable.294295## Loading order2962971. Read this skill first to confirm the user's question is in298 scope.2992. **For the AES-GCM capability matrix, task types, key-size300 surface, capability-query rules, permission matrix, AEAD301 semantics, error taxonomy, observability, and safety /302 path-selection policy, see the capabilities companion.**3033. **For step-by-step workflows — configure, build, modify, run,304 test, debug — see the tasks companion.**305306Both companion files cross-link to each other,307`doca-version/SKILL.md` for the canonical308version-handling rules, and309`doca-public-knowledge-map/SKILL.md`310whenever the right answer is "look it up in the public docs or the311installed package layout" rather than "AES-GCM-specific guidance".312313## Related skills314315- `doca-public-knowledge-map/SKILL.md` —316 the routing table for every public DOCA documentation source and317 the on-disk layout of an installed DOCA package. The DOCA AES-GCM318 page lives at `docs.nvidia.com/doca/sdk/DOCA-AES-GCM/`; it is a319 member of the DOCA Crypto Acceleration family alongside320 `doca-sha/SKILL.md`.321- `doca-setup/SKILL.md` — env preparation,322 install verification, and the *I have no install yet* path with323 the public NGC DOCA container. This skill assumes its324 preconditions are satisfied.325- `doca-version/SKILL.md` — canonical DOCA326 version-handling rules. This skill's327 `## Version compatibility`328 cross-links the four-way match rule and adds only the329 AES-GCM-specific *"discover key sizes + task presence via cap330 query"* overlay.331- `doca-structured-tools-contract/SKILL.md` —332 the bundle's structured-tools precedence rule (detect / prefer /333 fall back / report). The Command appendix in334 the tasks companion honors this contract.335- `doca-programming-guide/SKILL.md` —336 general DOCA programming patterns shared by every library: the337 canonical `pkg-config` + meson build pattern, the universal338 modify-a-shipped-sample first-app workflow, the universal339 lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the340 program-side debug order. This skill layers AES-GCM specifics on341 top.342- `doca-sha/SKILL.md` — the sibling library in the343 DOCA Crypto Acceleration family for hardware-accelerated SHA344 hashing. Load alongside this skill when the user's flow is345 authenticated-encryption *with a separate keyed hash* (rare —346 AES-GCM already provides authentication via its tag) or when the347 user is comparing offload paths between the two.348- `doca-debug/SKILL.md` — the cross-cutting349 debug ladder (install / version / build / link / runtime /350 program / driver). AES-GCM-specific debug (key-size-not-supported,351 oversized input, tag-verification failure on decrypt) overlays on352 top of that ladder.