DOCA AES-GCM - NVIDIA 文档

本指南提供了关于构建和开发需要使用 AES-GCM 算法进行数据加密和解密的应用程序的说明。

简介

注意

DOCA AES-GCM 库在 Alpha 级别和 NVIDIA® BlueField®-3 设备或更高版本上受支持。

该库提供了一个 API，用于在 DOCA 缓冲区上执行 AES-GCM 操作，其中缓冲区位于本地内存（即，在同一主机内）或 DPU 可访问的主机内存（远程内存）中。使用 DOCA AES-GCM，可以以优化的硬件加速方式轻松执行复杂的加密/解密操作。

本文档适用于希望加速其应用程序的加密/解密操作的软件开发人员。

先决条件

此库遵循 DOCA Core 上下文的架构，建议在阅读以下章节之前先阅读：

先前版本的变更

2.9.0 版本中的变更

不适用

环境

基于 DOCA AES-GCM 的应用程序可以在主机或 DPU 目标机上运行。

仅当 DPU 配置为DPU 模式时，才能运行从主机到 DPU 以及反之亦然的加密/解密。

架构

DOCA AES-GCM 是一个 DOCA Core 上下文。此库利用 DOCA Core 架构来公开异步任务/事件，这些任务/事件被卸载到硬件。

AES-GCM 可用于加密/解密数据，如下图所示

从本地内存到本地内存的加密/解密
使用 DPU 在主机和 DPU 之间复制内存
使用主机在主机和 DPU 之间复制内存

对象

设备和表示器

该库需要 DOCA 设备才能运行。该设备用于访问内存并执行实际的加密/解密。请参阅DOCA Core 设备发现。

对于同一个 BlueField DPU，使用哪个设备（即 PF/VF/SF）无关紧要，因为所有这些设备都使用相同的硬件组件。如果有多个 DPU，则可以为每个 DPU 创建一个 AES-GCM 实例，并为每个实例提供来自不同 DPU 的设备。

为了访问非本地内存（即从主机到 DPU 或反之亦然），应用程序的 DPU 端必须选择具有适当表示器的设备（请参阅DOCA Core 设备表示器发现）。只要 AES-GCM 实例未被销毁，该设备就必须保持有效。

内存缓冲区

加密/解密任务需要两个 DOCA 缓冲区，分别包含目标和源。

根据缓冲区的分配模式，请考虑 DOCA Core 库存类型表。

要查找支持哪种类型的内存，请参阅缓冲区支持表。

注意

在加密/解密操作期间，不得修改或读取缓冲区。

必须至少配置一个任务/事件类型。请参阅任务和/或事件的配置。
创建时必须提供具有适当支持的设备

设备支持

DOCA AES-GCM 需要设备才能运行。有关选择设备的信息，请参阅DOCA Core 设备发现。

由于设备功能将来可能会发生变化（请参阅DOCA Core 设备支持），建议使用以下方法选择您的设备

doca_aes_gcm_cap_task_encrypt_is_supported
doca_aes_gcm_cap_task_decrypt_is_supported

某些设备可以支持以下不同的功能

最大任务数
最大缓冲区大小
DOCA 链表缓冲区中支持的最大元素数
最大初始化向量长度
检查是否支持 96 位大小的身份验证标签
检查是否支持 128 位大小的身份验证标签
检查是否支持给定的 AES-GCM 密钥类型

缓冲区支持

任务支持具有以下功能的缓冲区

缓冲区类型	源缓冲区	目标缓冲区
本地 mmap 缓冲区	是	是
来自 PCIe 导出的 mmap 缓冲区	是	是
来自 RDMA 导出的 mmap 缓冲区	否	否
链表缓冲区	是	否

描述	用于设置配置的 API	用于查询支持的 API
启用任务	`doca_aes_gcm_task_encrypt_set_conf`	`doca_aes_gcm_cap_task_encrypt_is_supported`
任务数	`doca_aes_gcm_task_encrypt_set_conf`	`doca_aes_gcm_cap_get_max_num_tasks`
最大缓冲区大小	–	`doca_aes_gcm_cap_task_encrypt_get_max_buf_size`
最大缓冲区列表大小	–	`doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem`
最大初始化向量长度	–	`doca_aes_gcm_cap_task_encrypt_get_max_iv_length`
启用身份验证标签大小	–	`doca_aes_gcm_cap_task_encrypt_is_tag_96_supported` `doca_aes_gcm_cap_task_encrypt_is_tag_128_supported`
启用密钥类型	–	`doca_aes_gcm_cap_task_encrypt_is_key_type_supported`

