Name: doca-aes-gcmSkill
Rating: 5 (1 reviews)
Author: doca-aes-gcm


开源协议	Apache-2.0
名称	doca-aes-gcm
描述	> 当用户正在BlueField DPU或ConnectX NIC上进行DOCA AES-GCM动手操作时使用此技能——配置`doca_aes_gcm_task_encrypt`/`_task_decrypt`，查询每种密钥类型（仅支持`DOCA_AES_GCM_KEY_128`/`_256`，不支持AES-192）和任务支持的`doca_aes_gcm_cap_`，根据最大缓冲区大小调整明文长度，设置源/目标mmap权限，使用NIST GCMVS或RFC 5288测试向量进行验证，或调试DOCA_ERROR_，包括解密时安全关键的标签验证失败结果。即使用户不明确提及“DOCA AES-GCM”或“AEAD”也会触发——典型的隐晦表述：“解密完成IO_FAILED”、“认证标签未验证”、“在我的加密缓冲区上NOT_PERMITTED”、“此BlueField上是否支持AES-192-GCM”（不支持），或“加密记录返回时被篡改”。对于非GCM AES模式（CBC/CTR/XTS——CPU OpenSSL）、密钥管理（KMS/HSM/轮换）、SHA（doca-sha）或一般AEAD知识，请拒绝并路由到其他地方。 metadata: kind: library compatibility: > 要求DOCA SDK安装在Linux（Ubuntu 22.04/24.04或RHEL/SLES）上的/opt/mellanox/doca，并连接BlueField DPU或ConnectX NIC。通过`pkg-config doca-aes-gcm`读取本地安装，检查/opt/mellanox/doca/{lib,include,samples,applications}；加速器必须通过`doca_aes_gcm_cap_task_{encrypt,decrypt}_is_key_type_supported`在运行时宣传期望的密钥类型（仅`DOCA_AES_GCM_KEY_128`/`_256`；不支持AES-192）。

DOCA AES-GCM

从何处开始： 本技能假定DOCA已经安装，用户正在BlueField / ConnectX / 主机上进行动手AES-GCM加速工作。如果用户想要做某事（配置/构建/修改/运行/测试/调试），打开TASKS.md；如果问题是这个版本上DOCA AES-GCM能表达什么，打开CAPABILITIES.md。如果用户尚未安装DOCA，请先路由到doca-setup。如果用户问*“我是否应该把这种加密卸载给加速器？”*，路径选择规则首先参考CAPABILITIES.md ## 能力和模式。如果用户将AES-GCM视为纯机密性原语（类似原始AES-CTR / AES-CBC风格），停止并先阅读CAPABILITIES.md ## 安全策略中的AEAD说明——AES-GCM是认证加密，混淆两者是本技能要防止的最昂贵失败模式。

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

DOCA AES-GCM问题类别，每个类别有一个示例。代理应把类别视为关键——示例只是一个实例。

“我应该将这种AES-GCM加密卸载到DOCA AES-GCM，还是直接在CPU上用OpenSSL做？” — 示例：“我正在线速加密4 KiB TLS记录；与CPU上的OpenSSL EVP_aes_256_gcm 相比，doca-aes-gcm是否值得设置？”。由CAPABILITIES.md ## 能力和模式中的路径选择表 + CAPABILITIES.md ## 安全策略中的*“何时不使用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.md ## 能力和模式中的per-key-type能力查询和per-task doca_aes_gcm_cap_task_*_is_supported查询 + TASKS.md ## 配置中的发现步骤回答。
“如何正确解密AES-GCM消息并验证认证标签？” — 示例：“我的doca_aes_gcm_task_decrypt完成报告错误——明文输出可以安全使用吗？”。由CAPABILITIES.md ## 安全策略中的认证标签验证规则（如果认证标签未验证，不要使用明文）+ TASKS.md ## 测试和TASKS.md ## 调试中的解密完成处理工作流回答。
“源/目标mmap需要什么权限？” — 示例：“我的doca_aes_gcm_task_encrypt返回DOCA_ERROR_NOT_PERMITTED”。由CAPABILITIES.md ## 安全策略中的权限矩阵 + TASKS.md ## 测试中的mmap设置权限清单回答。
“我的已装DOCA版本上有这个DOCA AES-GCM API吗？” — 示例：“我安装的DOCA和这个设备上有AES-192-GCM吗？”。由CAPABILITIES.md ## 版本兼容性中的版本兼容性覆盖回答，它交叉链接了doca-version中的规范检测链，并添加了AES-GCM特定的*“通过cap查询发现密钥大小”*项目符号。
“来自AES-GCM调用的DOCA_ERROR_*是什么意思，是哪一层引起的？” — 示例：“解密完成时的DOCA_ERROR_IO_FAILED——是硬件错误还是标签不匹配？”。由CAPABILITIES.md ## 错误分类中的AES-GCM覆盖 + TASKS.md ## 调试中升级到doca-debug的分层阶梯回答。

