doca-aes-gcm

DOCA AES-GCM

示例

• “解密时认证标签无法验证。”——这属于本技能范围。 将标签验证失败视为安全结果，而非可重试的大小错误。
• “这台 BlueField 支持 AES-192-GCM 吗？”——不支持。只有 key-128 和 key-256；不要臆造 AES-192 或 CBC/CTR 卸载功能。

说明

遵循下方的加载顺序。需要配置／测试／调试时，打开任务配套文件。需要了解密钥类型和 AEAD 安全说明时，打开功能配套文件。不要打开所有配套文件。

**从这里开始：本技能假设 DOCA 已安装，且用户正在 BlueField / ConnectX / 主机上使用 DOCA 实际进行 AES-GCM 加速工作。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果用户想了解此版本中的 DOCA AES-GCM 能实现什么，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户在问“这种加密是否真的应该使用加速器？”，请先查看 ## 功能和模式 中的路径选择规则。如果用户将 AES-GCM 当作仅提供机密性的原语（类似原始 AES-CTR / AES-CBC），请先停止并阅读 ## 安全策略 中的 AEAD 说明——AES-GCM 是认证加密，而混淆两者正是本技能旨在防止的代价最高的失误。

此技能擅长回答的示例问题

此技能旨在回答的 DOCA AES-GCM 问题类别，每类都附有一个完整示例。Agent 应将类别视为核心要点——完整示例只是一个具体实例。

• “我应该将此 AES-GCM 加密卸载到 DOCA AES-GCM，还是直接用 OpenSSL 在 CPU 上处理？”——完整示例：“我正在以线路速率加密 4 KiB 的 TLS 记录；与在 CPU 上使用 OpenSSL EVP_aes_256_gcm 相比，配置 doca-aes-gcm 值得吗？” 由 ## Capabilities and modes 中的路径选择表，以及 ## Safety policy 中的*“何时不应使用 doca-aes-gcm”*要点解答。
• “我的设备是否支持我想用的 AES-GCM 密钥大小？”——完整示例：“这台 BlueField 上的加速器支持 AES-256-GCM 吗？顺便问一下，AES-192-GCM 可用吗？”（答：该库仅提供 DOCA_AES_GCM_KEY_128 / DOCA_AES_GCM_KEY_256；枚举中没有 AES-192，也不支持它。对于两种实际支持的密钥类型，请使用 doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type) 和对应的 _decrypt_is_key_type_supported 进行检查。AES-192 不可用，应改用 CPU 库。）由 ## Capabilities and modes 中针对每种密钥类型的能力查询和针对每种任务的 doca_aes_gcm_cap_task_*_is_supported 查询，以及 ## configure 中的发现步骤解答。
• “如何正确解密 AES-GCM 消息并验证认证标签？”——完整示例：“我的 doca_aes_gcm_task_decrypt 完成时报告错误——可以安全使用明文输出吗？” 由 ## Safety policy 中的认证标签验证规则（认证标签未通过验证时，不要使用明文），以及 ## test 和 ## debug 中的解密完成处理工作流解答。
• “源 / 目标 mmap 需要什么权限？”——完整示例：“我的 doca_aes_gcm_task_encrypt 返回 DOCA_ERROR_NOT_PERMITTED”。由 ## Safety policy 中的权限矩阵，以及 ## test 中的 mmap 权限设置检查清单解答。
• “我安装的 DOCA 版本是否提供此 DOCA AES-GCM API？”——完整示例：“我在这台设备上安装的 DOCA 中支持 AES-192-GCM 吗？” 由 ## Version compatibility 中的版本兼容性补充说明解答；该说明交叉链接到 doca-version/SKILL.md 中的标准检测流程，并补充了 AES-GCM 特有的*“通过能力查询发现密钥大小”*要点。
• “AES-GCM 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？”——完整示例：“我的加密缓冲区出现 DOCA_ERROR_NOT_PERMITTED”。由 ## Error taxonomy 中针对 AES-GCM 对跨库错误分类的补充说明，以及 ## debug 中逐层排查并升级到 doca-debug/SKILL.md 的流程解答。

