# Evaluation Report

Evaluation of the `doca-aes-gcm` skill before publication through Skill Evaluator.

This benchmark summarizes 3-Tier Evaluation from Skill Evaluator results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.

## Evaluation Summary

- Skill: `doca-aes-gcm`
- Evaluation date: 2026-07-23
- Skill Evaluator profile: `external`
- Environment: `k8s-sandbox`
- Dataset: 4 evaluation tasks
- Attempts per task: 1
- Pass threshold: 50%
- Overall verdict: PASS

## Agents Used

- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`)
- Codex (`openai/openai/gpt-5.5`)

## Metrics Used

Reported benchmark dimensions:

- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.

Underlying evaluation signals used in this run:

- `security` (Security): checks for unsafe operations, secret leakage, and unauthorized access.
- `skill_execution` (Skill Execution): verifies that the agent loaded the expected skill and workflow.
- `skill_efficiency` (Efficiency): checks routing quality, decoy avoidance, and redundant tool usage.
- `accuracy` (Accuracy): grades final-answer correctness against the reference answer.
- `goal_accuracy` (Goal Accuracy): checks whether the overall user task completed successfully.
- `behavior_check` (Behavior Check): verifies expected behavior steps, including safety expectations.

## Test Tasks

The benchmark dataset contained 4 evaluation tasks:

- Positive tasks: 3 tasks where the skill was expected to activate.
- Negative tasks: 1 tasks where no skill was expected.
- Unlabeled tasks: 0 tasks where positive/negative intent could not be inferred.

Task composition is derived from the evaluation dataset when possible. Entries with `expected_skill` set are treated as positive skill-activation cases, while entries with `expected_skill: null` are treated as negative activation cases.

## Results

| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 4 | 100% (+0%) | 100% (+0%) |
| Correctness | 4 | 75% (+15%) | 100% (+25%) |
| Discoverability | 4 | 100% (+38%) | 94% (+31%) |
| Effectiveness | 4 | 93% (+57%) | 94% (+46%) |
| Efficiency | 4 | 97% (+39%) | 96% (+66%) |

Score values show skill-assisted performance. Values in parentheses show uplift versus the no-skill baseline when baseline data is available.

## Tier 1: Static Validation Summary

Tier 1 validation passed with observations. Skill Evaluator ran 1 checks and found 7 total findings.

Top findings:

- MEDIUM SCHEMA/folder_hierarchy: Unexpected nesting depth for general skill (`skills/libs/doca-aes-gcm`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/libs/doca-aes-gcm/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/libs/doca-aes-gcm/SKILL.md`)
- MEDIUM SCHEMA/author_missing: Author not specified in metadata (`skills/libs/doca-aes-gcm/SKILL.md`)
- LOW SCHEMA/unexpected_file: Unexpected 'CAPABILITIES.md' in skill root (`skills/libs/doca-aes-gcm/CAPABILITIES.md`)

## Tier 2: Deduplication Summary

This tier was not run or did not produce findings in this report.

## Publication Recommendation

The skill is suitable to proceed toward Skill Evaluator publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

# DOCA AES-GCM capabilities, version overlay, errors, observability, safety

**Where to start:** Pick the H2 anchor that matches your question
(capabilities / version / errors / observability / safety) and read
that section end-to-end. The tables in each section are the
load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from
[SKILL.md](SKILL.md). For the *how* of executing each pattern (the
verbs `configure / build / modify / run / test / debug`), jump to
[TASKS.md](TASKS.md). For the canonical DOCA version-handling rules
that this skill layers an AES-GCM overlay on top of, see
[`doca-version`](../../doca-version/SKILL.md).

## Pattern overview

Every DOCA AES-GCM question this skill teaches resolves into one of
SIX patterns. The patterns are CLASSES — they apply across every
AES-GCM release and every BlueField / ConnectX device the accelerator
runs on.