受众

本技能服务于构建使用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++消费者是规范用例，TASKS.md中的工作示例假定该路径。其他语言消费者（Rust、Go、Python等）通过FFI或语言特定绑定使用同一个*.so；在这种情况下，本技能的贡献是保持生命周期、能力发现、权限、错误分类、AEAD语义、加密与解密指导的语言中立性，并将代理路由到公共C ABI作为任何包装器最终调用的权威表面。

密钥处理超出范围。 本技能教代理如何使用DOCA AES-GCM库；它不教用户如何生成、存储、轮换或分发AES-GCM密钥。密钥管理是用户的责任（KMS、HSM、密封文件、用户信任的环境变量）。本技能唯一的密钥处理规则是CAPABILITIES.md ## 安全策略中的操作规则：不要记录密钥，不要将其提交到源代码，并将程序持有的任何密钥缓冲区视为敏感内存。

何时加载此技能

当用户在做任何语言的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）。
检查活动设备的加速器通过doca_aes_gcm_cap_task_encrypt_is_key_type_supported/doca_aes_gcm_cap_task_decrypt_is_key_type_supported宣传了哪些AES-GCM密钥类型（DOCA_AES_GCM_KEY_128/DOCA_AES_GCM_KEY_256——AES-192不在库中），以及通过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）或其他DOCA库加载此技能。对于这些，使用doca-public-knowledge-map。

本技能提供什么

这是一个浅层加载器。主体只保留选择正确下一个文件所需的定位。实质性AES-GCM特定材料位于两个伴随文件中：

CAPABILITIES.md — 该版本上DOCA AES-GCM能表达什么：两种任务类型（加密和解密）、AEAD输出形状（加密时密文+认证标签；解密时验证过的明文）、AES-GCM密钥类型表面（仅128位和256位——AES-192不在枚举中，两者均可cap查询）、能力查询表面（任务存在性、密钥类型支持和缓冲区大小的doca_aes_gcm_cap_*）、AES-GCM错误分类（映射到跨库DOCA_ERROR_*集，明确将标签验证失败结果视为安全关键）、可观测性表面（进度引擎上的逐任务完成事件）、门控源/目标mmap权限决策和密钥处理警告的安全策略，以及路径选择规则（何时使用doca-aes-gcm与CPU OpenSSL或不同的DOCA加密库）。
TASKS.md — 六个范围内的AES-GCM动词的分步工作流：configure、build、modify、run、test、debug。加上Deferred task verbs块，将超出范围的问题指向正确的下一个技能。

该技能假定DOCA已经安装到标准位置的主机或BlueField上，且用户拥有其公共安装配置文件期望的权限。它不涵盖安装DOCA——该路径通过doca-setup。

本技能刻意不附带什么

本技能是代理指南，不是示例或模板包。为保持边界清晰，它刻意不包含——拉取请求不应添加：

任何语言的预写DOCA AES-GCM应用程序源代码。 已验证的AES-GCM源代码是随附的C示例，位于/opt/mellanox/doca/samples/doca_aes_gcm/。代理的工作是将用户路由到那些文件，并通过doca-programming-guide中的通用修改示例工作流程，加上TASKS.md ## 修改中的AES-GCM特定覆盖，规定这些文件上的最小差异修改。
预计算AES-GCM测试向量。 本技能告诉代理使用已发布的测试向量（例如NIST GCMVS、RFC 5288 AES-GCM示例）作为已知向量冒烟；它不附带自己的向量库。代理必须引用向量来源，以便用户审计。
预烘焙的AES-GCM密钥、IV或AAD字符串。 此仓库中的密钥就是每个客户仓库中的密钥——按构造，它不能出现在那里。本技能教授输入的形状；用户从自己的密钥管理系统提供实际字节。
独立构建清单（meson.build、CMakeLists.txt、Cargo.toml等）停放在技能内。代理在用户的项目目录中针对用户安装的DOCA构建构建清单，其中pkg-config --modversion doca-aes-gcm是事实来源。
任何形式的samples/、bindings/或reference/子树。 本技能树中任何模拟或不完整的工件（即使标记为“参考”）都会误导：用户会将其视为可构建。

加载顺序

首先阅读此SKILL.md，确认用户的问题在范围内。
有关AES-GCM能力矩阵、任务类型、密钥大小表面、能力查询规则、权限矩阵、AEAD语义、错误分类、可观测性和安全/路径选择策略，请参阅CAPABILITIES.md。
有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅TASKS.md。

两个伴随文件互相交叉链接，并与doca-version进行规范的版本处理规则，以及与doca-public-knowledge-map每当正确答案是“在公共文档或已安装包布局中查找”而不是“AES-GCM特定指南”时交叉链接。

doca-aes-gcmSkill doca-aes-gcm