DOCA SHA

本指南提供有关构建和开发使用 SHA1、SHA2-256 或 SHA2-512 算法计算消息摘要的应用程序的说明。

该库提供了一个 API，用于在 DOCA 缓冲区上执行 SHA 操作，其中缓冲区可以驻留在本地内存（即，在同一主机内）或 NVIDIA® BlueField®-2 设备可访问的主机内存（远程内存）中。使用 DOCA SHA，可以以优化的硬件加速方式轻松执行复杂的加密哈希运算。

本文档适用于希望加速其应用程序的 SHA 计算的软件开发人员，这些计算通常用于数字签名方案或基于哈希的消息身份验证代码计算。

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

• DOCA Core 执行模型

• DOCA Core 设备

• DOCA Core 内存子系统

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

仅当 DPU 配置为 DPU 模式时，才能运行从主机到 BlueField 以及反之亦然的 DOCA SHA 计算。

DOCA SHA 是一个 DOCA Core 上下文。此库利用 DOCA Core 架构来公开卸载到硬件的异步任务/事件。

SHA 可用于计算消息摘要，如下图所示

• 从本地内存到本地内存的 SHA

  

• 使用 DPU 使用主机和 DPU 之间的内存执行 SHA

  

• 使用主机使用主机和 DPU 之间的内存执行 SHA 计算

  

对象

设备和表示符

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

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

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

内存缓冲区

SHA 任务至少需要两个 DOCA 缓冲区，分别包含目标和源。

目标始终是单个 doca_buf。源可以是单个 doca_buf 或 doca_buf 的 linked_list。所有目标和源 doca_buf 都可以从 doca_buf_inventory 分配。

在 SHA 操作期间，不得修改或读取缓冲区。有关支持何种内存的信息，请参阅“缓冲区支持”部分中的表。

要开始使用该库，用户必须完成配置阶段，如 DOCA Core 上下文配置阶段 中所述。

本节介绍如何配置和启动上下文，以允许执行任务和检索事件。

配置

可以配置上下文以匹配应用程序用例。

要查找是否支持配置或其最小/最大值，请参阅“设备支持”部分。

强制配置

在尝试启动上下文之前，应用程序必须设置这些配置

• 必须至少配置一个任务/事件类型。有关任务和/或事件的配置，请分别参阅“任务”和“事件”部分。

• 创建时必须提供具有适当支持的设备

设备支持

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

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

• doca_sha_cap_task_hash_get_supported

• doca_sha_cap_task_partial_hash_get_supported

某些设备可能允许不同的功能，例如

• 最大任务数

• 最大源缓冲区大小

• 最小目标缓冲区大小

• DOCA 链表缓冲区中支持的最大元素数

• 检查是否支持 SHA1、SHA2-256 或 SHA2-512

缓冲区支持

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

本节介绍如何使用 DOCA Core 进度引擎 在 CPU 上执行。

任务

DOCA SHA 公开异步任务，这些任务根据 DOCA Core 架构利用 DPU 硬件。

SHA 任务

SHA 任务 doca_sha_task_hash 允许使用 “缓冲区支持” 部分中描述的缓冲区进行一次性 SHA 计算。一次性意味着源缓冲区用作整体输入，因此，SHA 操作在此任务完成事件到达后完成。

任务配置

任务输入

如 DOCA Core 任务 中所述的通用输入。

任务输出

如 DOCA Core 任务 中所述的通用输出。

任务完成成功

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

• 源缓冲区中数据的 SHA 计算已成功完成，结果已写入目标缓冲区

• 目标缓冲区数据段已扩展以包含 SHA 结果数据

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未修改

• 目标缓冲区内容可能会被修改

任务限制

• 操作不是原子的

• 提交任务后，不应读取/写入源和目标

• 其他限制在 DOCA Core 任务 中描述

Partial-SHA 任务

partial-SHA 任务 doca_sha_task_partial_hash 允许为消息集合进行有状态 SHA 计算。使用 “缓冲区支持” 部分中描述的缓冲区。

有状态意味着输入数据由许多段组成（可能是空间或时间上不连续的），因此，其 SHA 计算需要多次一次性 SHA 操作才能完成。在任何有状态操作期间，也可以执行其他独立的 SHA 任务。

任务配置

任务输入

如 DOCA Core 任务 中所述的通用输入。

任务输出

如 DOCA Core 任务 中所述的通用输出。

任务完成成功

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

• 源缓冲区中数据的 SHA 计算已成功完成，结果已写入目标缓冲区

• 目标缓冲区数据段已扩展以包含 SHA 结果数据

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未修改

• 目标缓冲区内容可能会被修改