| Pattern | When it applies (class shape) | Where the substance lives |
| --- | --- | --- |
| 1. Decide whether to offload | Compare the per-call setup cost of doca-aes-gcm against a CPU AES-GCM (OpenSSL `EVP_aes_*_gcm`) on the same input; choose offload only when the input is bulk, sustained, or already pinned in `doca_mmap` memory | [`## Capabilities and modes`](#capabilities-and-modes) path-selection table + [`## Safety policy`](#safety-policy) *"when NOT to use doca-aes-gcm"* bullets |
| 2. Pick the task type | Encrypt (`doca_aes_gcm_task_encrypt`) to produce ciphertext + auth tag from plaintext + key + IV + AAD; decrypt (`doca_aes_gcm_task_decrypt`) to verify the tag and produce plaintext from ciphertext + key + IV + AAD + expected tag | [`## Capabilities and modes`](#capabilities-and-modes) encrypt-vs-decrypt table + [TASKS.md ## modify](TASKS.md#modify) |
| 3. Discover capabilities | Query `doca_aes_gcm_cap_*` for task-type presence, per-key-size support, and max plaintext size per submission, against the active `doca_devinfo` BEFORE choosing the key size or sizing buffers | [`## Capabilities and modes`](#capabilities-and-modes) capability-query rule + [TASKS.md ## configure](TASKS.md#configure) step 2 |
| 4. Honor source / destination permissions | Source mmap = `DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum; destination mmap = `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`; both must be set BEFORE the first task submission | [`## Safety policy`](#safety-policy) permission matrix + [TASKS.md ## test](TASKS.md#test) |
| 5. Treat auth-tag verification as security-critical | On decrypt, the auth tag MUST verify before the plaintext output is consumed. A failed verification is a security-relevant event — the ciphertext was tampered with or corrupted, and the plaintext output of that task is poisoned | [`## Error taxonomy`](#error-taxonomy) decrypt-failure row + [`## Safety policy`](#safety-policy) AEAD-discipline section |
| 6. Diagnose an AES-GCM error | Map symptom (`DOCA_ERROR_BAD_STATE`, `_INVALID_VALUE`, `_NOT_SUPPORTED`, `_NOT_PERMITTED`, `_AGAIN`, `_IO_FAILED`) to root cause — lifecycle, key-size, oversized input, permission, queue pressure, or tag verification failure — without leaving the AES-GCM layer prematurely | [`## Error taxonomy`](#error-taxonomy) + [TASKS.md ## debug](TASKS.md#debug) |

Three cross-cutting rules that apply to *every* pattern above:

- **AES-GCM is AEAD, not raw AES.** AES-GCM provides confidentiality
  AND integrity in one operation; the auth tag on encrypt and the
  tag verification on decrypt are not optional add-ons. Treating
  AES-GCM like AES-CTR (where there is no tag) or AES-CBC (where
  authentication is a separate HMAC) is the single most common
  baseline-agent error. If the user wants a non-AEAD AES mode, the
  answer is CPU + OpenSSL — not this library.
- **Discover the version-installed surface, do not assume.** Every
  pattern above gates on `pkg-config --modversion doca-aes-gcm` and
  on the `doca_aes_gcm_cap_*` capability queries against the active
  `doca_devinfo`. Quoting a key-size, a max plaintext size, or even
  the presence of the encrypt or decrypt task without checking is
  the most common hallucination failure mode.
- **Validate against a published test vector before bulk.** The
  cheapest way to confirm the configured AES-GCM context produces a
  correct ciphertext + tag is to encrypt + decrypt a small fixed
  input (e.g. a NIST GCMVS vector or an RFC 5288 AES-GCM example)
  with a known key + IV + AAD and verify both directions match the
  published output, before submitting any user data.

## Capabilities and modes

DOCA AES-GCM is a **DOCA Core Context**. Every AES-GCM instance
follows the universal `cfg-create → cfg-set-* → init → start → use
→ stop → destroy` lifecycle (see
[`doca-programming-guide CAPABILITIES.md ## Capabilities and modes`](../../doca-programming-guide/CAPABILITIES.md#capabilities-and-modes)).
On top of that lifecycle, DOCA AES-GCM layers its own task model and
key-size-selection surface.

**The two task types.** DOCA AES-GCM exposes two task types; each has
its own `doca_aes_gcm_task_*_set_conf` (enable the task) and its own
matching `doca_aes_gcm_cap_task_*_is_supported` (capability query)
entry point. The agent must call the capability query before assuming
the task type is available on the user's device.

| Task type | Class shape | Notes |
| --- | --- | --- |
| `doca_aes_gcm_task_encrypt` | Take a single source `doca_buf` (plaintext) + key + IV + optional AAD, produce ciphertext in a destination `doca_buf` plus an authentication tag | Asynchronous; completion arrives via `doca_pe_progress`. The output is ciphertext + a tag the receiver must check. The plaintext-per-submission ceiling is `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`. |
| `doca_aes_gcm_task_decrypt` | Take a single source `doca_buf` (ciphertext) + key + IV + optional AAD + expected auth tag, verify the tag, produce plaintext in a destination `doca_buf` | Asynchronous; completion arrives via `doca_pe_progress`. **Tag verification is mandatory** — if the completion reports a verification failure, the plaintext output is *not* safe to consume (see [`## Safety policy`](#safety-policy)). |

**Path selection — encrypt vs decrypt.** The two task types are
independent surfaces; a single AES-GCM context can have both enabled
(typical) or just one (e.g. a producer side only encrypts; a
consumer side only decrypts). Choose at least one before
`doca_ctx_start()`.

| Path | What it is | Right shape for | Wrong shape for |
| --- | --- | --- | --- |
| Encrypt only | Configure only `doca_aes_gcm_task_encrypt`; the context produces ciphertext + tag for downstream consumers | A producer-only pipeline (log-shipper that encrypts before send, a backup writer encrypting before storing) | Any flow that also needs to consume incoming AES-GCM-protected data on the same context |
| Decrypt only | Configure only `doca_aes_gcm_task_decrypt`; the context consumes ciphertext + tag and produces verified plaintext | A consumer-only pipeline (a TLS record receiver, a backup reader decrypting before processing) | Any flow that also needs to produce outgoing AES-GCM-protected data on the same context |
| Both | Both tasks enabled on the same context | A symmetric peer that both encrypts outbound and decrypts inbound (the canonical case for an end-to-end encrypted channel) | A read-only or write-only flow — enabling the unused side adds setup overhead without benefit |

**Path-selection — when to use DOCA AES-GCM at all.** The agent's
rule:

- **Use doca-aes-gcm when** the input is bulk (rule of thumb: ≥ a
  few KiB per record and sustained), the throughput requirement is
  high enough that freeing the CPU for other work is valuable, or
  the input is already pinned in `doca_mmap` memory because another
  DOCA library produced it. TLS record encryption at line rate,
  encrypted storage (data-at-rest pipelines), and high-throughput
  backup encryption are the canonical fits.
- **Do NOT use doca-aes-gcm when** the input is a single tiny
  message (the per-call DMA-to-accelerator setup cost dominates;
  CPU + AES-NI is faster); when the user needs a non-GCM AES mode
  (CBC, CTR, XTS — use CPU + OpenSSL, not this library); or when
  the user needs *only* a keyed hash for authentication without
  encryption (use [`doca-sha`](../doca-sha/SKILL.md) for hashing,
  or a CPU HMAC).

**AES-GCM key sizes — only 128 and 256.** AES-GCM is defined in
the spec for 128 / 192 / 256-bit keys, but the DOCA AES-GCM
library's `enum doca_aes_gcm_key_type` exposes only
`DOCA_AES_GCM_KEY_128` and `DOCA_AES_GCM_KEY_256` — **AES-192-GCM
is NOT expressible through this library at all**. The agent must
not invent an AES-192 path. Per-device support for each of the
two real key types is still cap-gated: call
`doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)`
and the matching `_decrypt_is_key_type_supported` query before
sizing key material.

| Key size (bits) | `doca_aes_gcm_key_type` enum value | Key length (bytes) | Notes |
| --- | --- | --- | --- |
| 128 | `DOCA_AES_GCM_KEY_128 = 1` | 16 | Often supported; the smallest AES-GCM key the library accepts |
| 256 | `DOCA_AES_GCM_KEY_256 = 2` | 32 | Often supported; the most common choice for new deployments |
| 192 | *(not in the enum)* | *(n/a)* | NOT supported by the DOCA AES-GCM library — route to a CPU library if AES-192 is a hard requirement |

The agent must NOT quote either of the two real key types as
universally available — the cap query against the active
`doca_devinfo` is the runtime authority. A response that
recommends a key size without first naming the cap query — or
that quotes AES-192 as a per-device-cap-queried option — is the
baseline-agent failure mode this skill exists to prevent.

**Capability discovery — the only rule.** Before choosing a key size
or sizing any plaintext buffer, call the matching
`doca_aes_gcm_cap_*` query against the active `doca_devinfo`:

| Capability | Query | Why the agent must ask |
| --- | --- | --- |
| Encrypt task supported | `doca_aes_gcm_cap_task_encrypt_is_supported(devinfo)` | If false, the device has no AES-GCM encrypt accelerator and the user must fall back to CPU |
| Decrypt task supported | `doca_aes_gcm_cap_task_decrypt_is_supported(devinfo)` | If false, the device has no AES-GCM decrypt accelerator; the user must fall back to CPU for inbound |
| Key type supported for encrypt | `doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)` | Per-key-type boolean against the real `enum doca_aes_gcm_key_type` (`DOCA_AES_GCM_KEY_128` or `DOCA_AES_GCM_KEY_256`); AES-192-GCM is NOT in the enum and cannot be queried |
| Key type supported for decrypt | `doca_aes_gcm_cap_task_decrypt_is_key_type_supported(devinfo, key_type)` | Same surface for the decrypt task |
| Maximum encrypt plaintext size | `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)` | Hardware-bound ceiling on plaintext size per submission; inputs larger than this require the user to fragment at the application layer |

**Configuration shape.** *Mandatory* configurations before
`doca_ctx_start()`: at least one task type enabled via
`doca_aes_gcm_task_encrypt_set_conf` or
`doca_aes_gcm_task_decrypt_set_conf`, and the matching mmap
permissions set on both source and destination buffers per the
matrix in [`## Safety policy`](#safety-policy). Key material is
typically passed as part of the per-task setup; key bytes never live
in the skill or in the configured context for longer than the user's
own program needs them.

## Version compatibility

For the canonical DOCA version-detection chain, the four-way match
rule, NGC container semantics, and the headers-win-over-docs rule,
see [`doca-version`](../../doca-version/SKILL.md). The body lives
there; this skill does not duplicate it.

**The AES-GCM-specific overlay** is:

- **Per-key-type membership is device-bound, not version-bound.**
  The agent must not infer *"DOCA version X includes a third
  AES-GCM key size"* from release notes alone — the public
  `enum doca_aes_gcm_key_type` has two values
  (`DOCA_AES_GCM_KEY_128`, `DOCA_AES_GCM_KEY_256`); AES-192-GCM
  is NOT in the enum and is not expressible through this library.
  For the two real key types, the runtime authority is
  `doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)`
  / `_decrypt_is_key_type_supported(devinfo, key_type)` against
  the active device. Per the cross-cutting cap-query rule in
  [`doca-version CAPABILITIES.md ## Observability`](../../doca-version/CAPABILITIES.md#observability),
  the cap query is the runtime authority — never quote a key
  type as available from agent memory.
- **Per-device task presence is independent of the library install.**
  An install that ships the `doca-aes-gcm` shared object (verify with `ldconfig -p | grep -i doca_aes_gcm`; the on-disk basename uses underscores on every DOCA release where we have ground truth) does not guarantee a
  particular device exposes both encrypt and decrypt; some device
  generations advertise only one. Confirm via
  `doca_aes_gcm_cap_task_encrypt_is_supported(devinfo)` and
  `_task_decrypt_is_supported(devinfo)` per the cross-cutting
  cap-query rule above; if one returns false on a device the user
  expected to support it, route to
  [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug)
  before invoking the missing codepath.
- **`doca-aes-gcm.pc` plus `doca-common.pc` must both match
  `doca_caps --version`** at the four-way-match check (per
  [`doca-version CAPABILITIES.md ## Version compatibility`](../../doca-version/CAPABILITIES.md#version-compatibility)).
  A common partial-install pattern on hosts where the AES-GCM
  package was installed separately from the rest of DOCA is that
  `doca-aes-gcm.pc` reports release *X* while `doca-common.pc`
  reports release *Y*; route to
  [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug)
  layer 2 before any AES-GCM-layer diagnosis.

## Error taxonomy

AES-GCM-specific overlays on the cross-library `DOCA_ERROR_*`
taxonomy. The cross-library taxonomy itself lives in
[`doca-programming-guide CAPABILITIES.md ## Error taxonomy`](../../doca-programming-guide/CAPABILITIES.md#error-taxonomy);
the rows below are the *AES-GCM surface* meaning that the agent must
disambiguate before falling back to the cross-library response.

| Error | AES-GCM context where it shows up | AES-GCM-specific cause |
| --- | --- | --- |
| `DOCA_ERROR_BAD_STATE` | Any call after `doca_ctx_stop()` or before `doca_ctx_start()`; task submit before the matching `_set_conf` ran | Lifecycle violation. Walk the call sequence against the lifecycle in [`doca-programming-guide CAPABILITIES.md ## Capabilities and modes`](../../doca-programming-guide/CAPABILITIES.md#capabilities-and-modes); confirm the task type the user is submitting was enabled via `doca_aes_gcm_task_*_set_conf` before `doca_ctx_start()`. |
| `DOCA_ERROR_INVALID_VALUE` | `doca_aes_gcm_task_*_alloc_init`; submit time | The configured key size is not in the supported set, OR the plaintext exceeds `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`, OR the auth tag length the user passed does not match the AES-GCM spec. Re-run the matching cap query, then resize or correct the tag length. |
| `DOCA_ERROR_NOT_SUPPORTED` | `_task_*_set_conf`; submit with an unsupported key type | The task type is not in this device's accelerator, OR the configured key type is not in this device's supported set. Re-run `doca_aes_gcm_cap_task_*_is_supported` / `_is_key_type_supported` against the active `doca_devinfo`; if false, that is the answer — fall back to CPU or change the key type. |
| `DOCA_ERROR_NOT_PERMITTED` | First task submission | The source mmap does not have `DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` (or a stronger flag that supersedes it), OR the destination mmap is missing `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`, OR the program lacks the access the user's key-handling layer requires. Re-check the matrix in [`## Safety policy`](#safety-policy). |
| `DOCA_ERROR_AGAIN` | `doca_task_submit` on either AES-GCM task type | The task queue is full. This is *not* a hardware error; the program must drain completions via `doca_pe_progress()` before re-submitting. Same as the cross-library *"would-block, retry after progress"* pattern. |
| `DOCA_ERROR_IO_FAILED` (or equivalent device-reported error on the decrypt completion) | `doca_aes_gcm_task_decrypt` completion | **Auth tag verification FAILED on decrypt.** This is the security-relevant outcome: the ciphertext was tampered with or corrupted in transit / at rest. The plaintext output of this task is *poisoned* — do not consume it. Treat the input ciphertext as untrusted, log a security event, and route to the user's application-layer policy for tampered input. Do NOT silently retry. |
| `DOCA_ERROR_DRIVER` | Any submit / completion call | The layer below DOCA reported failure. Capture state and route to env-class debug ([`doca-setup ## debug`](../../doca-setup/TASKS.md#debug)) — the layer below DOCA is the suspect, not the AES-GCM program. |

The agent's rule: **never recommend a retry loop on `DOCA_ERROR_*`
without first identifying which of the rows above is the cause**.
`_AGAIN` is the only one that wants a retry (after
`doca_pe_progress()`); the others want investigation, not retry.
**Tag-verification failure (the `IO_FAILED`-class row above) MUST NOT
be retried** — a retry of the same ciphertext + key + IV + AAD will
fail the same way, and silently re-submitting hides the security
signal.

## Observability

DOCA AES-GCM observability is **event-driven, not poll-driven**.
Every submitted task produces a completion event on the DOCA Core
progress engine; there are no AES-GCM-specific counters the way Flow
has per-pipe counters.

Four primary signals the agent should reach for:

1. **Task completion events on the PE.** Every submitted AES-GCM
   task (encrypt or decrypt) produces a completion event when it
   finishes (or errors). The completion carries the `doca_error_t`
   if it failed; the agent must inspect the per-task completion,
   not the `doca_task_submit()` return value alone. *Submitted but
   no completion* is almost always a missed `doca_pe_progress()`
   call in the user's main loop.
2. **Decrypt completion status — the security-critical signal.** On
   `doca_aes_gcm_task_decrypt` completions specifically, the
   per-task completion result distinguishes "tag verified, plaintext
   is good" from "tag did NOT verify, plaintext is poisoned". The
   agent's observability rule: every decrypt completion must be
   inspected for this status before the plaintext is read; treating
   the absence of a system-level error as "success" misses the
   tampered-ciphertext case.
3. **Capability snapshot at configure time.** The output of every
   `doca_aes_gcm_cap_*` query is a snapshot of *what the device's
   accelerator said was possible* before any task was submitted.
   Save it as the baseline; if a task later returns
   `DOCA_ERROR_NOT_SUPPORTED` or `DOCA_ERROR_INVALID_VALUE` the diff
   against this snapshot is the bug.
4. **Known-vector round-trip.** The cheapest correctness signal is
   to encrypt + decrypt a small fixed input (a published AES-GCM
   test vector — NIST GCMVS or RFC 5288 example) with a known key +
   IV + AAD and compare against the published ciphertext + tag (on
   encrypt) and recovered plaintext (on decrypt). If the
   accelerator produces a different ciphertext or fails to recover
   the plaintext, the configuration is wrong; do not move on to
   bulk input.

For cross-cutting observability primitives (`--sdk-log-level`, the
`doca-<lib>-trace` build flavor, the `DOCA_LOG_LEVEL` env var) see
[`doca-debug CAPABILITIES.md ## Observability`](../../doca-debug/CAPABILITIES.md#observability).
For the install-tree observability (logger names, package layout)
defer to
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).

## Safety policy

> **Overlay on the bundle-wide hardware-safety meta-policy.** The rules below are this skill's per-artifact overlay on the cross-cutting rules in [`doca-hardware-safety` CAPABILITIES.md ## Safety policy](../../doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically [### Per-artifact overlay pattern](../../doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

DOCA AES-GCM's safety surface is **buffer-permission discipline plus
AEAD discipline plus key-handling discipline plus path-selection
discipline**. AES-GCM is authenticated encryption; an incorrect
permission flag, a skipped tag check on decrypt, a leaked key, or
the wrong choice of accelerator-vs-CPU each produces a distinct
class of failure, and the agent's job is to verify all four before
any submission.

The **permission matrix** the agent must walk for any new AES-GCM
setup:

| Buffer | Minimum mmap permission | Class shape | Common over-broad mistake |
| --- | --- | --- | --- |
| Source (plaintext on encrypt / ciphertext on decrypt) | `DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` | The accelerator only needs to read the input; granting write is unnecessary and a small attack-surface widening | Granting `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE` "to keep things simple" — works, but the read-only flag is the safe minimum |
| Destination (ciphertext on encrypt / plaintext on decrypt) | `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE` | The accelerator writes the output; the application reads it back | Reusing the source `doca_mmap` as the destination — fails at submit if the mmap is read-only; if both buffers share an mmap, the mmap must be read-write |

**AEAD discipline — the rules the agent must surface every time.**

- **AES-GCM is authenticated encryption.** The output of encrypt is
  ciphertext PLUS an auth tag; the input to decrypt is ciphertext
  PLUS an expected auth tag. The agent must never describe AES-GCM
  as if it were AES-CTR (where there is no tag) or AES-CBC (where
  authentication is a separate HMAC). A response that surfaces only
  the ciphertext path and ignores the tag is wrong by construction.
- **AAD (additional authenticated data) is authenticated but not
  encrypted.** When the user passes AAD on encrypt, the tag covers
  both the ciphertext and the AAD; on decrypt, the same AAD must be
  passed alongside the ciphertext and tag, or verification will
  fail. AAD is the slot for protocol headers, sequence numbers, or
  any context the receiver must be able to bind to the ciphertext.
- **Tag verification failure on decrypt is poisoned output.** If
  `doca_aes_gcm_task_decrypt` reports a tag-verification failure on
  its completion (the `IO_FAILED`-class row in
  [`## Error taxonomy`](#error-taxonomy) above), the plaintext
  output of that task is *not* safe to consume. The ciphertext was
  tampered with or corrupted in transit / at rest; the right
  response is to discard the plaintext, treat the input as
  untrusted, log a security event, and route to the user's
  application-layer policy. A silent retry on the same ciphertext
  is wrong by construction — the failure is deterministic.

**Key-handling discipline — operational rules, not key-management
substance.** Key management itself (generation, storage, rotation,
distribution) is out of scope for this skill; it belongs to the
user's KMS / HSM / sealed-storage system. The skill's only
operational rules:

- **Do not log key bytes.** Trace-level DOCA logging (`DOCA_LOG_LEVEL=trace`)
  can be verbose; the agent must not recommend dumping the key
  buffer in user-side prints. If the agent is helping the user
  instrument their program, the *length* of the key is observable;
  the *contents* are not.
- **Do not commit key bytes.** Hard-coded keys in a sample diff are
  a leak waiting to happen; the agent's `## modify` workflow MUST
  surface this as a hazard if the user pastes a key into a code
  edit.
- **Treat the key buffer as sensitive memory.** When the program is
  done with the key, zero it before free. The library does not own
  the key bytes; the user does.

**Path-selection — when NOT to use doca-aes-gcm.** Equally important:

- **Tiny one-shot encryption.** A single 64-byte AES-GCM encrypt on
  the CPU (AES-NI) is faster than the DMA-to-accelerator setup. The
  agent should recommend doca-aes-gcm only when the input is ≥ a
  few KiB *and* sustained, *or* the input is already pinned in
  `doca_mmap` memory because another DOCA library produced it.
- **Non-GCM AES modes.** If the user wants AES-CBC, AES-CTR, or
  AES-XTS, the answer is CPU + OpenSSL (or another CPU library) —
  not this library. The agent must not invent
  `doca_aes_*_cbc` / `_ctr` / `_xts` symbols; this library covers
  GCM specifically.
- **Authentication without encryption.** If the user needs only a
  keyed hash for integrity (e.g. an HMAC over a plaintext payload),
  AES-GCM is the wrong tool. Route to
  [`doca-sha`](../doca-sha/SKILL.md) for hardware-accelerated SHA
  hashing, or to CPU HMAC.

**The mmap must stay valid until the AES-GCM context is destroyed.**
Destroying either the source or destination mmap before
`doca_ctx_destroy()` is a use-after-free on the library's
bookkeeping; symptoms include `DOCA_ERROR_BAD_STATE` from subsequent
calls and undefined behavior on outstanding tasks.

**Validate against a known vector BEFORE bulk submission.** A single
known-vector smoke (one short input with a published key + IV + AAD
+ ciphertext + tag) catches key-size mis-selection, IV-length
assumptions, AAD-binding bugs, and tag-length errors before they
silently corrupt or poison a multi-GiB result.

## Deferred topic boundaries

This skill scopes itself to the DOCA AES-GCM library. Adjacent
topics the agent will get asked but should route elsewhere:

- **General AEAD / cryptography background** (why GCM is preferred
  over CBC-then-HMAC, GCM nonce-reuse pitfalls beyond the API
  surface, the underlying GHASH construction, when to choose AES-GCM
  vs ChaCha20-Poly1305) — outside this skill. Route to upstream NIST
  / IETF cryptography documentation; this skill assumes the user
  already knows AES-GCM is the right primitive and is asking *how to
  express it through the DOCA AES-GCM API*.
- **Key management** (key derivation functions, key rotation
  schedules, HSM integration, key escrow) — owned by the user's
  KMS / HSM stack, not this library. The skill's only contribution
  is the operational key-handling discipline in
  [`## Safety policy`](#safety-policy).
- **DOCA Core context and progress engine internals** — owned by
  [`doca-programming-guide`](../../doca-programming-guide/SKILL.md).
  This skill *uses* the Core context lifecycle; it does not
  redefine it.
- **Cross-cutting `DOCA_ERROR_*` taxonomy** — owned by
  [`doca-programming-guide CAPABILITIES.md ## Error taxonomy`](../../doca-programming-guide/CAPABILITIES.md#error-taxonomy).
  This skill adds the AES-GCM overlay, not the taxonomy itself.
- **Other DOCA crypto-acceleration libraries (DOCA SHA, DOCA
  Compress, DOCA DMA)** — separate libraries with their own skills
  (when they ship). Path-selection guidance in
  [`## Capabilities and modes`](#capabilities-and-modes) names them;
  the deep per-library substance lives in the matching skill.
- **Cross-library `doca_caps` invocation patterns** — owned by the
  cross-library `doca-caps` tool skill (when it ships). This skill
  references the *AES-GCM capability query family*
  (`doca_aes_gcm_cap_*`), which is per-library; the *cross-library
  capability snapshot tool* (`doca_caps --list-devs`) is a separate
  surface.

## Description: <br>
Guides AI agents through hands-on DOCA AES-GCM authenticated encryption and decryption work on BlueField DPU or ConnectX NIC hardware, covering task configuration, capability discovery, mmap permissions, NIST/RFC test-vector validation, and DOCA_ERROR debugging. <br>

This skill is ready for commercial/non-commercial use. <br>

## Owner
NVIDIA <br>

### License/Terms of Use: <br>
Apache 2.0 AND CC-BY-4.0 <br>
## Use Case: <br>
Developers and engineers building applications that consume the DOCA AES-GCM C library to offload AES-GCM authenticated encryption and decryption onto a BlueField DPU or ConnectX accelerator. <br>

### Deployment Geography for Use: <br>
Global <br>

## Requirements / Dependencies: <br>
**Requires API Key or External Credential:** [Not Specified] <br>
**Credential Type(s):** [None identified] <br>

Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate. <br>

## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>

## Reference(s): <br>
- [DOCA SDK Documentation](https://docs.nvidia.com/doca/sdk/index.html) <br>
- [DOCA Samples (GitHub)](https://github.com/NVIDIA-DOCA/doca-samples) <br>
- [DOCA Platform Framework (GitHub)](https://github.com/NVIDIA/doca-platform) <br>
- [CAPABILITIES.md](CAPABILITIES.md) <br>
- [TASKS.md](TASKS.md) <br>


## Skill Output: <br>
**Output Type(s):** [Analysis, Configuration instructions, Shell commands] <br>
**Output Format:** [Markdown with inline code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>

## Evaluation Agents Used: <br>
- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) <br>
- Codex (`openai/openai/gpt-5.5`) <br>



## Evaluation Tasks: <br>
Evaluated against 4 internal evaluation tasks (3 positive skill-activation, 1 negative). <br>

## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>

Underlying evaluation signals used in this run: <br>
- `security`: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
- `skill_execution`: Verifies that the agent loaded the expected skill and workflow. <br>
- `skill_efficiency`: Checks routing quality, decoy avoidance, and redundant tool usage. <br>
- `accuracy`: Grades final-answer correctness against the reference answer. <br>
- `goal_accuracy`: Checks whether the overall user task completed successfully. <br>
- `behavior_check`: Verifies expected behavior steps, including safety expectations. <br>



## Evaluation Results: <br>
| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 4 | 100% (+0%) | 100% (+0%) |
| Correctness | 4 | 75% (+15%) | 100% (+25%) |
| Discoverability | 4 | 100% (+38%) | 94% (+31%) |
| Effectiveness | 4 | 93% (+57%) | 94% (+46%) |
| Efficiency | 4 | 97% (+39%) | 96% (+66%) |

## Skill Version(s): <br>
d53d861 (source: git SHA, committed 2026-07-23) <br>

## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

---
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:
  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 local install via
  `pkg-config doca-aes-gcm` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}; the
  accelerator must advertise the desired key type at runtime
  via `doca_aes_gcm_cap_task_{encrypt,decrypt}_is_key_type_supported`
  (only `DOCA_AES_GCM_KEY_128` / `_256`; AES-192 unsupported).
---

# 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
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`](../doca-sha/SKILL.md)), or other DOCA libraries. For
those, use
[`doca-public-knowledge-map`](../../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:

- `CAPABILITIES.md` — 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).
- `TASKS.md` — 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`](../../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`](../../doca-programming-guide/SKILL.md),
  layered with the AES-GCM-specific overrides in
  [`TASKS.md ## modify`](TASKS.md#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.md` 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 [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug — see [TASKS.md](TASKS.md).**

Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules, and
[`doca-public-knowledge-map`](../../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`](../../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`](../doca-sha/SKILL.md).
- [`doca-setup`](../../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`](../../doca-version/SKILL.md) — canonical DOCA
  version-handling rules. This skill's
  [`## Version compatibility`](CAPABILITIES.md#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`](../../doca-structured-tools-contract/SKILL.md) —
  the bundle's structured-tools precedence rule (detect / prefer /
  fall back / report). The Command appendix in
  [TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../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`](../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`](../../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.

# SKILLCARD.yaml — provisional, signed at NVCARPS scan time
# Schema: https://github.com/NVIDIA/skills/blob/main/docs/skill-cards.mdx
# This file is generated by `runner/build_skillcards.py`; do not hand-edit.
# Re-run after any change to SKILL.md frontmatter or the deep-E2E baseline.

schema_version: "1"

identity:
  name: "doca-aes-gcm"
  artifact_id: "doca-aes-gcm"
  kind: "library"
  version: "TBD-at-sign-time"          # NVCARPS fills from the source ref
  signature: "TBD-at-sign-time"        # NVCARPS-generated SHA + ed25519 sig
  signed_by: "TBD-at-sign-time"        # NVCARPS identity (NVIDIA-PSIRT signing key)

description: "Use this skill when the user is doing hands-on DOCA AES-GCM\nwork on a BlueField DPU or ConnectX NIC — configuring\n`doca_aes_gcm_task_encrypt` / `_task_decrypt`, querying\n`doca_aes_gcm_cap_*` for per-key-type (only\n`DOCA_AES_GCM_KEY_128` / `_256` — AES-192 not supported) and\nper-task support, sizing plaintext against the max-buf cap,\nsetting source / destination mmap permissions, validating\nwith a NIST GCMVS or RFC 5288 vector, or debugging\nDOCA_ERROR_* including the security-critical\ntag-verification-failed outcome on decrypt. Trigger even\nwhen the user does not explicitly mention \"DOCA AES-GCM\" or\n\"AEAD\" — typical implicit phrasings: \"decrypt completion\nIO_FAILED\", \"auth tag isn't verifying\",\n\"NOT_PERMITTED on my encrypt buffer\", \"is AES-192-GCM on\nthis BlueField\" (no), or \"encrypted record came back\ntampered\". Refuse and route elsewhere for non-GCM AES modes\n(CBC / CTR / XTS — CPU OpenSSL), key management\n(KMS / HSM / rotation), SHA (doca-sha), or general AEAD\nbackground."

source:
  repo: "NVIDIA-DOCA/doca-skills"
  path: "skills/libs/doca-aes-gcm/SKILL.md"
  branch: "main"
  license: "Apache-2.0 AND CC-BY-4.0"

provenance:
  scan_run_id: "TBD-at-sign-time"      # NVCARPS scan run UUID
  signed_at:   "TBD-at-sign-time"      # ISO-8601 timestamp from NVCARPS
  upstream_catalog: "https://github.com/NVIDIA/skills"
  upstream_component: "doca"           # see components.d/doca.yml

quality:
  baseline:
    verdict: "PASS"
    blocker_findings: 0
    suite:    "runner/reports/2026-05-26_r15_full_e2e"
    aggregate: "runner/reports/2026-05-26_r15_full_e2e/aggregate.json"
    summary:   "runner/reports/2026-05-26_r15_full_e2e/summary.md"
  regression_contract:
    file:    "runner/baseline_grades.json"
    rule:    "no PASS->FAIL on variant C since last green run"
    gate:    "ci/check-no-regression.py --variant C"

behavior_boundaries:
  documentation_only: true             # bundle ships no runnable code
  hardware_touching_changes_routed_to: "skills/doca-hardware-safety/"
  version_policy_routed_to: "skills/doca-version/"
  external_productized_software_routed_to: "skills/doca-public-knowledge-map/"
  see_also:
    - "AGENTS.md"                       # universal rules
    - "AUTHORING.md"                    # per-skill class-shape contract
    - "BENCHMARK.md"                    # how this skill is graded
    - "SECURITY.md"                     # safety-bug intake

contact:
  bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues"
  safety_bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues/new?labels=safety-bug"
  security:   "https://www.nvidia.com/en-us/security/"

# DOCA AES-GCM workflows

**Where to start:** The verbs run `configure → build → modify → run
→ test → debug`. Skip ahead only when the user is already past a
verb. The `## test` verb is an iterative loop (cap check →
known-vector round-trip → small-bulk → full-bulk → loop back if the
key size or buffer sizing changed), not a one-shot pass — see the
eval-loop overlay in `## test` below.

Read this file when the loader sent you here from
[SKILL.md](SKILL.md). For the underlying capability surface, task
types, key-size surface, capability-query rules, AEAD semantics,
error taxonomy, observability, and safety / path-selection policy,
see [CAPABILITIES.md](CAPABILITIES.md). For the cross-library DOCA
patterns layered under everything below (the universal lifecycle,
the cross-library `DOCA_ERROR_*` taxonomy, the modify-a-shipped-
sample workflow), see
[`doca-programming-guide`](../../doca-programming-guide/SKILL.md).

Each verb below describes the **shape of the workflow**, not a
copy-paste recipe. The agent's job is to walk the user through the
steps in order, verifying preconditions before recommending the
next call.

## configure

Goal: bring up a DOCA AES-GCM context on a host or BlueField and
confirm the device's accelerator supports the task types and key
sizes the user actually intends to use.

Steps the agent should walk the user through:

1. **Confirm the installed DOCA version.** Use the procedure in
   [`doca-version TASKS.md ## configure`](../../doca-version/TASKS.md#configure).
   Quote the version observed (`pkg-config --modversion
   doca-aes-gcm`, then `doca_caps --version`); do not assume
   "latest".
2. **Discover the device capability surface for AES-GCM.** Run
   `doca_caps --list-devs` to see which devices have AES-GCM
   capability, then run the per-`doca_devinfo` `doca_aes_gcm_cap_*`
   queries against the candidate device. Record at minimum:
   `doca_aes_gcm_cap_task_encrypt_is_supported(devinfo)`,
   `doca_aes_gcm_cap_task_decrypt_is_supported(devinfo)`, and for
   each key type the user is considering
   (`DOCA_AES_GCM_KEY_128` and/or `DOCA_AES_GCM_KEY_256` —
   AES-192 is not in the enum and is not supported),
   `doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type)`
   and the matching `_decrypt_is_key_type_supported`.
   Also record
   `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`. The
   capability surface to compare against lives in
   [CAPABILITIES.md ## Capabilities and modes](CAPABILITIES.md#capabilities-and-modes).
3. **Decide whether to offload at all.** Per the path-selection
   bullets in [CAPABILITIES.md ## Safety policy](CAPABILITIES.md#safety-policy),
   doca-aes-gcm is the right answer only when the input is bulk,
   sustained, or already pinned in `doca_mmap` memory. For a tiny
   one-shot encryption, recommend CPU + AES-NI; for a non-GCM AES
   mode, recommend CPU + OpenSSL — do not invent a doca-aes-gcm
   use case the user did not ask for.
4. **Pick the task types per side.** Encrypt-only, decrypt-only, or
   both (the symmetric peer case). The pick decides the next-step
   code shape; the trade-off table lives in
   [CAPABILITIES.md ## Capabilities and modes](CAPABILITIES.md#capabilities-and-modes).
   Do not pick *for* the user when their intent is ambiguous —
   ask whether the program is a producer, a consumer, or both.
5. **Surface the AEAD shape to the user.** Before any code, the
   agent must surface the AEAD-input contract: encrypt takes key +
   IV + AAD (optional) + plaintext, produces ciphertext + auth tag;
   decrypt takes key + IV + AAD (optional) + ciphertext + expected
   tag, verifies the tag, produces plaintext. The user must know
   where each of these comes from (key from their KMS, IV per the
   protocol, AAD per the protocol, plaintext / ciphertext from the
   data flow) before any task config is meaningful.
6. **Configure the AES-GCM instance.** Mandatory before
   `doca_ctx_start()`: enable at least one task type
   (`doca_aes_gcm_task_encrypt_set_conf` and/or
   `doca_aes_gcm_task_decrypt_set_conf`); set source mmap
   permissions (`doca_mmap_set_permissions` to include
   `DOCA_ACCESS_FLAG_LOCAL_READ_ONLY`); set destination mmap
   permissions (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`); size the
   per-submission plaintext to at most
   `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`. Per
   the matrix in [CAPABILITIES.md ## Safety policy](CAPABILITIES.md#safety-policy).
7. **Sanity check before any task submission.** Confirm with the
   user: which task type(s), which key size, source-buffer size,
   destination-buffer size, where the key + IV + AAD come from.
   Run a known-vector round-trip (a published AES-GCM test vector
   from NIST GCMVS or RFC 5288) and verify the ciphertext + tag
   match on encrypt and the plaintext recovers on decrypt before
   any user data flows. If any step fails with a `DOCA_ERROR_*`,
   route through the error taxonomy in
   [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy)
   before retrying.

For the canonical DOCA universal lifecycle that underlies steps 4-7,
see
[`doca-programming-guide TASKS.md ## configure`](../../doca-programming-guide/TASKS.md#configure).
This skill adds the AES-GCM overlay; do not re-explain the lifecycle
here.

## build

Goal: produce a binary that links DOCA AES-GCM against the user's
installed DOCA, using the canonical cross-library build pattern.

The build pattern for any DOCA C/C++ consumer is **identical**
across libraries — `pkg-config` for include + link flags, meson or
CMake as the build system — and is fully documented in
[`doca-programming-guide TASKS.md ## build`](../../doca-programming-guide/TASKS.md#build).
This skill carries only the AES-GCM-specific overlay:

| Slot | Value for AES-GCM | Why it matters |
| --- | --- | --- |
| `pkg-config` module name | `doca-aes-gcm` | The library's `.pc` file installed by the DOCA host packages |
| Required runtime libs | `libdoca-common`, `libdoca-aes-gcm`, plus whatever `pkg-config --libs doca-aes-gcm` resolves to | AES-GCM depends on Core; the link line should not pull in unrelated DOCA libraries |
| Header check | The public header that `pkg-config --cflags` for this artifact resolves to actually exists on disk at the path pkg-config reports (do not hardcode the include path) | If `pkg-config --cflags doca-aes-gcm` resolves but the include is missing, the install is partial |
| Minimum required DOCA version | Query with `pkg-config --modversion doca-aes-gcm`; never hardcode in build files | Cross-version build/runtime mixing breaks per [CAPABILITIES.md ## Version compatibility](CAPABILITIES.md#version-compatibility) |

For non-C consumers (Rust, Go, Python), the link surface is the
same `*.so` files; the FFI wrapper layer is the language-specific
binding and is out of scope for this skill — but the four slots
above are still the load-bearing inputs the wrapper needs.

## modify

Goal: take a shipped DOCA AES-GCM sample as the verified starting
point and apply a minimum-diff modification to express the user's
intent.

The universal modify-a-shipped-sample workflow lives in
[`doca-programming-guide TASKS.md ## modify`](../../doca-programming-guide/TASKS.md#modify).
Use it as-is. The AES-GCM-specific overlay is the *modify-from-sample
schema fill* — the five slots the agent must elicit from the user
before recommending any code-level edit:

| Slot | What the agent asks the user | AES-GCM-specific consideration |
| --- | --- | --- |
| 1. Starting sample | Which sample under `/opt/mellanox/doca/samples/doca_aes_gcm/`? | Pick the closest in *task direction* (encrypt vs decrypt vs both) to the user's intent. Do NOT bridge across both axes — a smaller diff is always safer than a re-architecture |
| 2. Task type added or removed | Which task type from the two? | Each added type needs its own `doca_aes_gcm_task_*_set_conf` call before `doca_ctx_start()`, plus its matching cap-query in [`## configure`](#configure) step 2 |
| 3. Key size change | Switching from AES-128-GCM to AES-256-GCM? (AES-192-GCM is not in the library — `enum doca_aes_gcm_key_type` only has `DOCA_AES_GCM_KEY_128` and `DOCA_AES_GCM_KEY_256`. If the user actually needs AES-192, route to a CPU library.) | Re-run `doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, new_key_type)` (and the matching `_decrypt_is_key_type_supported`); the key buffer length the user provides MUST match the new key type in bytes (16 for `_KEY_128`, 32 for `_KEY_256`). The agent must remind the user that hard-coding key bytes in the diff is a leak; the key comes from the user's KMS, not the source file |
| 4. Buffer-size changes | Plaintext size per submission changing? | Per-submission plaintext must be ≤ `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)`; if the user has larger records, the application layer must fragment (this library does not auto-fragment). Over-broad mmap permissions are a silent security regression |
| 5. AAD shape change | Adding / removing / resizing the additional-authenticated-data field? | AAD must match exactly between encrypt and decrypt for the tag to verify. If the protocol the user is implementing binds a sequence number or header into the AAD, both ends must agree byte-for-byte. AAD mismatches surface only as decrypt tag-verification failures, not as configure-time errors — they are silent until decrypt |

The agent emits an *intent description + the five filled slots*;
the *actual* unified diff against the sample source is produced by
the modify-from-sample renderer (deferred to a future round). Until
the renderer ships, the agent must walk the user through the diff
line-by-line against the sample source they read on disk, and have
the user paste back the result for validation. **Special hazard for
AES-GCM modifications:** the agent must explicitly flag if any
proposed diff includes hard-coded key bytes — that diff is unsafe
to commit regardless of whether it builds.

## run

Goal: actually execute the built binary against the user's
installed DOCA on a host or BlueField, with a real input.

Steps the agent should walk the user through:

1. **Confirm the device is reachable.** AES-GCM runs on a single
   side (no peer); the only env-side requirement is that the
   `doca_dev` the binary opens corresponds to a device whose
   accelerator the user expects. Mismatched `doca_dev` selection
   (opening a NIC without AES-GCM accelerator support) returns
   `DOCA_ERROR_NOT_SUPPORTED` at task submit, not at open.
2. **Run the known-vector round-trip first.** A binary that encrypts
   + decrypts one short fixed input with a published key + IV + AAD
   and compares both directions against the published expected
   output is the cheapest correctness signal. Do not bulk-encrypt
   or bulk-decrypt before this passes.
3. **Capture the structured log.** Set `DOCA_LOG_LEVEL=trace` for
   the first run (see
   [`doca-debug CAPABILITIES.md ## Observability`](../../doca-debug/CAPABILITIES.md#observability)).
   This is the cheapest way to make the lifecycle and task-submit
   transitions visible on first failure. **Do not log the key bytes
   themselves** — the trace flag is for the library, not the user's
   key buffer.
4. **Capture the completion events on the PE.** A run that produces
   no completion events but doesn't error is almost always a missed
   `doca_pe_progress()` call. Confirm the progress engine is being
   driven on the main thread. For decrypt completions specifically,
   inspect the per-completion result for the tag-verification
   status before reading the plaintext.

## test

Goal: prove the configured AES-GCM context can actually produce
correct ciphertexts (on encrypt) and verify + recover plaintexts
(on decrypt) at the user's intended throughput, on the user's
hardware, and that the key size and buffer sizing were right.

> **Performance harness routing.** For *throughput / latency
> measurement* on the configured AES-GCM context (or for cross-library
> comparison against the other DOCA crypto primitives), route the
> user to [`doca-bench TASKS.md ## test`](../../tools/doca-bench/TASKS.md#test)
> — `doca-bench` is the cross-library performance harness with
> documented warm-up / steady-state / outlier semantics, and it
> explicitly supports AES-GCM. The iteration loop below stays the
> *correctness* harness; `doca-bench` is the *performance* harness.
> Hand-rolling a benchmark loop inside this skill's `## test`
> would re-invent what `doca-bench` already does and would not be
> reviewable against published accelerator headroom.

This is **a loop, not a one-shot pass.** Each iteration narrows
either the task type, the key size, the buffer sizing, the AAD
shape, or the permission set. The loop terminates when either (a)
the user's intended AES-GCM workload encrypts + decrypts correctly
end-to-end with acceptable throughput, or (b) the agent has narrowed
the failure cause to a layer outside DOCA AES-GCM itself (driver /
firmware / device) and escalated to the matching skill.

Iteration shape:

1. **Capability re-check.** Re-run
   `doca_aes_gcm_cap_task_encrypt_is_supported`,
   `_task_decrypt_is_supported`,
   `_task_encrypt_is_key_type_supported(devinfo, key_type)` for
   each key type in use (`DOCA_AES_GCM_KEY_128` /
   `DOCA_AES_GCM_KEY_256`), and
   `_task_encrypt_get_max_buf_size` against the active
   `doca_devinfo`. If any return false / unexpected → that's the
   answer; the user's device or DOCA version does not support the
   requested config. Update the intent or update the install.
2. **Permission cross-check.** Compare the configured source +
   destination mmap permissions against the matrix in
   [CAPABILITIES.md ## Safety policy](CAPABILITIES.md#safety-policy).
   Mismatches surface as `DOCA_ERROR_NOT_PERMITTED` on the first
   task submission, not at configure time.
3. **Known-vector round-trip.** Encrypt one short fixed plaintext
   with a published key + IV + AAD and compare the accelerator's
   ciphertext + tag against the published expected ciphertext + tag
   byte-for-byte. Then decrypt the published ciphertext + tag with
   the same key + IV + AAD and verify the plaintext recovers
   byte-for-byte. If either direction differs, the configuration is
   wrong — do not proceed to bulk input.
4. **Completion drain.** Confirm completion events arrive on the PE
   for every submitted task. *Submitted but no completion* is the
   most expensive class of bug to discover late; confirm it on the
   known-vector round-trip before bulk submissions.
5. **Bulk encrypt test.** If the user intends bulk encryption,
   submit a series of encrypt tasks (small inputs first, then sizes
   approaching `_task_encrypt_get_max_buf_size`) and verify the
   ciphertexts + tags against a CPU AES-GCM reference (OpenSSL
   `EVP_aes_*_gcm`). Throughput numbers come from this step;
   correctness comes from step 3.
6. **Bulk decrypt test (with tampering negative).** If the user
   intends bulk decryption, submit the matching ciphertexts + tags
   and verify the plaintexts recover. Then submit ONE deliberately
   tampered ciphertext (flip a single bit) and verify the
   completion reports a tag-verification failure. This validates
   that the agent's tag-check observability is wired up correctly —
   silently accepting a tampered ciphertext is the worst failure
   mode this library exposes.
7. **Negative test for unsupported config.** Once the positive path
   works, use a key type that the step-1 capability query explicitly
   reports unsupported and confirm `DOCA_ERROR_NOT_SUPPORTED`. If the
   device supports both public key types, skip this key-type negative
   test with that reason; do not invent an enum value. An alternative
   negative is allowed only when another capability query explicitly
   declares the selected configuration unsupported.

Eval-loop overlay — why this is a loop, not a one-shot pass:

| Iteration trigger | What it looks like | What changes next iteration |
| --- | --- | --- |
| `DOCA_ERROR_NOT_SUPPORTED` on a key size we expected to work | The docs list the key size but the cap query returns false | The agent quoted the *library* surface; the *device* capability per `doca_devinfo` is the real gate. Re-narrow to the device-level query. |
| `DOCA_ERROR_INVALID_VALUE` on first submit | Plaintext is larger than `_task_encrypt_get_max_buf_size`, OR the auth-tag length the user passed does not match the AES-GCM spec, OR the key length does not match the declared key size | Re-size the buffer using the cap-query output, or correct the tag / key length. The error is sizing-vs-cap mismatch, not corruption. |
| Known-vector encrypt produces a wrong ciphertext or tag | Configuration accepted but output mismatches the published vector | Key-size mis-selection (asked for AES-256-GCM, configured AES-128-GCM), wrong IV length, or AAD bytes not matching the vector. Re-check the key length, IV length, and AAD bytes against the published vector before any other diagnosis. |
| Known-vector decrypt fails to recover the plaintext | Encrypt round-trips fine but decrypt with the published ciphertext + tag fails verification | Either the AAD passed to decrypt does not match the AAD used at encrypt, or the expected-tag pointer is wrong, or the key bytes differ between the two sides. AAD mismatch is the most common cause. |
| Submitted task produces no completion | `doca_task_submit()` returned `DOCA_SUCCESS`; the PE produces nothing | The PE is not being progressed. Add a `doca_pe_progress()` call in the main loop. |
| Decrypt completion reports `IO_FAILED` (or equivalent tag-verification-failure status) on real user ciphertext | Tag verification failed on data the user thought was good | This is a **security signal**, not a code bug: the ciphertext was tampered with or corrupted in transit / at rest. Do not consume the plaintext, do not retry the decrypt — treat the input as untrusted and route to the user's application-layer policy for tampered input. |
| Bulk submit returns `DOCA_ERROR_AGAIN` | First N submissions succeed, then `AGAIN` | The task queue is full. Drain completions between bursts via `doca_pe_progress()`, or raise the configured queue depth at configure time. |

Loop termination: an iteration kind is one row of the table above:
capability re-check, permission fix, sizing fix, known-vector/AAD
fix, completion drain, or queue-pressure fix. After each
single-variable fix, re-capture that row's observable result. Stop
after two consecutive iterations of the same kind leave both the
relevant configuration or capability output and the observed symptom
unchanged — that means the cause is below DOCA AES-GCM. Escalate to
[`doca-debug TASKS.md ## debug`](../../doca-debug/TASKS.md#debug)
with the captured cap-query snapshot + known-vector diff as
evidence.

## debug

Goal: when a DOCA AES-GCM call returns a `DOCA_ERROR_*` (or the
program produces no completion event, or a decrypt completion
reports a tag-verification failure), narrow the cause to a specific
layer and act on it.

The cross-library debug ladder lives in
[`doca-debug TASKS.md ## debug`](../../doca-debug/TASKS.md#debug).
Walk through it in order — install → version → build → link →
runtime → program → driver — *before* recommending AES-GCM-specific
fixes. This skill's overlay names the AES-GCM-specific manifestation
at layers 5 (runtime) and 6 (program):

**Layer 5 (runtime) — AES-GCM overlay.**

- Walk the lifecycle: was the context started? Was the task enabled
  before start (`doca_aes_gcm_task_*_set_conf` before
  `doca_ctx_start()`)? Submitting before the task is enabled
  returns `DOCA_ERROR_BAD_STATE`, not a clear symptom.
- Confirm the PE is being progressed. *No completion events* is
  almost always a missing `doca_pe_progress()` in the user's main
  loop.
- Confirm both the source mmap and the destination mmap are still
  alive at submit time. Destroying either before `doca_ctx_destroy`
  is a use-after-free that surfaces as `DOCA_ERROR_BAD_STATE` from
  subsequent calls.

**Layer 6 (program) — AES-GCM overlay.**

- Key-type discipline: a `_set_conf` or submit call that quotes a
  key type the cap query returns false for returns
  `DOCA_ERROR_NOT_SUPPORTED`. Re-run the cap query against the
  active `doca_devinfo`; do not assume from prior installs. The key
  buffer length in bytes (16 / 32) MUST match the declared key
  type (128-bit `DOCA_AES_GCM_KEY_128` or 256-bit
  `DOCA_AES_GCM_KEY_256`; AES-192 is not in the enum).
- Buffer-sizing matrix: the most common AES-GCM program-layer bug
  is a plaintext larger than
  `doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)` —
  surfaces as `DOCA_ERROR_INVALID_VALUE` at submit. The fix is to
  fragment at the application layer; this library does not
  auto-fragment.
- AAD-binding mismatch (decrypt-only symptom): if encrypt + decrypt
  round-trips fail on the user's own data but pass on a published
  vector, the AAD bytes the user passes to decrypt do not match the
  AAD bytes used at encrypt. AAD mismatches are silent at configure
  time and only surface as tag-verification failure on decrypt
  completion. Walk the user's AAD construction on both sides
  byte-for-byte.
- IV / nonce discipline: AES-GCM tag verification depends on the
  exact same IV being passed to encrypt and decrypt. An IV
  mismatch between the two sides surfaces as a tag-verification
  failure, identical to a tampered ciphertext. Walk the user's IV
  source on both sides (per-record counter, random per record, …)
  to disambiguate.
- Tag-verification failure on real data — security-critical path.
  When a decrypt completion reports the tag-verification-failure
  status on data the user expected to be good, the agent's response
  must be:
  (a) treat the plaintext output as poisoned — do not consume it;
  (b) treat the input ciphertext as untrusted — log a security
  event with the IV, AAD, and the upstream source the ciphertext
  came from (NOT the key);
  (c) do NOT silently retry — retrying the same ciphertext + key +
  IV + AAD will fail the same way and hides the security signal;
  (d) route the user to their application-layer policy for
  tampered input (rotate keys? drop the connection? quarantine the
  storage object?).
- Known-vector mismatch: if a published-vector encrypt produces a
  wrong ciphertext, the key bytes, IV bytes, or AAD bytes the
  program is passing do not match the vector. If the tag is the
  wrong length, the user has misconfigured the tag-length field.

Once the layer is identified, route to the matching debug verb on
the matching skill: install / build / link / driver to
[`doca-setup ## debug`](../../doca-setup/TASKS.md#debug); version to
[`doca-version ## debug`](../../doca-version/TASKS.md#debug);
cross-cutting runtime to
[`doca-debug ## debug`](../../doca-debug/TASKS.md#debug);
program-layer Core-context patterns to
[`doca-programming-guide TASKS.md ## debug`](../../doca-programming-guide/TASKS.md#debug).

## Deferred task verbs

The following verbs are out of scope for this skill but are
commonly asked in the same conversations. Route them as follows so
the agent does not invent guidance:

- **install.** Installing DOCA, choosing packages, post-install
  verification, `pkg-config` wiring — defer to
  [`doca-setup`](../../doca-setup/SKILL.md) and to the install-tree
  layout in
  [doca-public-knowledge-map ## Layout of an installed DOCA package](../../doca-public-knowledge-map/SKILL.md#layout-of-an-installed-doca-package).
  This skill assumes DOCA is already installed.
- **deploy.** Deploying AES-GCM-using applications at scale
  (TLS-record encryption workers across many hosts, encrypted
  storage daemons, Kubernetes operator workflows) — out of scope
  for Phase 1 and reserved for a future platform skill. For
  single-host first-run testing, the right verb in this skill is
  `## run`; do not invent a "deploy" workflow.
- **rollback.** Coordinated rollback of AES-GCM-using applications
  across many hosts — out of scope. For a single in-session
  AES-GCM configuration rollback, the right verb in this skill is
  destroying the context (`doca_ctx_stop` → `doca_ctx_destroy`)
  and re-running [`## configure`](#configure) with corrected
  parameters.
- **key management.** Key generation, rotation, escrow, KMS / HSM
  integration — outside this skill. The skill's only key-handling
  contribution is the operational discipline in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  (do not log keys, do not commit keys, zero key buffers before
  free). The actual key-management substance belongs to the user's
  KMS or HSM documentation.
- **kernel-level driver install / firmware burn.** AES-GCM depends
  on the underlying ConnectX firmware and BlueField BFB; if the
  debug ladder lands on a driver-layer issue, the fix is via
  `mlxconfig` / `mlxfwreset` / re-imaging the BFB, all of which
  belong to
  [`doca-setup ## debug`](../../doca-setup/TASKS.md#debug) layer 5.

## Command appendix

Every command below is **cross-cutting on DOCA AES-GCM** — it
answers a recurring class of question that comes up in the verbs
above. The agent should treat the *class* as load-bearing; the
worked example is a single instance. Run-as user is the
unprivileged user unless noted. Sudo is called out per row.

**Infra-aware preamble (every row below).** Per the bundle's
detect → prefer → fall back → report contract documented in
[`doca-structured-tools-contract ## The agent behavior contract`](../../doca-structured-tools-contract/SKILL.md#the-agent-behavior-contract),
the agent should:

1. Probe for the matching structured helper FIRST (`doca-env --json`
   for version + devices + libraries + drivers + hugepages in one
   shot; `doca-capability-snapshot` for per-device capability flags;
   `version-matrix.json` for *"available since"* lookups).
2. If the probe succeeds, the structured tool's output is the
   authoritative answer and the agent SHOULD NOT also run the
   manual command in the row below. Report *"using structured
   `<tool>`"*.
3. If the probe fails, fall back to the manual command in the row.
   Report *"falling back to manual chain"*.
4. The schemas the structured tools emit are defined in
   [`doca-structured-tools-contract ## Schemas`](../../doca-structured-tools-contract/SKILL.md#schemas);
   the version-handling semantics (four-way match, NGC,
   headers-win) are owned by
   [`doca-version`](../../doca-version/SKILL.md).

| Command (worked example) | Owning step | Class of question it answers | What healthy output looks like |
| --- | --- | --- | --- |
| `pkg-config --modversion doca-aes-gcm` | `## configure` step 1; `## build` slot 4 | What is the build-time DOCA AES-GCM version? | A semver string matching `doca_caps --version`. Disagreement = partial install (route to [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug) layer 2) |
| `pkg-config --cflags --libs doca-aes-gcm` | `## build` | What include + link flags does the linker need? | Trust whatever `pkg-config --cflags --libs` produces on this install. Do not hardcode either the `-I` include path or the `-l<name>` flag form — both can drift between DOCA install profiles and DOCA majors; the on-disk `.so` basenames use underscores on every release where we have ground truth, while the `.pc` package names use hyphens, and `pkg-config` is the only thing that resolves both correctly. Hand-crafted `-l` lines silently break when DOCA upgrades. |
| `doca_caps --list-devs` | `## configure` step 2 | Which devices on this host can be used as a `doca_dev` for AES-GCM? | One row per visible device with PCIe address and capability flags; the agent must still run `doca_aes_gcm_cap_*` per-device to confirm key-size support |
| `doca_caps --version` | `## configure` step 1; `## test` step 1 | What is the *runtime* DOCA version on this host? | A semver string matching `pkg-config --modversion doca-aes-gcm` |
| `ls /opt/mellanox/doca/samples/doca_aes_gcm/` | `## modify` slot 1 | Which AES-GCM samples ship in this install, and which is the closest starting point? | A list of sample directories named after the task pattern they demonstrate |
| `cat /opt/mellanox/doca/applications/VERSION` | `## configure` step 1; `## debug` layer 1 | What does the install tree itself claim its version is? | A semver string matching the other two version sources |
| The existing EVP-based CPU reference harness or a published NIST/RFC AES-GCM known vector | `## test` step 5 | What is the CPU-reference ciphertext and tag for the bulk-encrypt comparison? | Ciphertext and tag matching the doca-aes-gcm output for the same key + IV + AAD + plaintext. Do not use `openssl enc -aes-*-gcm`; that CLI is not the bundle's AEAD reference workflow. |
| `dmesg | tail -n 40` (sudo) | `## debug` layer 7 | What did the kernel / driver log around the last AES-GCM call? | Empty or recent benign messages. Repeated mlx5 / accelerator errors → driver-layer bug; route to [`doca-setup ## debug`](../../doca-setup/TASKS.md#debug) |
| `DOCA_LOG_LEVEL=trace ./<binary>` | `## run` step 3 | What did the structured DOCA logger emit for the first failing call? | A trace-level line on every lifecycle transition and every task submission. Silence after submission = PE not progressed. **Do not log the key buffer** — only the library's own trace lines |

For commands shared across libraries (`pkg-config --modversion`,
`doca_caps`, `cat /opt/mellanox/doca/applications/VERSION`,
`DOCA_LOG_LEVEL`) the cross-library overlay is in
[`doca-debug TASKS.md ## Command appendix`](../../doca-debug/TASKS.md#command-appendix);
this table adds the AES-GCM-specific rows on top.