Skip to main content
skill CX Codex

doca-aes-gcm — Claude Code skill: encryption on BlueField DPU

doca-aes-gcm — a skill for working with AES-GCM accelerator on BlueField DPU or ConnectX NIC. Handles task configuration for encrypt and decrypt, capability queries for key types, auth tag verification, and error debugging at the API level.

Apache-2.0 ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-aes-gcm -a claude-code
Open on GitHub

What doca-aes-gcm does

doca-aes-gcm is a skill for developers using DOCA SDK to offload AES-GCM authenticated encryption to BlueField DPU or ConnectX NIC hardware. The skill helps configure doca_aes_gcm_task_encrypt and _task_decrypt, query device capabilities via doca_aes_gcm_cap_*, verify key-type and buffer-size support, and debug errors like DOCA_ERROR_NOT_PERMITTED on mmap buffers.

Inside: a decision tree for choosing hardware acceleration versus CPU OpenSSL, security rules for auth-tag handling on decrypt (plaintext is unsafe if tag fails verification), a permission matrix for source and destination buffers, and an error taxonomy. The skill activates on implicit phrasings: "decrypt completion IO_FAILED", "auth tag isn't verifying", "NOT_PERMITTED on my encrypt buffer". Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES).

Only DOCA_AES_GCM_KEY_128 and _256 are available — AES-192 is not in the accelerator. For AES-CBC, AES-CTR, AES-XTS, key management (KMS/HSM), or general AEAD theory, the skill routes elsewhere.

What it helps with

  • Set up encrypt and decrypt tasks on DOCA AES-GCM
  • Check if the device supports your key size and mode
  • Verify auth tag and detect tampered ciphertext on decrypt
  • Fix permission errors on source and destination mmap buffers
  • Decide between hardware acceleration and CPU OpenSSL

Example prompts for the agent

  • Help me configure doca_aes_gcm_task_encrypt for 4 KiB TLS records
  • Should I use DOCA AES-GCM or OpenSSL for my workload?
  • My decrypt returns IO_FAILED — what does it mean and is the plaintext safe?

How to install doca-aes-gcm

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-aes-gcm -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-aes-gcm/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-aes-gcm/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-aes-gcm

How do I install doca-aes-gcm in Claude Code?

Run npx skills add NVIDIA/skills --skill doca-aes-gcm -a claude-code, then open ~/.claude/skills/doca-aes-gcm/SKILL.md in Claude Code.

What does doca-aes-gcm do?

It is a skill for DOCA SDK work — helping you configure and debug the AES-GCM accelerator on BlueField DPU or ConnectX NIC, check key-type support, verify authentication tags, and understand API errors.

Does DOCA support AES-192-GCM?

No. DOCA AES-GCM exposes only DOCA_AES_GCM_KEY_128 and _256. For AES-192, use a CPU library such as OpenSSL.

Source text

SKILL.md · Apache-2.0
---
license: Apache-2.0
name: doca-aes-gcm
description: >
  Use this skill when the user is doing hands-on DOCA AES-GCM work on a
  BlueField DPU or ConnectX NIC — configuring
  `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 <[email protected]>
  kind: library
  doca_version: "3.5"
  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
  `pkg-config doca-aes-gcm` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
  Only `DOCA_AES_GCM_KEY_128` / `_256` are supported (not AES-192).
  The validation steps require a live DOCA install.
---

# 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 in
  ## Capabilities 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 in
  ## Capabilities and modes
  + the discovery step in
  ## 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 in
  ## Safety policy
  (*do not use the plaintext if the auth tag did not verify*) +
  the decrypt completion-handling workflow in
  ## test 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 in
  ## Error taxonomy
  + the layered ladder in
  ## 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 in
  ## modify.
- **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

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

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for Security →

From the same set312

The whole set →
nvshmem-select-remote-transport nvshmem-select-remote-transport selects an NVSHMEM remote transport using static system facts and CUDA kernel inspection. Helps configure multi-node GPU communication without running benchmarks. CX Codex +1 ★ 4,106repo stars pva-doctor pva-doctor is a Claude Code skill that checks whether a host can handle requested NVIDIA PVA work. Run it before Spec, OpGen, Build-Test, or Debug. CX Codex +1 ★ 4,106repo stars doca-urom The skill covers the host side of DOCA UROM: moving MPI/UCX remote memory operations off the host CPU onto a BlueField DPU. CX Codex +1 ★ 4,106repo stars tao-validate-recipe-transfer tao-validate-recipe-transfer guides porting official computer vision research code to custom datasets and diagnoses why transferred models underperform. CX Codex +1 ★ 4,106repo stars complexa-sweep complexa-sweep orchestrates cartesian-product hyperparameter sweeps over Proteina-Complexa design pipelines. Generates inference configs from sweep axes, runs design for each, and ranks results by quality and cost metrics. CX Codex +1 ★ 4,106repo stars nvidia-app Controls the NVIDIA App and its in-game overlay through a local MCP server directly from your coding assistant. CX Codex +1 ★ 4,106repo stars doca-argus This skill guides deployment and operation of DOCA Argus on BlueField, including detection settings and SIEM forwarding. Use it when findings are missing or arriving as noisy alerts. CX Codex +1 ★ 4,106repo stars doca-pcc Host-side DOCA PCC skill for deploying custom congestion control algorithms on BlueField DPU. Creates per-port contexts, loads compiled PCC images, attaches them to RoCE ports, and debugs load errors. CX Codex +1 ★ 4,106repo stars

Project sponsors

Companies that keep this analytics open