解密完成时出现 IO_FAILED 并不是调试问题。 这表示认证标签验证失败，是一个安全事件，而不是代码或配置错误——无需按层分类，也无需升级到 doca-debug/SKILL.md。该任务生成的明文已被污染，绝不可使用；不得重试解密；输入密文已被篡改或损坏，必须视为不可信数据；如何处理该结果，应遵循调用方应用层针对篡改输入的策略。请先说明这一点。只有当用户正在使用已知正确的测试向量时，才值得提及配置原因（密钥、IV、AAD 或标签长度错误），即使如此也应放在后面。完整规则见 ## Error taxonomy 和 ## Safety policy。

受众

此技能面向构建应用程序、使用 DOCA AES-GCM 库的外部开发者——也就是说，他们的代码会调用 doca_aes_gcm_*（直接使用 C/C++，或通过其他语言的 FFI/绑定），将 AES-GCM 认证加密/解密任务卸载到 BlueField DPU 或 ConnectX 加速器。此技能不面向为 DOCA AES-GCM 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA AES-GCM 以 C 库的形式提供，其 pkg-config 模块名称为 doca-aes-gcm。随附的示例使用 C 编写。C 和 C++ 消费者是典型情况，任务配套材料中的示例也假定使用这种方式。其他语言的消费者（Rust、Go、Python 等）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，此技能的作用是确保生命周期、能力发现、权限、错误分类、AEAD 语义以及加密与解密方面的指导不依赖具体语言，并引导 Agent 使用公共 C ABI，因为任何封装最终都会调用这一权威接口。

密钥处理不在范围内。 此技能教 Agent 如何使用 DOCA AES-GCM 库；它不会教用户如何生成、存储、轮换或分发 AES-GCM 密钥。密钥管理由用户负责（例如使用 KMS、HSM、密封文件或用户信任的环境变量）。此技能唯一有关密钥处理的规定是

安全策略：

不要记录密钥，不要将密钥提交到源代码中，并将程序持有的任何密钥缓冲区视为敏感内存。

适合加载此技能的场景

当用户正在实际操作 DOCA AES-GCM（使用任何语言）时，加载此技能。 具体包括：

• 在 doca_dev 上初始化 doca_aes_gcm 上下文，并在调用 doca_ctx_start() 之前配置至少一种任务类型（doca_aes_gcm_task_encrypt 和/或 doca_aes_gcm_task_decrypt）。
• 根据用户的数据形态，在加密（doca_aes_gcm_task_encrypt — 接收密钥 + IV + AAD + 明文，生成密文 + 认证标签）和解密（doca_aes_gcm_task_decrypt — 接收密钥 + IV + AAD + 密文 + 预期认证标签，生成明文 并验证标签）之间进行选择。
• 为 doca_mmap 正确设置权限：源缓冲区（至少设置为 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY — 加密时为明文，解密时为密文）和目标缓冲区（设置为 DOCA_ACCESS_FLAG_LOCAL_READ_WRITE）。
• 检查活动设备的加速器支持哪些 AES-GCM 密钥类型（DOCA_AES_GCM_KEY_128 / DOCA_AES_GCM_KEY_256 — 该库不支持 AES-192），方法是调用 doca_aes_gcm_cap_task_encrypt_is_key_type_supported / doca_aes_gcm_cap_task_decrypt_is_key_type_supported；并检查支持哪些任务类型，方法是调用 doca_aes_gcm_cap_task_encrypt_is_supported / _task_decrypt_is_supported。
• 根据 doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo)， 确定每次提交的明文大小。
• 在将任何用户数据交给加速器处理之前，使用公开的 AES-GCM 测试向量（NIST GCMVS，或 RFC 5288 示例）验证加密 + 解密往返操作。
• 将解密完成时的认证标签验证结果视为安全关键信号来处理 — 标签不匹配的完成事件表示密文遭到篡改或损坏；该任务输出的明文已被污染，不得使用。
• 调试 AES-GCM 调用返回的 DOCA_ERROR_*（生命周期、密钥大小不受支持、权限，或解密时的标签验证失败），以及进度引擎上的任务完成事件。
• 设计或扩展非 C 绑定（Rust、Go、Python 等），用于封装 AES-GCM C ABI — 封装必须遵守生命周期、权限、能力、AEAD 语义，以及加密与解密的相关规则。

对于一般性的 DOCA 介绍、DOCA 本身的安装、非 GCM 的 AES 模式（CBC / CTR / XTS — 该库不支持这些模式，正确做法是在 CPU 上使用 OpenSSL）、同一加速器系列上的 SHA 哈希（使用 doca-sha/SKILL.md），或其他 DOCA 库，请勿加载此技能。对于这些情况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个精简加载器。正文仅保留选择下一个合适文件所需的指引。实质性的 AES-GCM 专属内容位于两个配套文件中：

