UADK 快速入门

• UADK 快速入门
  • 概述
    • UADK
    • UADK engine
    • 使用场景
  • 使用要求
    • 硬件
    • 软件
      • 操作系统要求
      • 其他软件包要求
    • 工具链
  • 安装部署
    • UADK 安装部署
      • yum源安装
      • RPM包安装
      • 源码编译安装
    • 加载UACCE驱动
    • 加载厂商加速器驱动
    • 卸载厂商加速器驱动
    • UADK engine 安装部署
      • yum源安装
      • RPM包安装
      • 源码编译安装
  • 开始使用
    • 使用UADK
      • 开启环境变量
      • 性能测试
    • 使用UADK engine
      • 开启环境变量
      • 功能测试

概述

欢迎使用UADK 和 UADK engine。 本文档编写的目的是帮助用户快速开始使用UADK 和UADK engine。

UADK

UADK（User space Accelerator Development Kit，用户态加速器开发包）是采用SVA（Shared Virtual Address）技术的通用型用户态加速器框架，为用户提供了硬件加速计算密码学、压缩等算法的统一编程接口。UADK中包含UACCE（Unified/User-space-access-intended Accelerator Framework），能使不同厂商支持SVA技术的硬件加速器均可适配到UADK框架。

UADK框架包含UACCE、厂商驱动、抽象算法层。需要硬件加速器设备支持SVA，操作系统支持IOMMU和SVA。不同厂商的硬件加速器设备通过厂商自身的内核态驱动，在UACCE上注册成为不同的字符设备，使得用户能够在用户态通过字符设备操作来访问不同厂商的硬件加速器设备。UADK针对密码学、压缩等算法抽象出了算法层，该抽象算法层实现了通用的调用接口。目前主要支持以下算法：

• AES、SM4、DES、SM3、SHAx、MD5、AEAD、HMAC算法；
• RSA、DH算法；
• gzip、zlib算法；

当前已有鲲鹏（Kunpeng）硬件加速器设备注册到UACCE，并通过UADK框架，为用户提供了卸载CPU、使用硬件加速器计算密码学、压缩等算法的功能，达到了释放CPU算力、提升计算性能的目的。

UADK engine

UADK engine是UADK的一种上层应用，基于OpenSSL的engine机制开发。UADK engine提供通过OpenSSL命令行工具以及OpenSSL标准接口使用硬件加速器设备的功能，能够实现快速迁移现有业务。

UADK engine由RSA engine、DH engine、Cipher engine、Digest engine这4个子模块组成。不同厂商的硬件加速器设备，在注册到UADK框架之后，用户均能够通过UADK engine使用OpenSSL命令行工具或OpenSSL标准接口获得不同厂商的硬件加速计算功能。engine id统一为uadk_engine。UADK engine的组成模块和支持功能如下：

• RSA engine子模块，支持密钥生成、非对称加解密、数字签名。
• DH engine子模块，支持密钥协商。
• Cipher engine子模块，支持对称加解密。
• Digest engine子模块，支持生成消息摘要。

当前鲲鹏（Kunpeng）硬件加速器设备注册到UADK框架后，用户能使用OpenSSL命令行工具和OpenSSL标准接口通过UADK engine获得鲲鹏（Kunpeng）硬件加速器设备的相关功能。

使用场景

大数据、数据机密、智能安防、 Web服务、分布式存储等。

使用要求

本章节以鲲鹏（Kunpeng）硬件加速器设备为例，介绍UADK以及UADK engine的使用要求，其他厂商的硬件加速器设备使用要求类似。

硬件

已注册到UADK框架的鲲鹏（Kunpeng）9xx系列CPU 。

软件

操作系统要求

openEuler 22.03及以上版本。 操作系统要求内核支持IOMMU & SVA特性。

其他软件包要求

OpenSSL 1.1.1a及以上版本。

工具链

编译UADK 和UADK engine 依赖的编译器：

gcc version 10.2.0 (GCC)

