UADK Quick Start Guide
- UADK Quick Start Guide
Overview
This chapter describes how to quickly start using UADK and the UADK engine.
UADK
UADK is a general-purpose user space accelerator framework that uses shared virtual addressing (SVA) to provide a unified programming interface for hardware acceleration of cryptographic and compression algorithms. UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE), which enables hardware accelerators from different vendors that support SVA to adapt to UADK.
UADK consists of UACCE, vendors' drivers, and an algorithm layer. UADK requires the hardware accelerator to support SVA, and the operating system to support IOMMU and SVA. Hardware accelerators from different vendors are registered as different character devices with UACCE by using kernel-mode drivers of the vendors. A user can access the hardware accelerators by performing user-mode operations on the character devices. UADK provides an algorithm layer for invoking the cryptographic and compression algorithms in a unified manner. Currently, UADK supports the following algorithms:
- AES, SM4, DES, SM3, SHAx, MD5, AEAD and HMAC
- RSA and DH
- gzip and zlib
Currently, Kunpeng hardware accelerators have been registered with UACCE. Through the UADK framework, users can run cryptographic and compression algorithms using hardware accelerators instead of CPUs, freeing up CPU computing power and improving computing performance.
UADK Engine
The UADK engine is an upper-layer application of UADK developed based on the OpenSSL engine mechanism. The UADK engine provides the function of using hardware accelerators through the OpenSSL command line tools and OpenSSL standard interface to quickly migrate existing services.
The UADK engine consists of five sub-modules: RSA engine, DH engine, ECC engine, Cipher engine, and Digest engine. After hardware accelerators from different vendors are registered with UADK as devices, you can use the OpenSSL command line tools or OpenSSL standard interface through the UADK engine to obtain the hardware acceleration functions of the devices. The engine ID is uadk_engine. The sub-modules and functions of the UADK engine are as follows:
- RSA engine: supports key generation, asymmetric encryption and decryption, and digital signature.
- DH engine: supports key negotiation.
- ECC engine: generates data verification codes.
- Cipher engine: supports symmetric encryption and decryption.
- Digest engine: generates message digests.
After a Kunpeng hardware accelerator is registered with UADK, you can use the OpenSSL command line tools or OpenSSL standard interface to use the functions of the Kunpeng hardware accelerator through the UADK engine.
Application Scenarios
Big data, data confidentiality, intelligent security, web services, and distributed storage.
Usage Requirements
This section uses the Kunpeng hardware accelerator as an example to describe the usage requirements of UADK and the UADK engine. The usage requirements of other vendors' hardware accelerators are similar.
Hardware
A CPU of the Kunpeng 9xx series that has been registered with UADK.
Software
Operating System
openEuler 22.03 LTS or later. The OS kernel must support the IOMMU and SVA features.
Other Software Packages
OpenSSL 1.1.1a or later.
Toolchain
Compiler used to build UADK and the UADK engine:
GCC 10.2.0
Installation and Deployment
This section uses the Kunpeng hardware accelerator as an example to describe how to install, upgrade, and uninstall UADK and the UADK engine. The installation, upgrade, and uninstallation of hardware accelerators from other vendors are similar. The kernel-mode driver of the Kunpeng hardware accelerator and the user-mode driver of UADK need to be used together. Perform the operations in sequence.
Installing and Deploying UADK
The UADK algorithm library can be installed using the Yum source or RPM package, or built from source. You can select an installation method as required.
Installing Using the Yum Source
On openEuler 22.03 LTS SP2 or later, run the following command to install UADK from the Yum source:
yum install libwd
Installing Using the RPM Package
Obtain the UADK RPM package from the openEuler community.
The installation commands are as follows:
cd /usr/src/
git clone https://gitee.com/src-openeuler/libwd.git
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
Building from Source
Obtain the UADK source code from the Linaro community.
For details about how to build, install, and configure UADK, visit https://github.com/Linaro/uadk/blame/master/INSTALL.
Loading the UACCE Driver
Before loading the hardware accelerator driver of the vendor, you need to load uacce.ko.
Run modprobe uacce
or insmod /lib/modules/$(uname -r)/uacce.ko
to load uacce.ko.
Loading the Accelerator Driver of the Vendor
The following uses the Kunpeng hardware accelerator as an example to describe how to load a driver.
Accelerator Module | Module Loading Sequence |
---|---|
HPRE | uacce.ko, hisi_qm.ko, hisi_hpre.ko |
ZIP | uacce.ko, hisi_qm.ko, hisi_zip.ko |
SEC | uacce.ko, hisi_qm.ko, hisi_sec2.ko |
Note:
When loading hisi_hpre.ko, hisi_zip.ko, or hisi_sec2.ko, you can specify uacce_mode.uacce_mode=1
indicates the SVA mode.uacce_mode=2
indicates the no-SVA mode. The user-mode driver of the Kunpeng hardware accelerator depends on the UACCE framework (while the kernel-mode driver does not). Therefore, you need to load uacce.ko first. The ZIP, HPRE, and SEC modules of the Kunpeng hardware accelerator depend on the QM module for queue management. Therefore, after loading uacce.ko, you need to load hisi_qm.ko, and then load the drivers of the ZIP, HPRE, and SEC modules.
You can use the insmod or modprobe tool to load the drivers.
To load the drivers using the modprobe tool, perform the following steps:
Load the user-mode driver of the HPRE module in SVA mode.
modprobe hisi_hpre uacce_mode=1
Load the user-mode driver of the SEC module in SVA mode.
modprobe hisi_sec2 uacce_mode=1
Load the user-mode driver of the ZIP module in SVA mode.
modprobe hisi_zip uacce_mode=1
To load the drivers using the insmod tool, perform the following steps:
Load the user-mode driver of the HPRE module in SVA mode.
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
Load the user-mode driver of the SEC module in SVA mode.
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
Load the user-mode driver of the ZIP module in SVA mode.
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
Module parameter configuration:
When loading the drivers, you can set the module parameters in any sequence. After configuring the module parameters and loading the driver, you can query the module parameters by using the cat /sys/bus/pci/drivers/<driver>/module/parameters/
command. The module parameters cannot be updated after the driver is loaded. To modify the module parameters, you need to unload the driver, set the new module parameters, and reload the driver.
The formats of the module parameter configuration commands are as follows:
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]
- The parameters in square brackets ([]) are optional and have default values. The parameters can be in any sequence.
- The default value of uacce_mode for all modules is 0, indicating that the user mode is not supported. Therefore, you need to set uacce_mode=1 for users in user mode.
- The default value of pf_q_num for the SEC module is 256. The default value of pf_q_num for the HPRE or ZIP module is 64.
- The default value of vfs_num for all modules is 0.
- The default value of sgl_sge_nr for all modules is 10.
- The default value of ctx_q_num for all modules is 2.
For example, if you choose not to use the default values when loading the ZIP driver, run the following command to manually configure the parameters:
insmod /lib/modules/$(uname -r)/hisi_zip.ko uacce_mode=1 pf_q_num =16 vfs_num=1 sgl_sge_nr=16
- If only the SVA feature is required for the first time, set uacce_mode=1.
Unloading the Accelerator Driver of the Vendor
The following uses the Kunpeng hardware accelerator as an example to describe how to unload a driver. To unload a driver, run the following command:
modprobe -r hisi_hpre
or
rmmod hisi_hpre
Installing and Deploying the UADK Engine
The UADK engine can be installed using the Yum source or RPM package, or built from source. You can select an installation method as required.
Installing Using the Yum Source
On openEuler 22.03 LTS SP2, run the following command to install the UADK engine using the Yum source:
yum install uadk_engine
Installing Using the RPM Package
Obtain the UADK engine RPM package from the openEuler community.
The installation commands are as follows:
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
Building from Source
Obtain the UADK engine source code from the Linaro community.
For details about how to build and install the UADK engine, visit https://github.com/Linaro/uadk_engine/blob/master/README.md.
Getting Started
Using UADK
UADK provides a performance test tool. After UADK is built and installed, a tool named uadk_tool is generated. You can view the usage and parameter description of the performance test tool using the uadk_tool benchmark --help
command.
Enabling Environment Variables
Run the export
commands to set the numbers of queues.
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"
The input parameter format of the environment variables is ctx_mode:ctx_num@node, indicating that a number of ctx_num queues in ctx_mode are set on the NUMA node whose index is node. For example, "sync:2@0,async:4@0" indicates that two queues in sync mode and four queues in async mode are set on the NUMA 0 node.
Performing Performance Tests
MD5 performance test
Test the digest calculation performance of MD5 in SVA mode.
uadk_tool benchmark --alg md5 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
SM3 performance test
Test the digest calculation performance of SM3 in SVA mode.
uadk_tool benchmark --alg sm3 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
SHA performance test
Test the digest calculation performance of SHA-512 in SVA mode.
uadk_tool benchmark --alg sha-512 --mode sva --opt 0 --sync --seconds 5 --thread 2 --multi 1 --ctxnum 6
AES performance test
Test the performance of AES-128-CBC encryption in SVA mode.
uadk_tool benchmark --alg aes-128-cbc --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
Test the performance of AES-128-CBC decryption in SVA mode.
uadk_tool benchmark --alg aes-128-cbc --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
SM4 performance test
Test the performance of SM4-128-ECB encryption in SVA mode.
uadk_tool benchmark --alg sm4-128-ecb --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
Test the performance of SM4-128-ECB decryption in SVA mode.
uadk_tool benchmark --alg sm4-128-ecb --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
DES performance test
Test the performance of 3DES-128-ECB encryption in SVA mode.
uadk_tool benchmark --alg 3des-128-ecb --mode sva --opt 0 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
Test the performance of 3DES-128-ECB decryption in SVA mode.
uadk_tool benchmark --alg 3des-128-ecb --mode sva --opt 1 --sync --pktlen 1024 --seconds 5 --multi 1 --thread 2 --ctxnum 6
For other test scenarios, use the
uadk_tool benchmark --help
command to view the parameter and configuration description.
Using the UADK Engine
You can use the OpenSSL command line tools to directly invoke the UADK engine. Use the help menu of each OpenSSL tool to learn about how to use the tool.
Enabling Environment Variables
The UADK engine supports environment variables. You can set the numbers of queues for executing tasks as required.
Add the following content to the beginning of the openssl.cnf file (usually in /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
Run the
export
commands to set the numbers of queues.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"
The input parameter format of the environment variables is ctx_mode:ctx_num@node, indicating that a number of ctx_num queues in ctx_mode are set on the NUMA node whose index is node. For example, "sync:2@0,async:4@0" indicates that two queues in sync mode and four queues in async mode are set on the NUMA 0 node.
Performing Function Tests
RSA function test
Generate a private key.
openssl genrsa -out prikey.pem -engine uadk_engine 1024
Obtain a public key.
openssl rsa -in prikey.pem -pubout -out pubkey.pem -engine uadk_engine
Assume that the file to be encrypted is plain.txt.
echo "Content to be encrypted" > plain.txt
Encrypt the file.
openssl rsautl -encrypt -in plain.txt -inkey pubkey.pem -pubin -out enc.txt -engine uadk_engine
Decrypt the file.
openssl rsautl -decrypt -in enc.txt -inkey prikey.pem -out dec.txt -engine uadk_engine
Assume that the file to be signed is msg.txt.
echo "Content to be signed" > msg.txt
Sign the file.
openssl rsautl -sign -in msg.txt -inkey prikey.pem -out signed.txt -engine uadk_engine
Verify the signature.
openssl rsautl -verify -in signed.txt -inkey pubkey.pem -pubin -out verified.txt -engine uadk_engine
Use the openssl speed tool to perform the test.
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 function test
Generate a global public key parameter.
openssl dhparam -out dhparam.pem 768
Generate Alice's private key.
openssl genpkey -paramfile dhparam.pem -out alice_prikey.pem -engine uadk_engine
Obtain Alice's public key.
openssl pkey -in alice_prikey.pem -pubout -out alice_pubkey.pem
Generate Bob's private key.
openssl genpkey -paramfile dhparam.pem -out bob_prikey.pem -engine uadk_engine
Obtain Bob's public key.
openssl pkey -in bob_prikey.pem -pubout -out bob_pubkey.pem
Exchange public keys and generate negotiated keys.
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
Compare the negotiated shared keys.
cmp secret1.bin secret2.bin xxd secret1.bin xxd secret2.bin
MD5 function test
Assume that the digest file to be calculated is data.txt.
echo "Content to be hashed" > data.txt
Calculate the digest.
openssl md5 -engine uadk_engine data.txt
Use the openssl speed tool to perform the test.
openssl speed -engine uadk_engine -async_jobs 1 -evp md5
SM3 function test
Assume that the digest file to be calculated is data.txt.
echo "Content to be hashed" > data.txt
Calculate the digest.
openssl sm3 -engine uadk_engine data.txt
SHA function test
Assume that the digest file to be calculated is data.txt.
echo "Content to be hashed" > data.txt
Calculate the digest.
openssl sha1 -engine uadk_engine data.txt openssl sha256 -engine uadk_engine data.txt openssl sha512 -engine uadk_engine data.txt
AES function test
Assume that the file to be encrypted is data.txt.
echo "Content to be encrypted" > data
Use AES-128-CBC to encrypt the file.
openssl enc -aes-128-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-128-CBC to decrypt the file.
openssl enc -aes-128-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-192-CBC to encrypt the file.
openssl enc -aes-192-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-192-CBC to decrypt the file.
openssl enc -aes-192-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-256-CBC to encrypt the file.
openssl enc -aes-256-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-256-CBC to decrypt the file.
openssl enc -aes-256-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use AES-128-ECB to encrypt the file.
openssl enc -aes-128-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-128-ECB to decrypt the file.
openssl enc -aes-128-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-192-ECB to encrypt the file.
openssl enc -aes-192-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-192-ECB to decrypt the file.
openssl enc -aes-192-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-256-ECB to encrypt the file.
openssl enc -aes-256-ecb -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-256-ECB to decrypt the file.
openssl enc -aes-256-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-128-CTR to encrypt the file.
openssl enc -aes-128-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-128-CTR to decrypt the file.
openssl enc -aes-128-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-192-CTR to encrypt the file.
openssl enc -aes-192-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-192-CTR to decrypt the file.
openssl enc -aes-192-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-256-CTR to encrypt the file.
openssl enc -aes-256-ctr -a -in data -out data.en -pass pass:123456 -K abc -engine uadk_engine -p
Use AES-256-CTR to decrypt the file.
openssl enc -aes-256-ctr -a -d -in data.en -out data.de -pass pass:123456 -K abc -engine uadk_engine -p
SM4 function test
Use SM4-CBC to encrypt the file.
openssl enc -sm4-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use SM4-CBC to decrypt the file.
openssl enc -sm4-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use SM4-ECB to encrypt the file.
openssl enc -sm4-ecb -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use SM4-ECB to decrypt the file.
openssl enc -sm4-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
DES function test
Use DES-EDE3-CBC to encrypt the file.
openssl enc -des-ede3-cbc -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use DES-EDE3-CBC to decrypt the file.
openssl enc -des-ede3-cbc -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use DES-EDE3-ECB to encrypt the file.
openssl enc -des-ede3-ecb -a -in data -out data.en -pass pass:123456 -K abc -iv abc -engine uadk_engine -p
Use DES-EDE3-ECB to decrypt the file.
openssl enc -des-ede3-ecb -a -d -in data.en -out data.de -pass pass:123456 -K abc -iv abc -engine uadk_engine -p