doca-aes-gcm

# DOCA AES-GCM

**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 [`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 AES-GCM 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 encryption?"*,
the path-selection rule in
[`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the *"when NOT to use doca-aes-gcm"* bullets in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the discovery step in
  [`TASKS.md ## configure`](TASKS.md#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
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  (*do not use the plaintext if the auth tag did not verify*) +
  the decrypt completion-handling workflow in
  [`TASKS.md ## test`](TASKS.md#test) and
  [`TASKS.md ## debug`](TASKS.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the mmap-set-permissions checklist in
  [`TASKS.md ## test`](TASKS.md#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
  [`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
  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_IO_FAILED`
  on the decrypt completion — is this a hardware bug or a tag
  mismatch?"*. Answered by the AES-GCM 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 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 `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, 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
[`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy):
do not log keys, do not commit them to source, and treat any key
bu