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
    • UADK Installation and Deployment
      • 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 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 UADK Engine
      • Enabling Environment Variables
      • Performing Function Tests

Overview

Welcome to use UADK and UADK engine. This document describes how to quickly start using UADK and UADK engine.

UADK

User Space Accelerator Development Kit (UADK) is a general-purpose user space accelerator framework that uses the shared virtual address (SVA) technology to provide a unified programming interface for hardware acceleration computing cryptography and compression algorithms. UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE), which enables hardware accelerators from different vendors that support the SVA technology to adapt to UADK.

UADK consists of UACCE, the vendor driver, and 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 on 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 cryptography 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 cryptography and compression algorithms using the hardware accelerators instead of CPU, freeing up CPU computing power and improving computing performance.

UADK engine

UADK engine is an upper-layer application of UADK developed based on the OpenSSL engine mechanism. UADK engine provides the function of using the hardware accelerators through the OpenSSL command line tools and OpenSSL standard interface to quickly migrate existing services.

UADK engine consists of four sub-modules: RSA engine, DH engine, Cipher engine and Digest engine. After hardware accelerators from different vendors are registered with UADK, you can use the OpenSSL command line tools or OpenSSL standard interface through UADK engine to use the hardware acceleration computing functions of the devices. The engine ID is uadk_engine. The modules and functions of UADK engine are as follows:

• RSA engine sub-module: supports key generation, asymmetric encryption and decryption, and digital signature.
• DH engine sub-module: supports key exchange.
• Cipher engine sub-module: supports symmetric encryption and decryption.
• Digest engine sub-module: 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 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 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 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 UADK engine:

gcc version 10.2.0 (GCC)

Installation and Deployment

This section uses the Kunpeng hardware accelerator as an example to describe how to install, upgrade, and uninstall UADK and UADK engine. The installation, upgrade, and uninstallation of hardware accelerators from other vendors are similar. The kernel-mode driver of the Kunpeng accelerator and the UADK user-mode driver need to be used together. Perform the operations in sequence.

UADK Installation and Deployment

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 or later, run the following command to install it using 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. The default value of uacce_mode is 0. uacce_mode=0 indicates the kernel mode. uacce_mode=1 indicates the user-mode SVA mode. uacce_mode=2 indicates the user-mode no-SVA mode. The user-mode driver of the Kunpeng accelerator depends on the UACCE framework (while the kernel mode 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 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 driver.

To load the drivers using the modprobe tool, perform the following steps:

• Load the HPRE module driver in user-mode SVA mode.

  modprobe hisi_hpre uacce_mode=1
  

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

  modprobe hisi_sec2 uacce_mode=1
  

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

  modprobe hisi_zip uacce_mode=1
  

To load the drivers using the insmod tool, perform the following steps:

• Load the HPRE module driver in user-mode 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 SEC module driver in user-mode 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 ZIP module driver in user-mode 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 and set the new module parameters when reloading 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 [] are optional and have default values. The parameters can be in any sequence.
  • The default value of uacce_mode of 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 of the SEC module is 256. The default value of pf_q_num of 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 the driver:

modprobe -r hisi_hpre

or

rmmod hisi_hpre

Installing and Deploying UADK Engine

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, run the following command to install 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 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 the 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 variable 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 the 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 UADK Engine

You can use the OpenSSL command line tools to directly invoke UADK engine. Use the help menu of each OpenSSL tool to view how to use the tool.

Enabling Environment Variables

UADK engine supports environment variables. You can set the number of queues for executing tasks as required.

1. Add the following content to the beginning of the openssl.cnf file (generally 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 the 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 variable 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
  

  Using 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
  

  Using AES-128-BCC 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
  

  Using 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
  

  Using 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
  

  Using AES-256-BCC 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
  

  Using AES-256-BCC 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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

  Using 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
  

  Using 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
  

  Using 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
  

  Using 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