任务输入

与 DOCA Core 任务中所述的通用输入相同

名称	描述	注释
源缓冲区	指向要加密的内存的缓冲区	仅加密数据段中驻留的数据
目标缓冲区	指向内存加密到何处的缓冲区	加密数据将附加到尾段
密钥	用于加密数据的密钥	由函数 `doca_aes_gcm_key_create` 创建用户应使用相同的密钥来加密和解密数据
初始化向量 (IV)	AES-GCM 算法要使用的初始化向量	用户应使用相同的 IV 来加密和解密数据
初始化向量长度	AES-GCM 算法必须提供的初始化向量长度	以字节表示，支持 0B-12B 值
身份验证标签大小	AES-GCM 算法要提供的身份验证标签大小。标签将自动计算并附加到结果缓冲区。	以字节表示，仅支持 12B 和 16B 值
附加身份验证数据大小	AES-GCM 算法要提供的附加身份验证数据大小。此数据应位于源缓冲区的开头，将不会被加密，但会进行身份验证。	以字节表示

任务输出

与 DOCA Core 任务中所述的通用输出相同。

任务完成成功

任务成功完成后，将发生以下情况

源缓冲区中的数据将被加密并写入目标缓冲区
目标缓冲区数据段将扩展以包含加密数据

任务完成失败

如果任务中途失败

如果发生致命错误，上下文可能会进入停止状态
源和目标 doca_buf 对象未被修改
目标缓冲区内容可能会被修改

任务限制

该操作不是原子性的
提交任务后，不应读取/写入源和目标
其他限制在 DOCA Core 任务中描述

解密任务

解密任务允许数据解密。使用缓冲区支持中描述的缓冲区。

任务配置

描述	用于设置配置的 API	用于查询支持的 API
启用任务	`doca_aes_gcm_task_decrypt_set_conf`	`doca_aes_gcm_cap_task_decrypt_is_supported`
任务数	`doca_aes_gcm_task_decrypt_set_conf`	`doca_aes_gcm_cap_get_max_num_tasks`
最大缓冲区大小	–	`doca_aes_gcm_cap_task_decrypt_get_max_buf_size`
最大缓冲区列表大小	–	`doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem`
最大初始化向量长度	–	`doca_aes_gcm_cap_task_decrypt_get_max_iv_length`
启用身份验证标签大小	–	`doca_aes_gcm_cap_task_decrypt_is_tag_96_supported` `doca_aes_gcm_cap_task_decrypt_is_tag_128_supported`
启用密钥类型	–	`doca_aes_gcm_cap_task_decrypt_is_key_type_supported`

任务输入

与 DOCA Core 任务中所述的通用输入相同。

名称	描述	注释
源缓冲区	指向要解密的内存的缓冲区	仅解密数据段中驻留的数据
目标缓冲区	指向内存解密到何处的缓冲区	解密数据将附加到尾段，从而扩展数据段
密钥	用于解密数据的密钥	由函数 `doca_aes_gcm_key_create` 创建用户应使用相同的密钥来加密和解密数据
初始化向量 (IV)	AES-GCM 算法要使用的初始化向量	用户应使用相同的 IV 来加密和解密数据
初始化向量长度	AES-GCM 算法必须提供的初始化向量长度	以字节表示，支持 0B-12B 值
身份验证标签大小	AES-GCM 算法要提供的身份验证标签大小。源缓冲区末尾存在的标签将被验证，并且不会出现在目标缓冲区中。	以字节表示，仅支持 12B 和 16B 值
附加身份验证数据大小	AES-GCM 算法要提供的附加身份验证数据大小。此数据位于源缓冲区的开头，不会被加密，但会进行身份验证。	以字节表示

任务输出

与 DOCA Core 任务中所述的通用输出相同。

任务完成成功

任务成功完成后，将发生以下情况

源缓冲区中的数据将被解密并写入目标缓冲区
目标缓冲区数据段将扩展以包含解密数据

任务完成失败

如果任务中途失败

如果发生致命错误，上下文可能会进入停止状态
源和目标 doca_buf 对象未被修改
目标缓冲区内容可能会被修改

任务限制

该操作不是原子性的
提交任务后，不应读取/写入源和目标
其他限制在 DOCA Core 任务中描述

销毁上下文
启动上下文

允许的操作

根据配置配置上下文
启动上下文

