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 SP4 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://atomgit.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.

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.

  shell

  modprobe hisi_hpre uacce_mode=1

• Load the user-mode driver of the SEC module in SVA mode.

  shell

  modprobe hisi_sec2 uacce_mode=1

• Load the user-mode driver of the ZIP module in SVA mode.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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:

  shell

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

  shell

  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:

  shell

  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 SP4, 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://atomgit.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.

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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

1. Add the following content to the beginning of the openssl.cnf file (usually in /usr/local/ssl/):

   text

   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. Run the export commands to set the numbers of queues.

   shell

   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.

  shell

  openssl genrsa -out prikey.pem -engine uadk_engine 1024

  Obtain a public key.

  shell

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

  Assume that the file to be encrypted is plain.txt.

  shell

  echo "Content to be encrypted" > plain.txt

  Encrypt the file.

  shell

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

  Decrypt the file.

  shell

  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.

  shell

  echo "Content to be signed" > msg.txt

  Sign the file.

  shell

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

  Verify the signature.

  shell

  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.

  shell

  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.

  shell

  openssl dhparam -out dhparam.pem 768

  Generate Alice's private key.

  shell

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

  Obtain Alice's public key.

  shell

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

  Generate Bob's private key.

  shell

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

  Obtain Bob's public key.

  shell

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

  Exchange public keys and generate negotiated keys.

  shell

  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.

  shell

  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.

  shell

  echo "Content to be hashed" > data.txt

  Calculate the digest.

  shell

  openssl md5 -engine uadk_engine data.txt

  Use the openssl speed tool to perform the test.

  shell

  openssl speed -engine uadk_engine -async_jobs 1 -evp md5

• SM3 function test

  Assume that the digest file to be calculated is data.txt.

  shell

  echo "Content to be hashed" > data.txt

  Calculate the digest.

  shell

  openssl sm3 -engine uadk_engine data.txt

• SHA function test

  Assume that the digest file to be calculated is data.txt.

  shell

  echo "Content to be hashed" > data.txt

  Calculate the digest.

  shell

  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.

  shell

  echo "Content to be encrypted" > data

  Use AES-128-CBC to encrypt the file.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

  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.

  shell

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