Skip to content

qat_common.md

Latest commit

 

History

History
252 lines (199 loc) · 9.19 KB

qat_common.md

File metadata and controls

252 lines (199 loc) · 9.19 KB

OpenSSL Provider Support

Intel® QAT OpenSSL* Engine supports both the legacy Engine interface and the OpenSSL 3.x Provider interface (qatprovider) in production environments. The Provider interface is the recommended integration point for OpenSSL 3.x applications and offers the same QAT acceleration capabilities as the Engine interface. Provider support can be enabled using the configure flag --enable-qat_provider; the default, if not specified, is the Engine interface.

Example commands to test using qatprovider:

Note: If qatprovider.so is not installed in the default OpenSSL* modules directory (<openssl-install>/lib64/ossl-modules/), add -provider-path /path/to/ossl-modules before -provider qatprovider in all commands below.

Note: When loading qatprovider explicitly, always also load the OpenSSL* default provider (add -provider default to command-line invocations, or activate [default_sect] in openssl.cnf). The default provider supplies algorithms not offloaded by QAT (e.g. certificate parsing, key encoding, digest algorithms used internally). Omitting it can cause unexpected failures.

Note: When QAT HW or SW offload is supported and enabled on the platform, qatprovider takes the highest priority over all other stacked providers for the algorithms it offloads.

  • QAT_HW ./openssl speed -provider qatprovider -elapsed -async_jobs 72 rsa2048
  • QAT_SW ./openssl speed -provider qatprovider -elapsed -async_jobs 8 rsa2048

RSA Sign/Verify:

./openssl genrsa -provider qatprovider -out rsa_key.pem 2048
./openssl dgst -provider qatprovider -sha256 -sign rsa_key.pem -out sig.bin plain.txt
./openssl dgst -provider qatprovider -sha256 -verify <(./openssl rsa -in rsa_key.pem -pubout) -signature sig.bin plain.txt

ECDSA Sign/Verify (P-256):

./openssl genpkey -provider qatprovider -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ec_key.pem
./openssl dgst -provider qatprovider -sha256 -sign ec_key.pem -out ec_sig.bin plain.txt
./openssl dgst -provider qatprovider -sha256 -verify <(./openssl pkey -in ec_key.pem -pubout) -signature ec_sig.bin plain.txt

AES-GCM Encrypt/Decrypt:

./openssl enc -provider qatprovider -aes-256-gcm -pbkdf2 -in plain.txt -out enc.bin
./openssl enc -provider qatprovider -aes-256-gcm -pbkdf2 -d -in enc.bin -out dec.txt

TLS Handshake (s_server / s_client):

# Server
./openssl s_server -provider qatprovider -cert server.crt -key server.key -port 4433 &
# Client
./openssl s_client -provider qatprovider -connect localhost:4433

Interoperability with OpenSSL Default Provider for Hybrid PQC

qatprovider supports hybrid post-quantum cryptography (PQC) by stacking with a second provider that supplies PQC algorithms. QAT accelerates the classical component (e.g. ECDH P-256/P-384, RSA, AES-GCM) while the PQC provider supplies the post-quantum component (ML-KEM, ML-DSA). Two configurations have been tested:

Configuration OpenSSL Version PQC Provider
OpenSSL 3.5.x built-in 3.5.x Built-in default provider (ML-KEM, ML-DSA)
liboqs + oqs-provider 3.x (≤3.4.x) oqs-provider backed by liboqs

Option 1: OpenSSL 3.5.x built-in default provider

OpenSSL 3.5.x ships ML-KEM and ML-DSA natively in its default provider — no additional libraries are needed.

openssl.cnf — stacked provider configuration:

openssl_conf = openssl_init

[openssl_init]
providers = provider_section

[provider_section]
qatprovider = qat_prov_section
default     = default_sect

[qat_prov_section]
module   = /usr/local/lib64/ossl-modules/qatprovider.so
activate = 1

[default_sect]
activate = 1

Test hybrid KEM speed:

./openssl speed -provider qatprovider -provider default \
    -elapsed X25519MLKEM768 p256_mlkem768

TLS handshake with hybrid KEM groups:

# Server
./openssl s_server \
    -provider qatprovider -provider default \
    -cert server.crt -key server.key -port 4433 \
    -groups X25519MLKEM768:p256_mlkem768:X25519 &

# Client
./openssl s_client \
    -provider qatprovider -provider default \
    -connect localhost:4433 \
    -groups X25519MLKEM768:p256_mlkem768:X25519

Generate a hybrid key and self-signed certificate (hybrid signatures):

./openssl genpkey \
    -provider qatprovider -provider default \
    -algorithm p256_mldsa44 -out hybrid_key.pem