安装部署

本章节以鲲鹏（Kunpeng）硬件加速器设备为例，介绍UADK以及UADK engine的安装、升级和卸载，其他厂商的硬件加速器设备类似。 需要鲲鹏（Kunpeng）加速器内核态驱动、UADK用户驱动态配合使用。请按照顺序进行安装。

UADK 安装部署

UADK抽象算法库安装部署方式有三种：yum源安装、RPM包安装以及源码编译安装。可根据实际情况，选择一种安装方式。

yum源安装

对于openEuler 22.03及以上版本的用户，可以直接用yum源安装，安装命令：

yum install libwd

RPM包安装

从openEuler社区获取UADK rpm包：https://gitee.com/src-openeuler/libwd

安装命令如下：

cd /usr/src/

git clone https://gitee.com/src-openeuler/libwd.git -b openEuler-22.03-LTS

mkdir -p /root/rpmbuild

cd /root/rpmbuild

mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS

cp /usr/src/libwd/libwd*.tar.gz /usr/src/libwd/*patch /root/rpmbuild/SOURCES/

cp /usr/src/libwd/warpdrive.spec /root/rpmbuild/SPECS/

rpmbuild --bb SPECS/warpdrive.spec

rpm -ivh /root/rpmbuild/RPMS/aarch64/libwd*.rpm

源码编译安装

从Linaro社区上获取到UADK源码：https://github.com/Linaro/uadk

详细源码编译、安装、配置步骤参见以下链接： https://github.com/Linaro/uadk/blame/master/INSTALL

加载UACCE驱动

在加载厂商的硬件加速器驱动前，需要先加载uacce.ko。

加载命令：modprobe uacce 或insmod /lib/modules/$(uname -r)/uacce.ko

加载厂商加速器驱动

以鲲鹏（Kunpeng）硬件加速器的驱动加载为例。

说明：加载 hisi_hpre.ko/hisi_zip.ko/hisi_sec2.ko时可以指定uacce_mode，uacce_mode默认值为0。uacce_mode=0为使能内核态，uacce_mode=1为使能用户态SVA模式，uacce_mode=2为使能用户态no-SVA模式。 鲲鹏（Kunpeng）加速器用户态驱动依赖uacce框架（内核态不依赖），因此需要先加载uacce.ko。鲲鹏（Kunpeng）硬件加速器的ZIP、HPRE、SEC模块依赖QM队列管理，因此加载uacce.ko之后需要加载hisi_qm.ko，然后加载ZIP、HPRE、SEC模块的驱动。

可以使用insmod或modprobe工具加载驱动。

modprobe工具加载方式：

• 加载HPRE模块驱动用户态SVA模式的命令：

  modprobe hisi_hpre uacce_mode=1
  

• 加载SEC模块驱动用户态SVA模式的命令：

  modprobe hisi_sec2 uacce_mode=1
  

• 加载ZIP模块驱动用户态SVA模式的命令：

  modprobe hisi_zip uacce_mode=1
  

insmod工具加载方式：

• 加载HPRE模块驱动用户态SVA模式的命令：

  insmod /lib/modules/$(uname -r)/uacce.ko
  insmod /lib/modules/$(uname -r)/hisi_qm.ko
  insmod /lib/modules/$(uname -r)/hisi_hpre.ko uacce_mode=1
  

• 加载SEC模块驱动用户态SVA模式的命令：

  insmod /lib/modules/$(uname -r)/uacce.ko
  insmod /lib/modules/$(uname -r)/hisi_qm.ko
  insmod /lib/modules/$(uname -r)/hisi_sec2.ko uacce_mode=1
  

• 加载ZIP模块驱动用户态SVA模式的命令：

  insmod /lib/modules/$(uname -r)/uacce.ko
  insmod /lib/modules/$(uname -r)/hisi_qm.ko
  insmod /lib/modules/$(uname -r)/hisi_zip.ko uacce_mode=1
  

模块参数配置说明：

在加载驱动时，可以进行模块参数配置，参数没有先后顺序要求。在配置模块参数加载驱动后，可以通过cat /sys/bus/pci/drivers/<driver>/module/parameters/ 来查询模块参数。模块参数在加载驱动后不支持更新；如果需要更改模块参数，需要先卸载驱动，在重新加载驱动时设置新的模块参数。

• 模块参数配置命令格式：

  insmod <driver> [uacce_mode] [pf_q_num] [vfs_num] [sgl_sge_nr] [ctx_q_num]
  

  modprobe <driver_name> [uacce_mode] [pf_q_num] [vfs_num] [sgl_sge_nr] [ctx_q_num]
  

  • []中的参数为可选项，均有默认值，无顺序要求。

  • 所有模块uacce_mode默认值为0，表示不支持用户态，因此对于用户态的用户来说，需要配置uacce_mode=1。

  • SEC模块pf_q_num的默认值为256；HPRE/ZIP模块pf_q_num的默认值为64。

  • 所有模块vfs_num的默认值为0。

  • 所有模块sgl_sge_nr的默认值为10。

  • 所有模块ctx_q_num的默认值为2。

    例如，加载ZIP驱动时，如果不使用默认值，手动参数配置命令如下：

    insmod /lib/modules/$(uname -r)/hisi_zip.ko uacce_mode=1 pf_q_num =16 vfs_num=1 sgl_sge_nr=16
    

  • 初次仅需要使用SVA特性时，配置uacce_mode=1即可。

卸载厂商加速器驱动

以鲲鹏（Kunpeng）硬件加速器驱动卸载为例。卸载命令：

modprobe -r hisi_hpre

或者

rmmod hisi_hpre

UADK engine 安装部署

UADK engine安装部署方式有三种：yum源安装、RPM包安装以及源码编译安装。可根据实际情况，选择一种安装方式。

yum源安装

对于openEuler 22.03用户，可以直接用yum源安装，安装命令：

yum install uadk_engine

RPM包安装

从openEuler社区获取uadk_engine rpm包：https://gitee.com/src-openeuler/uadk_engine

安装命令如下：

cd /usr/src/

git clone https://gitee.com/src-openeuler/uadk_engine.git

mkdir -p /root/rpmbuild

cd /root/rpmbuild

mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS

cp /usr/src/uadk_engine/uadk_engine*.tar.gz /usr/src/uadk_engine/*patch /root/rpmbuild/SOURCES/

cp /usr/src/uadk_engine/uadk_engine.spec /root/rpmbuild/SPECS/

rpmbuild --bb SPECS/uadk_engine.spec

rpm -ivh /root/rpmbuild/RPMS/aarch64/uadk_engine*.rpm --prefix=/usr/local/openssl/lib/engines-1.1

源码编译安装

可以从Linaro社区获取到UADK engine源码：https://github.com/Linaro/uadk_engine

详细源码编译安装步骤参见以下链接： https://github.com/Linaro/uadk_engine/blob/master/README

开始使用

使用UADK

UADK提供了性能测试工具，编译安装UADK后会生成一个名为uadk_tool的工具，可以通过uadk_tool benchmark --help查看性能测试工具使用方法及参数说明。

开启环境变量

使用export命令设置队列数量：

export WD_RSA_CTX_NUM="sync:2@0,async:4@0"
export WD_DH_CTX_NUM="sync:2@0,async:4@0"
export WD_CIPHER_CTX_NUM="sync:2@2,async:4@2"
export WD_DIGEST_CTX_NUM="sync:2@2,async:4@2"

环境变量的入参格式为ctx_mode:ctx_num@node，表示在索引号为node的numa节点上设置ctx_num个ctx_mode模式的队列。 例如，"sync:2@0,async:4@0"表示，在numa 0节点上设置2个sync模式的队列和4个async模式的队列。

性能测试

• MD5性能测试

  测试md5在SVA模式计算摘要的性能：

  uadk_tool benchmark --alg md5 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
  

• SM3性能测试

  测试sm3在SVA模式计算摘要的性能：

  uadk_tool benchmark --alg sm3 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
  

• SHA性能测试

  测试sha-512在SVA模式计算摘要的性能：

  uadk_tool benchmark --alg sha-512 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
  

• AES性能

  测试aes-128-cbc在SVA模式进行加密的性能：

  uadk_tool benchmark --alg aes-128-cbc --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

  测试aes-128-cbc在SVA模式进行解密的性能：

  uadk_tool benchmark --alg aes-128-cbc --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

• SM4性能测试

  测试sm4-128-ecb在SVA模式进行加密的性能：

  uadk_tool benchmark --alg sm4-128-ecb --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

  测试sm4-128-ecb在SVA模式进行解密的性能：

  uadk_tool benchmark --alg sm4-128-ecb --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

• DES性能测试

  测试3des-128-ecb在SVA模式进行加密的性能：

  uadk_tool benchmark --alg 3des-128-ecb --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

  测试3des-128-ecb在SVA模式进行解密的性能：

  uadk_tool benchmark --alg 3des-128-ecb --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
  

其他测试场景，可以使用uadk_tool benchmark --help查看参数和配置说明。

使用UADK engine

可以通过openssl命令行工具直接调用uadk engine。可以通过各个openssl工具的帮助菜单查看使用方式。

4.2.1 开启环境变量

UADK engine支持环境变量配置功能，能够根据需要设置执行任务的队列数量，需要进行以下配置：

1. 修改openssl.cnf文件（一般在/usr/local/ssl/路径下），将以下内容添加到配置文件的开头

   openssl_cnf=openssl_def
   [openssl_def]
   engines=engine_section
   [engine_section]
   uadk_engine=uadk_section
   [uadk_section]
   UADK_CMD_ENABLE_RSA_ENV=1
   UADK_CMD_ENABLE_DH_ENV=1
   UADK_CMD_ENABLE_CIPHER_ENV=1
   UADK_CMD_ENABLE_DIGEST_ENV=1
   

2. 使用export命令设置队列数量

   export WD_RSA_CTX_NUM="sync:2@0,async:4@0"
   export WD_DH_CTX_NUM="sync:2@0,async:4@0"
   export WD_CIPHER_CTX_NUM="sync:2@2,async:4@2"
   export WD_DIGEST_CTX_NUM="sync:2@2,async:4@2"
   

   环境变量的入参格式为ctx_mode:ctx_num@node，表示在索引号为node的numa节点上设置ctx_num个ctx_mode模式的队列。 例如，"sync:2@0,async:4@0"表示，在numa 0节点上设置2个sync模式的队列和4个async模式的队列。

功能测试

• RSA功能测试

  生成私钥：

  openssl genrsa -out prikey.pem -engine uadk_engine 1024
  

  获取公钥：

  openssl rsa -in prikey.pem -pubout -out pubkey.pem -engine uadk_engine
  

  假设需要加密的文件为plain.txt：

  echo "Content to be encrypted" > plain.txt
  

  加密：

  openssl rsautl -encrypt -in plain.txt -inkey pubkey.pem -pubin -out enc.txt -engine uadk_engine
  

  解密：

  openssl rsautl -decrypt -in enc.txt -inkey prikey.pem -out dec.txt -engine uadk_engine
  

  假设需要签名的文件为msg.txt：

  echo "Content to be signed" > msg.txt
  

  签名：

  openssl rsautl -sign -in msg.txt -inkey prikey.pem -out signed.txt -engine uadk_engine
  

  验签：

  openssl rsautl -verify -in signed.txt -inkey pubkey.pem -pubin -out verified.txt -engine uadk_engine
  

  使用openssl speed工具测试：

  openssl speed -elapsed -engine uadk_engine rsa1024
  openssl speed -elapsed -engine uadk_engine -async_jobs 10 rsa1024
  openssl speed -elapsed -engine uadk_engine -async_jobs 36 rsa1024
  

• DH功能测试

  生成全局公钥参数：

  openssl dhparam -out dhparam.pem 768
  

  生成Alice私钥：

  openssl genpkey -paramfile dhparam.pem -out alice_prikey.pem -engine uadk_engine
  

  获取Alice公钥：

  openssl pkey -in alice_prikey.pem -pubout -out alice_pubkey.pem
  

  生成Bob私钥：

  openssl genpkey -paramfile dhparam.pem -out bob_prikey.pem -engine uadk_engine
  

  获取Bob公钥：

  openssl pkey -in bob_prikey.pem -pubout -out bob_pubkey.pem
  

  交换公钥，各自生成协商出的密钥：

  openssl pkeyutl -derive -inkey alice_prikey.pem -peerkey bob_pubkey.pem -out secret1.bin -engine uadk_engine
  openssl pkeyutl -derive -inkey bob_prikey.pem -peerkey alice_pubkey.pem -out secret2.bin -engine uadk_engine
  

  对比协商出的共享密钥：

  cmp secret1.bin secret2.bin
  xxd secret1.bin
  xxd secret2.bin
  

• MD5功能测试：

  假设需要计算摘要的文件为data.txt：

  echo "Content to be hashed" > data.txt
  

  计算摘要：

  openssl md5 -engine uadk_engine data.txt
  

  openssl speed工具测试：

  openssl speed -engine uadk_engine -async_jobs 1 -evp md5
  

• SM3功能测试

  假设需要计算摘要的文件为data.txt：

  echo "Content to be hashed" > data.txt
  

  计算摘要：

  openssl sm3 -engine uadk_engine data.txt
  

• SHA功能测试

  假设需要计算摘要的文件为data.txt：

  echo "Content to be hashed" > data.txt
  

  计算摘要：

  openssl sha1 -engine uadk_engine data.txt
  openssl sha256 -engine uadk_engine data.txt
  openssl sha512 -engine uadk_engine data.txt
  

• AES功能测试

  假设需要加密的文件为data.txt：

  echo "Content to be encrypted" > data
  

  aes-128-cbc模式加密：

  openssl enc -aes-128-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-128-cbc模式解密：

  openssl enc -aes-128-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-192-cbc模式加密：

  openssl enc -aes-192-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-192-cbc模式解密：

  openssl enc -aes-192-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-256-cbc模式加密：

  openssl enc -aes-256-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-256-cbc模式解密：

  openssl enc -aes-256-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  aes-128-ecb模式加密：

  openssl enc -aes-128-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-128-ecb模式解密：

  openssl enc -aes-128-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-192-ecb模式加密：

  openssl enc -aes-192-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-192-ecb模式解密：

  openssl enc -aes-192-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-256-ecb模式加密：

  openssl enc -aes-256-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-256-ecb模式解密：

  openssl enc -aes-256-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-128-ctr模式加密：

  openssl enc -aes-128-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-128-ctr模式解密：

  openssl enc -aes-128-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-192-ctr模式加密：

  openssl enc -aes-192-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-192-ctr模式解密：

  openssl enc -aes-192-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-256-ctr模式加密：

  openssl enc -aes-256-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
  

  aes-256-ctr模式解密：

  openssl enc -aes-256-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
  

• SM4功能测试

  sm4-cbc模式加密：

  openssl enc -sm4-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  sm4-cbc模式解密：

  openssl enc -sm4-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  sm4-ecb模式加密：

  openssl enc -sm4-ecb -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  sm4-ecb模式解密：

  openssl enc -sm4-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

• DES功能测试

  des-ede3-cbc模式加密：

  openssl enc -des-ede3-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  des-ede3-cbc模式解密：

  openssl enc -des-ede3-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  des-ede3-ecb模式加密：

  openssl enc -des-ede3-ecb -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
  

  des-ede3-ecb模式解密：

  openssl enc -des-ede3-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p