可以通过以下方式达到此状态

先前状态	转换操作
无	创建上下文
运行中	在确保所有任务都已释放后调用停止
停止中	调用进度，直到所有任务都已完成并释放

启动中

无法达到此状态。

运行中

在此状态下，应用程序应

分配和提交任务
调用进度以完成任务和/或接收事件

允许的操作

分配先前配置的任务
提交任务
调用停止

可以通过以下方式达到此状态

先前状态	转换操作
空闲	配置后调用启动

停止中

在此状态下，应用程序应

调用进度以完成所有未完成的任务（任务完成失败）
释放任何已完成的任务

允许的操作

调用进度

可以通过以下方式达到此状态

先前状态	转换操作
运行中	调用进度并且发生致命错误
运行中	在未释放所有任务的情况下调用停止

替代数据路径选项

DOCA AES-GCM 仅支持 CPU 上的数据路径。请参阅执行阶段。

DOCA AES-GCM 示例

本节介绍基于 DOCA AES-GCM 库的 DOCA AES-GCM 示例。

本节中的示例说明了如何使用 DOCA AES-GCM API 执行以下操作

将缓冲区的内容加密到另一个缓冲区
将缓冲区的内容解密到另一个缓冲区

信息

本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议管辖。

运行示例

请参阅以下文档
- DOCA Linux 安装指南，了解如何安装 BlueField 相关软件的详细信息。
- DOCA 故障排除，了解您在安装、编译或执行 DOCA 示例时可能遇到的任何问题。

要构建给定的示例

复制
已复制！

            
            cd /opt/mellanox/doca/samples/doca_aes_gcm/<sample_name>
meson/tmp/build
ninja -C/tmp/build

信息

二进制文件 doca_<sample_name> 在 /tmp/build/ 下创建。

示例（例如，doca_aes_gcm_encrypt）用法

复制
已复制！

            
            Usage: doca_aes_gcm_encrypt [DOCA Flags] [Program Flags]
 
DOCA Flags:
  -h, --help                        Print a help synopsis
  -v, --version                     Print program version information
  -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  -j, --json <path>                 Parse all command flags from an input json file
 
Program Flags:
  -p, --pci-addr                    DOCA device PCI device address - default: 03:00.0
  -f, --file                        Input file to encrypt/decrypt
  -o, --output                      Output file - default: /tmp/out.txt
  -k, --key                         Raw key to encrypt/decrypt with, represented in hex format (32 characters for 128-bit key, and 64 for 256-bit key) - default: 256-bit key, equals to zero
  -i, --iv                          Initialization vector, represented in hex format (0-24 characters for 0-96-bit IV) - default: 96-bit IV, equals to zero
  -t, --tag size                    Authentication tag size. Tag size is in bytes and can be 12B or 16B - default: 12
  -a, --aad size                    Additional authenticated data size - default: 0

有关每个示例的更多信息，请使用 -h 选项

复制
已复制！

            
            /tmp/build/doca_<sample_name>-h

示例

AES-GCM 加密

本示例说明了如何使用 AES-GCM 加密数据。

示例逻辑包括

定位 DOCA 设备。
初始化所需的 DOCA Core 结构。
设置 AES-GCM 加密任务配置。
使用两个相关缓冲区填充 DOCA 内存映射。
为每个缓冲区在 DOCA 缓冲区库存中分配元素。
创建 DOCA AES-GCM 密钥。
分配和初始化 AES-GCM 加密任务。
提交 AES-GCM 加密任务。
检索 AES-GCM 加密任务（一旦完成）。
检查任务结果。
销毁所有 AES-GCM 和 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/aes_gcm_encrypt_sample.c
/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/aes_gcm_encrypt_main.c
/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/meson.build

AES-GCM 解密

本示例说明了如何使用 AES-GCM 解密数据。

示例逻辑包括

定位 DOCA 设备。
初始化所需的 DOCA Core 结构。
设置 AES-GCM 解密任务配置。
使用两个相关缓冲区填充 DOCA 内存映射。
为每个缓冲区在 DOCA 缓冲区库存中分配元素。
创建 DOCA AES-GCM 密钥。
分配和初始化 AES-GCM 解密任务。
提交 AES-GCM 解密任务。
检索 AES-GCM 解密任务（一旦完成）。
检查任务结果。
销毁所有 AES-GCM 和 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/aes_gcm_decrypt_sample.c
/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/aes_gcm_decrypt_main.c
/opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/meson.build

本页内容