UADK Quick Start Guide

• UADK Quick Start Guide
  • Overview
    • UADK
    • UADK Engine
    • Application Scenarios
  • Usage Requirements
    • Hardware
    • Software
      • Operating System
      • Other Software Packages
    • Toolchain
  • Installation and Deployment
    • Installing and Deploying UADK
      • Installing Using the Yum Source
      • Installing Using the RPM Package
      • Building from Source
    • Loading the UACCE Driver
    • Loading the Accelerator Driver of the Vendor
    • Unloading the Accelerator Driver of the Vendor
    • Installing and Deploying the UADK Engine
      • Installing Using the Yum Source
      • Installing Using the RPM Package
      • Building from Source
  • Getting Started
    • Using UADK
      • Enabling Environment Variables
      • Performing Performance Tests
    • Using the UADK Engine
      • Enabling Environment Variables
      • Performing Function Tests

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 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.

Description: 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, 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.

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.

1. 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
   

2. 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