• 能力配套文件——说明当前版本的 DOCA AES-GCM 能实现哪些功能： 两种任务类型（加密和解密）、AEAD 输出形式 （加密时为密文 + 认证标签；解密时为验证后的明文）、 AES-GCM 密钥类型范围（仅支持 128 位和 256 位——枚举中没有 AES-192， 两种类型都通过能力查询确认）、能力查询 范围（通过 doca_aes_gcm_cap_* 查询任务是否存在、密钥类型 支持情况和缓冲区大小）、AES-GCM 错误分类（映射到跨库的 DOCA_ERROR_* 集合，并将标签验证失败结果明确视为安全关键问题）、 可观测性范围（进度引擎上的每任务完成事件）、用于决定源 / 目标 mmap 权限的安全策略和密钥处理注意事项，以及路径选择规则（何时使用 doca-aes-gcm，而非 CPU OpenSSL 或其他 DOCA 加密库）。
• 任务配套文件——涵盖六种适用范围内 AES-GCM 操作的分步工作流：configure、build、modify、run、test、debug。 另有一个 Deferred task verbs 区块，将范围外的问题指向相应的后续技能。

此技能假定主机或 BlueField 已在标准位置安装 DOCA，且用户拥有其公开安装配置预期的权限。本技能不涵盖安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。

此技能明确不提供的内容

此技能提供的是Agent 指引，而不是示例或模板包。为明确边界，特意不包含以下内容，拉取请求也不应添加：

• 预先编写的 DOCA AES-GCM 应用源代码，无论使用哪种语言。 已验证的 AES-GCM 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_aes_gcm/。Agent 的工作是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用示例修改工作流，指导用户以最小差异修改这些文件，再叠加 ## modify 中 AES-GCM 专属的调整。
• 预先计算的 AES-GCM 测试向量。 技能会指导 Agent 使用已发布的测试向量（例如 NIST GCMVS、RFC 5288 AES-GCM 示例）作为已知向量冒烟测试；但不会自带向量库。Agent 必须注明向量来源，以便用户审查。
• 预先准备的 AES-GCM 密钥、IV 或 AAD 字符串。 本仓库中的密钥也会成为每位客户仓库中的密钥——从设计上就不应存在于此处。技能会讲解输入的形式；实际字节由用户从自己的密钥管理系统提供。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等），放置在技能内部。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-aes-gcm 是权威信息来源。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 即使标注为“reference”，此技能目录树中的模拟或不完整产物也会造成误导：用户会误以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其适用范围。
2. 有关 AES-GCM 能力矩阵、任务类型、密钥大小范围、能力查询规则、权限矩阵、AEAD 语义、错误分类、可观测性以及安全／路径选择策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件会相互交叉链接到 doca-version/SKILL.md（其中包含规范的 版本处理规则），并在正确的答案是“查阅公开文档或已安装软件包布局”，而非“AES-GCM 专属指导”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 每个公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。DOCA AES-GCM 页面位于 docs.nvidia.com/doca/sdk/DOCA-AES-GCM/；它属于 DOCA Crypto Acceleration 系列，与 doca-sha/SKILL.md 并列。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及使用公开 NGC DOCA 容器的 我还没有安装 路径。此技能假定已满足其 前置条件。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能的 ## Version compatibility 会链接到四项匹配规则，并仅额外补充 AES-GCM 专属的 “通过能力查询发现密钥大小和任务是否存在” 覆盖说明。
• doca-structured-tools-contract/SKILL.md — 该套件的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 所有库通用的 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的优先修改随附示例的首个应用工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。此技能在此基础上补充 AES-GCM 专属内容。
• doca-sha/SKILL.md — DOCA Crypto Acceleration 系列中的同级库，用于硬件加速 SHA 哈希。当用户的流程是“使用独立的密钥哈希进行认证加密”（较少见——AES-GCM 已通过其标签提供认证），或用户正在比较这两种卸载路径时，请同时加载此技能。
• doca-debug/SKILL.md — 跨领域的调试阶梯（安装／版本／构建／链接／运行时／程序／驱动）。AES-GCM 专属调试（不支持密钥大小、输入过大、解密时标签验证失败）是在此阶梯基础上的补充。