./openssl req -new -x509 \
    -provider qatprovider -provider default \
    -key hybrid_key.pem -out hybrid_cert.pem \
    -subj "/CN=QAT Hybrid Test"

TLS handshake with hybrid signature authentication:

# Server
./openssl s_server \
    -provider qatprovider -provider default \
    -cert hybrid_cert.pem -key hybrid_key.pem -port 4433 &

# Client
./openssl s_client \
    -provider qatprovider -provider default \
    -connect localhost:4433 \
    -CAfile hybrid_cert.pem

Option 2: OpenSSL 3.4.x with liboqs + oqs-provider

For OpenSSL versions prior to 3.5.x, use liboqs and oqs-provider to supply PQC algorithms. Build and install them following the oqs-provider build instructions.

openssl.cnf — stacked provider configuration:

openssl_conf = openssl_init

[openssl_init]
providers = provider_section

[provider_section]
qatprovider = qat_prov_section
oqsprovider  = oqs_prov_section
default      = default_sect

[qat_prov_section]
module   = /usr/local/lib64/ossl-modules/qatprovider.so
activate = 1

[oqs_prov_section]
module   = /usr/local/lib64/ossl-modules/oqsprovider.so
activate = 1

[default_sect]
activate = 1

Test hybrid KEM speed:

./openssl speed -provider qatprovider -provider oqsprovider -provider default \
    -elapsed X25519_kyber768 p256_kyber768

TLS handshake with hybrid KEM groups:

# Server
./openssl s_server \
    -provider qatprovider -provider oqsprovider -provider default \
    -cert server.crt -key server.key -port 4433 \
    -groups X25519_kyber768:p256_kyber768:X25519 &

# Client
./openssl s_client \
    -provider qatprovider -provider oqsprovider -provider default \
    -connect localhost:4433 \
    -groups X25519_kyber768:p256_kyber768:X25519

FIPS 140-3 Certification

Intel® QAT OpenSSL* Engine contains changes to comply with FIPS 140-3 Level-1 Certification requirements using QAT Provider against OpenSSL 3.0.8. The FIPS support can be enabled using the configure flag --enable-qat_fips only with OpenSSL 3.0.8 using the provider interface, which must be enabled using --enable-qat_provider.

When the FIPS flag is enabled along with the provider for OpenSSL 3.0.8, it will run self-tests and integrity tests and will satisfy other FIPS 140-3 CMVP & CAVP requirements. The FIPS build is packaged as an RPM using the specfile fips/qatengine_fips.spec with QAT_HW & QAT_SW Co-existence enabled along with other required flags.

The Intel® QAT OpenSSL* Engine (version v1.3.1) has obtained FIPS 140-3 Level-1 certification. The certificate is available at the NIST CMVP Certificate #5032.

Support Algorithms in FIPS mode

Mode Algorithms
QAT_HW RSA, ECDSA, ECDH, ECDHX25519, ECDHX448, DSA, DH, TLS1.2-KDF(PRF), TLS1.3-KDF(HKDF), SHA3 & AES-GCM
QAT_SW RSA, ECDSA, ECDH, ECDHX25519, SHA2 & AES-GCM

Binary RPM Package

QAT_Engine supports Binary Package via RPM which can be found in the Release page (Assests section) The Current Binary RPM Package is created for the distros RHEL 9.2, Ubuntu 22.04 and SUSE SLES15 SP3 with with default Kernel and other dependent packages from the system default. The RPM is generated using QAT2.0 OOT driver with QAT_SW Co-existence which means it will accelerate via QAT_HW for asymmetic PKE and QAT_SW for AES-GCM and supported only on Intel® Xeon® Scalable Processor family with Intel® QAT Gen4/Gen4m with default build configuration in QAT Engine against OpenSSL 3.0 engine and can be built using the make rpm_oot target. Dependent library versions used for building binary package are mentioned in Software requirements section.

Example commands below to install and uninstall RPM Package

install:
    RHEL & SUSE: rpm -ivh QAT_Engine-<version>.x86_64.rpm --target noarch
    Ubuntu: alien -i QAT_Engine-<version>.x86_64.rpm --scripts
uninstall
    RHEL & SUSE: rpm -e QAT_Engine
    Ubuntu: apt-get remove QAT_Engine

The binary RPM Package will take care of installing dependent libraries and kernel modules in the default path and OpenSSL being installed in /usr/local/ssl Since it is using different OpenSSL version(refer Software requirements for version) than what is present in the system. LD_LIBRARY_PATH must be set to this path below.

export LD_LIBRARY_PATH=/usr/local/ssl/lib64