Building Software Acceleration Features in the Intel® Quick Assist Technology (Intel® QAT) Engine for OpenSSL*

 Building OpenSSL from Source

This section describes how to build the Intel QAT Engine for OpenSSL when OpenSSL is built from source code. If you want to build the engine using your distribution's pre-packaged version of OpenSSL, click the Using the Distribution-Provided OpenSSL tab, above.

Build Requirements

You'll need some prerequisite software packages to build OpenSSL, the Intel QAT Engine for OpenSSL, and the engine's dependencies.

Ubuntu 22.04 LTS

To build the Intel QAT Engine for OpenSSL and its dependencies on Ubuntu, you’ll need to install the following packages from apt:

sudo apt install autoconf build-essential libtool cmake cpuid pkg-config_nasm

RHEL 9.2

sudo yum install autoconf libtool cmake pkg-config nasm openssl perl

Runtime Requirements

To make use of the software acceleration features in the Intel QAT Engine for OpenSSL, you’ll need a system that supports Intel® AVX-512 with the following instruction set extensions:

• AVX512F
• AVX512_IFMA
• VAES
• VPCLMULQDQ

The latter two extensions were introduced with certain 10th Generation Intel® Core™ processors and 3^rd Generation Intel® Xeon® Scalable processors (products formerly codenamed Ice Lake). A quick way to verify that your system supports the necessary features is to run the cpuid command. Run the following and check that the output matches.

$ cpuid -1 | egrep 'VAES|VPCLM|GFNI|AVX512F|AVX512IFMA'
      AVX512F: AVX-512 foundation instructions = true
      AVX512IFMA: fused multiply add           = true
      VAES instructions                        = true
      VPCLMULQDQ instruction                   = true

All features must be present.

These output fields are only present in cpuid version 20211210 or later. This is the default version provided in Ubuntu 22.04.

Choose a Directory Structure

Before we proceed with the build, we need to decide where to install the completed packages and libraries for both OpenSSL and the Intel QAT Engine for OpenSSL. Since the goal of building from source code is to produce a build that can be upgraded as needed without interfering with existing applications, we want a directory hierarchy that allows for parallel installations of multiple versions of the same tool. To keep the filesystem tidy, we'll place these packages in /opt using the following structure:

/opt/tool/version

Building OpenSSL v3.0.9

Example here uses OpenSSL 3.0.1. 

wget https://www.openssl.org/source/openssl-3.0.9.tar.gz 
tar xf openssl-3.0.9.tar.gz
cd openssl-3.0.9

To configure OpenSSL, run the config program and set the --prefix and --openssldir options to our desired installation directory, which will be /opt/openssl/3.0.9

./config --prefix=/opt/openssl/3.0.9 --openssldir=/opt/openssl/3.0.9

Then build and install:

make -j
sudo make install

Because we have installed OpenSSL into a non-standard build directory, we'll need to make some environment changes. To ensure you get this version of OpenSSL and not your system one, prepend the OpenSSL directory to your PATH variable:

export PATH=/opt/openssl/3.0.9/bin:$PATH

You also need to set LD_LIBRARY_PATH in your environment to run the binary, but for the purposes of this document, we will wait until all components are compiled and installed before doing so.

To verify OpenSSL is built and installed correctly, run the following:

$ LD_LIBRARY_PATH=/opt/openssl/3.0.9/lib64 openssl version -v -e
OpenSSL 3.0.9 30 May 2023 (Library: OpenSSL 3.0.9 30 May 2023)
ENGINESDIR: "/opt/openssl/3.0.9/lib64/engines-3"

You should see the correct version, and ENGINESDIR should be pointing to your installation in /opt/openssl.

You can set these environment variables in scripts to ensure that OpenSSL from the intended location.

If you don't set LD_LIBRARY_PATH, OpenSSL will load the equivalent libraries from the distribution's default location, resulting in a mismatch of library and binary versions. This will prevent the QAT engine from loading in OpenSSL, and it can also cause sporadic runtime errors in OpenSSL itself.

Building the Intel QAT OpenSSL Engine for Software Acceleration

The software acceleration support in the Intel QAT Engine for OpenSSL depends on the following two libraries. They must be built first, but they may be built in any order:

• Intel® Integrated Performance Primitives Cryptography
• Intel® Multi-Buffer Crypto for IPsec Library

Once these libraries are installed, you can build the Intel Quick Assist Technology OpenSSL Engine.

We’ll step through how to build each one.

Building Intel® Integrated Performance Primitives Cryptography

First, checkout the source code repository from GitHub*:

git clone https://github.com/intel/ipp-crypto.git
cd ipp-crypto