任务限制

• 操作不是原子的

• 提交任务后，不应读取/写入源和目标

• 其他限制在 DOCA Core 任务 中描述

事件

DOCA SHA 公开异步事件，以根据 DOCA Core 架构通知意外发生的更改。

SHA 公开的唯一事件是 DOCA Core 事件 中描述的通用事件。

DOCA SHA 库遵循 DOCA Core 上下文状态机 中描述的上下文状态机。

以下部分描述了移动状态以及每个状态允许的操作。

空闲

在此状态下，应用程序应执行以下操作之一

• 销毁上下文

• 启动上下文

允许的操作

• 根据 “配置” 部分配置上下文

• 启动上下文

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

启动中

无法达到此状态。

运行中

在此状态下，应用程序应

• 分配和提交任务

• 调用 progress 以完成任务和/或接收事件

允许的操作

• 分配先前配置的任务

• 提交任务

• 调用 stop

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

停止中

在此状态下，应用程序应

• 调用 progress 以完成所有正在进行的任务（任务完成失败）

• 释放任何已完成的任务

允许的操作

• 调用 progress

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

DOCA SHA 仅支持 CPU 上的数据路径。请参阅 “执行阶段” 部分。

本节介绍基于 DOCA SHA 库的 DOCA SHA 示例。

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

• 对缓冲区内容执行 SHA 计算，并将结果写入另一个缓冲区

• 将缓冲区的内容切分为段集合，并对此段集合执行 partial-SHA 计算，然后将结果写入另一个缓冲区

运行示例

1. 请参阅以下文档

   • DOCA Linux 安装指南，了解如何安装与 BlueField 相关的软件的详细信息。

   • DOCA 故障排除，了解您在 DOCA 示例的安装、编译或执行中可能遇到的任何问题。

2. 要构建给定的示例

   复制

   已复制！

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

   信息

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

3. 示例（例如，doca_sha_create）用法

   复制

   已复制！

               
   
               
   Usage: doca_sha_create [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:
     -d, --data                        user data
           

4. 有关每个示例的其他信息，请使用 -h 选项

   复制

   已复制！

               
   
               
   /tmp/build/doca_<sample_name>-h
           

示例

SHA 创建

此示例说明了如何使用 DOCA SHA 执行 SHA 计算。

示例逻辑包括

1. 查找 DOCA 设备。

2. 初始化所需的 DOCA Core 结构。

3. 为 doca_sha_task_hash 设置 task_pool 配置。

4. 使用两个相关缓冲区填充 DOCA 内存映射。

5. 为每个缓冲区分配 DOCA 缓冲区库存中的元素。

6. 分配和初始化 doca_sha_task_hash。

7. 提交任务。

8. 在任务完成后检索任务结果。

参考

• /opt/mellanox/doca/samples/doca_sha/sha_create/sha_create_sample.c

• /opt/mellanox/doca/samples/doca_sha/sha_create/sha_create_main.c

• /opt/mellanox/doca/samples/doca_sha/sha_create/meson.build

SHA-Partial 创建

此示例说明了如何使用 DOCA SHA 为数据段集合执行 partial-SHA 计算。

示例逻辑包括

1. 查找 DOCA 设备。

2. 初始化所需的 DOCA Core 结构。

3. 为 doca_sha_task_partial_hash 设置 task_pool 配置。

4. 根据选定的 SHA 算法的块大小，将源数据切分为数据段集合

5. 使用所有源数据段和目标所需的缓冲区填充 DOCA 内存映射。

6. 为第一个源缓冲区和目标缓冲区分配 DOCA 缓冲区库存中的元素。

7. 使用第一个源缓冲区和目标缓冲区分配和初始化 doca_sha_task_partial_hash。

8. 迭代重复以下子步骤，直到所有数据段都被消耗

   1. 提交 doca_sha_task_partial_hash。

   2. 等待提交的任务完成。

   3. 为下一个源段分配 doca_buf，并使用 doca_sha_task_partial_hash_set_src 将其设置为上述分配任务的源缓冲区。

   4. 如果是最后一个段，请使用 doca_sha_task_partial_hash_set_is_final_buf 在分配的任务中标记它。

9. 在目标缓冲区中检索最终迭代的结果，作为完整的 partial-SHA 计算结果。

10. 销毁所有 SHA 和 DOCA Core 结构。

参考

• /opt/mellanox/doca/samples/doca_sha/sha_partial_create/sha_partial_create_sample.c

• /opt/mellanox/doca/samples/doca_sha/sha_partial_create/sha_partial_create_main.c

• /opt/mellanox/doca/samples/doca_sha/sha_partial_create/meson.build