LTS

    Innovation Version

      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 ModuleModule Loading Sequence
      HPREuacce.ko, hisi_qm.ko, hisi_hpre.ko
      ZIPuacce.ko, hisi_qm.ko, hisi_zip.ko
      SECuacce.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.

      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
        

      Bug Catching

      Buggy Content

      Bug Description

      Submit As Issue

      It's a little complicated....

      I'd like to ask someone.

      PR

      Just a small problem.

      I can fix it online!

      Bug Type
      Specifications and Common Mistakes

      ● Misspellings or punctuation mistakes;

      ● Incorrect links, empty cells, or wrong formats;

      ● Chinese characters in English context;

      ● Minor inconsistencies between the UI and descriptions;

      ● Low writing fluency that does not affect understanding;

      ● Incorrect version numbers, including software package names and version numbers on the UI.

      Usability

      ● Incorrect or missing key steps;

      ● Missing prerequisites or precautions;

      ● Ambiguous figures, tables, or texts;

      ● Unclear logic, such as missing classifications, items, and steps.

      Correctness

      ● Technical principles, function descriptions, or specifications inconsistent with those of the software;

      ● Incorrect schematic or architecture diagrams;

      ● Incorrect commands or command parameters;

      ● Incorrect code;

      ● Commands inconsistent with the functions;

      ● Wrong screenshots.

      Risk Warnings

      ● Lack of risk warnings for operations that may damage the system or important data.

      Content Compliance

      ● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

      ● Copyright infringement.

      How satisfied are you with this document

      Not satisfied at all
      Very satisfied
      Submit
      Click to create an issue. An issue template will be automatically generated based on your feedback.
      Bug Catching
      编组 3备份