Ensure you are building against a fixed release of the code, and not the development branch. 

git checkout ippcp_2021.7.1

You only need to build the multi-buffer portion of the Intel IPP package, so change to the multi-buffer crypto library subdirectory. Then, prepare the build by running cmake:

cd sources/ippcp/crypto_mb
cmake . -Bbuild -DCMAKE_INSTALL_PREFIX=/opt/crypto_mb/2021.7.1

Note that we are using crypto_mb as our tool name, since we aren't building the entire IPP package.

This library needs to know where to find your OpenSSL sources, so set OPENSSL_ROOT_DIR.

export OPENSSL_ROOT_DIR=/opt/openssl/3.0.9/

To perform the build, run:

cd build
make -j
sudo make install

We'll also need to update LD_LIBRARY_PATH to include this new library directory and will do so after all components have been compiled and installed.

Building the Intel® Multi-Buffer Crypto for IPsec Library

First, checkout the source code repository from GitHub:

git clone https://github.com/intel/intel-ipsec-mb.git
cd intel-ipsec-mb

Ensure you are building against a fixed release of the code, and not a development branch.

git checkout v1.3

There is no configuration step. Build the library using:

make -j

To install to our destination, define PREFIX when running "make install":

sudo make install NOLDCONFIG=y PREFIX=/opt/ipsec-mb/1.3

We'll also need to update LD_LIBRARY_PATH to include this new library directory and will do so after all components have been compiled and installed.

Building the Intel Quick Assist Technology Engine for OpenSSL

Checkout the software repository from GitHub:

git clone https://github.com/intel/QAT_Engine.git
cd QAT_Engine

Next, ensure you are building against a fixed release of the code, and not a development branch.

git checkout v1.2.0

To configure the Intel QAT OpenSSL engine for all software acceleration features, we need to do the following:

• Set LDFLAGS and CPPFLAGS to ensure the Intel IPP Crypto and Multi-Buffer Library for IPSec libraries are found by configure. The options --with-qat_sw_crypto_mb_install_dir and --with-qat_sw_ipsec_mb_install_dir are provided for this purpose.
• Supply the location of our OpenSSL library via the --with-openssl_install_dir option.
• Add the --with-openssl_dir option, which points to the OpenSSL source code. This will regenerate the error files from OpenSSL's source.

​Here, we assume that you are building from your home directory. Be sure to update the path to match your build environment.

./autogen.sh
LDFLAGS="-L/opt/ipsec-mb/1.3/lib -L/opt/crypto_mb/2021.7.1/lib" CPPFLAGS="-I/opt/ipsec-mb/1.3/include -I/opt/crypto_mb/2021.7.1/include" ./configure --prefix=/opt/openssl/3.0.9 --with-openssl_install_dir=/opt/openssl/3.0.9 --with-openssl_dir=$HOME/openssl-3.0.9 --enable-qat_sw

To build and install, we also need to set PERL5LIB on the command line, so that Perl can find the configdata.pm file in the OpenSSL source directory. This step is necessary due to a bug in the QAT Engine build configuration, and it will be fixed in a future release.

PERL5LIB=$HOME/openssl-3.0.9 make -j
sudo PERL5LIB=$HOME/openssl-3.0.9 make install

After the installation has completed, you should see the engine present in OpenSSL’s engine directory:

ls -l /opt/openssl/3.0.9/lib64/engines-3/qatengine.*
-rwxr-xr-x 1 root root   1029 Aug  7 12:22 /opt/openssl/3.0.9/lib64/engines-3/qatengine.la
-rwxr-xr-x 1 root root 699672 Aug  7 12:22 /opt/openssl/3.0.9/lib64/engines-3/qatengine.so

Remember to set both LD_LIBRARY_PATH and modify your own PATH, or the following examples will fail. This can be done either in the user’s environment or the application’s environment. The example below demonstrates exporting the LD_LIBRARY_PATH in the user’s environment. Note that this method may impact other applications or libraries that are dependent on a specific versions of OpenSSL’s libCrypto or libSSL shared libraries delivered as part of the distribution.

export PATH=/opt/openssl/3.0.9/bin:$PATH
export LD_LIBRARY_PATH=/opt/openssl/3.0.9/lib64:/opt/crypto_mb/2021.7.1/lib:/opt/ipsec-mb/1.3/lib

To avoid impacting other applications or libraries dependent of older version of OpenSSL libraries, the safer option is to set LD_LIBRARY_PATH as part of the application’s environment which is shown in the following example.

LD_LIBRARY_PATH=/opt/openssl/3.0.9/lib64:/opt/crypto_mb/2021.7.1/lib:/opt/ipsec-mb/1.3/lib openssl version -e -v