/doca-aes-gcm

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)