search

intel / qatlib

Other
95 stars 34 forks source link

readme

Linux build with gcc CodeQL scan OpenSSF Scorecard

Intel® QuickAssist Technology Library (QATlib)

Table of Contents

Revision History

Date Doc Revision Version Details
November 2024 015 24.09 - Doc update only. Add QAT20-38022 information to Open Issues section.
September 2024 014 24.09 - Improved performance scaling in multi-thread applications (--enable-icp-thread-specific-usdm).
- Bug Fixes. See Resolved Issues.
- Set core affinity mapping based on NUMA node to improve performance (near-linear scaling) on multi-socket platforms.
July 2024 013 24.02 - Doc update only. Updated this table to say that support for the GEN4 402xx device was added in the 24.02 release. Added link to more details in Supported Devices section.
February 2024 012 24.02 - Added Heartbeat support.
- Added support for QAT GEN 5 devices, including support for a range of crypto wireless algorithms.
- RAS - Device error reset and recovery handling.
- Bug Fixes. See Resolved Issues.
November 2023 011 23.11 - Support DC NS (NoSession) APIs.
- Support DC compressBound APIs.
- Support Symmetric Crypto SM3 & SM4.
- Support Asymmetric Crypto SM2.
- Bug Fixes. See Resolved Issues.
August 2023 010 23.08 - Removal of following insecure algorithms: Diffie-Hellman and Elliptic curves less than 256-bits.
- Additional configuration profiles, including sym which facilitates improved symmetric crypto performance.
- DC Chaining (Hash then compress)
- Bug Fixes. See Resolved Issues.
- The shared object version is changed from 3->4.
February 2023 009 23.02 - Added configuration option --enable-legacy-algorithms to use these insecure crypto algorithms and disabled them by default (AES-ECB, SHA-1, SHA2-224, SHA3-224, RSA512/1024/1536, DSA)
- Refactored code in quickassist/utilities/libusdm_drv
- Bugfixes
- Updated documentation with configuration and tuning information
November 2022 008 22.07.2 - Changed from yasm to nasm for assembly compilation
- Added configuration option to use C implementation of soft CRC implementation instead of asm
- Added support for pkg-config
- Added missing lock around accesses to some global data in qatmgr
October 2022 007 22.07.1 - Fix for QATE-86605
July 2022 006 22.07 - Added support for lz4/lz4s compression algorithms
- Added support for Compression End-to-end (E2E) integrity check
- Added support for PKE generic point multiply
- Updated QAT APIs (as a result the shared object version changed from 2->3).
- Enabled CPM2.0b
- Split rpm package
November 2021 005 21.11 - Added qatlib-tests rpm package
- Added option to configure script to skip building sample code
August 2021 004 21.08 - Added support for deflate compression - Compress and Verify (CnV) and Compress and Verify and Recover (CnVnR)
- Added Physical Function to Virtual Function (PFVF) communication support
May 2021 003 21.05 - Added support for AES-CCM 192/265
- Added support for SHA3-224/384/512 (no partials support)
- Added support for ChaCha20-Poly1305
- Added support for PKE 8K (RSA, DH, ModExp, ModInv)
- Fixed device enumeration on different nodes
- Fixed pci_vfio_set_command for 32 bit builds
November 2020 002 20.10 - Fixed service stopping during uninstallation
- Fixed "Cannot open /sys/kernel/iommu_groups/vfio/devices/" error
- Fixes based on static code analysis
- Fixes based on secure code reviews
- Refactored logging mechanism
- Updated library versioning scheme
- Improvements to make install target
- Fix so service file installed in /usr/lib64 can be properly detected
- Remove execute permissions from non-executable files
- Clarified documentation of licensing
- Removed libudev dependency from the package
- Removed OpenSSL/libcrypto extracts, instead link against system OpenSSL/libcrypto
August 2020 001 20.08 - Initial Release

Overview

Intel(R) QuickAssist Technology (Intel(R) QAT) provides hardware acceleration for offloading security, authentication and compression services from the CPU, thus significantly increasing the performance and efficiency of standard platform solutions.

Its services include symmetric encryption and authentication, asymmetric encryption, digital signatures, RSA, DH and ECC, and lossless data compression.

This package provides user space libraries that allow access to Intel(R) QuickAssist devices and expose the Intel(R) QuickAssist APIs and sample codes.

Features

The following services are available in qatlib via the QuickAssist API:

This package includes:

Insecure Algorithms

The following algorithms are considered insecure and are disabled by default.

To enable these algorithms, use the following configuration option:

Deprecated Features & Planned Deprecations

Setup

Please refer to INSTALL for details on installing the library.

Supported Devices

Earlier generations of QAT devices (e.g. c6xx, dh895xxcc, etc.) are not supported. Please refer to QATlib User’s Guide for more information on supported devices.

Limitations

The following features are not currently supported:

Environmental Assumptions

The following assumptions are made concerning the deployment environment:

Examples

Example applications that showcase usage of the QAT APIs are included in the package (quickassist/lookaside/access_layer/src/sample_code). Please refer to Intel® QuickAssist Technology API Programmer's Guide.

Open Issues

Known issues relating to the Intel® QAT software are described in this section.

Issue titles follow the pattern:

<Component> [Stepping] -  Description of issue

where: \<Component> is one of the following:

[Stepping] is an optional qualifier that identifies if the errata applies to a specific device stepping

Issue ID Description
QAT20-38022 CY - Edwards and Montgomery curves not supported in PKE operations.
QATE-102390 GEN - [error] validateConcurrRequest() - : Invalid numConcurrRequests
QATE-3241 CY - cpaCySymPerformOp when used with parameter checking may reveal the amount of padding.
QATE-76073 GEN - If PF device configuration is modified without restarting qatmgr, undefined behavior may occur.

QAT20-38022

Title CY – Edwards and Montgomery curves not supported in PKE operations
Reference # QAT20-38022
Description On some platforms the function cpaCyQueryCapabilities() will report the ecEdMontSupported capability as FALSE and operations using those curves will fail. This case can arise when qatlib is running in a guest and the QAT kernel driver on the host is not a standard Linux in-tree kernel driver. For example, it can occur with some Linux out-of-tree, VMware® ESXi and Windows® QAT kernel drivers.
Implication PKE operations using those elliptic curves will fail.
Resolution There are three ways to resolve this: (a) If host OS is Linux, use the QAT driver which comes with any standard Linux kernel, i.e. the in-tree driver. (b) Apply this patch to your qatlib source code and rebuild and re-install the library. (c) Install an updated QAT kernel driver on the host, which reports a fix for this issue in its release notes.
Affected OS Linux, VMware®, Windows®
Driver/Module CPM-IA – Only applies to QAT GEN4 devices.

QATE-102390

Title GEN – [error] validateConcurrRequest() - : Invalid numConcurrRequests
Reference # QATE-102390
Description An error occurs in a virtualized environment after VF resources are detached from a running VM (guest) and then re-attached. Following this, the qat service is restarted on the guest to ensure the correct VF resources are used. In rare instances, this leads to a failure in process initialisation with the error: "[error] validateConcurrRequest() - : Invalid numConcurrRequests".
Implication Processes within the guest fail to start.
Resolution To resolve the issue, restart the qatmgr on the guest using "sudo systemctl restart qat". If in standalone mode, restart the process manually.
Affected OS Linux
Driver/Module CPM-IA – Only on the 420xx QAT GEN 5 device.

QATE-3241

Title CY - cpaCySymPerformOp when used with parameter checking may reveal the amount of padding.
Reference # QATE-3241
Description When Performing a CBC Decryption as a chained request using cpaCySymPerformOp it is necessary to pass a length of the data to MAC (messageLenToHashInBytes). With ICP_PARAM_CHECK enabled, this checks the length of data to MAC is valid and, if not, it aborts the whole operation and outputs an error on stderr.
Implication The length of the data to MAC is based on the amount of padding. This should remain private and not be revealed. The issue is not observed when the length is checked in constant time before passing the value to the API. This is done by OpenSSL.
Resolution 1. Build without ICP_PARAM_CHECK, but this opens the risk of buffer overrun.
2. Validate the length before using the API.
Affected OS Linux
Driver/Module CPM-IA - Crypto

QATE-76073

Title GEN - If PF device configuration is modified without restarting qatmgr, undefined behavior may occur.
Reference # QATE-76073
Description When qatmgr is initialized, it reads the current configuration of the PF device. If the PF device configuration is modified without restarting the qatmgr, the updated device configuration is not comprehended by qatmgr.
Implication Undefined behavior may occur.
Resolution If PF device is reconfigured and reloaded, ensure to stop and start the qatmgr.
Affected OS Linux
Driver/Module CPM-IA - General

Resolved Issues

Resolved issues relating to the Intel® QAT software are described in this section.

Issue ID Description
QATE-76698 GEN - Multi-process applications running in guest will fail when running with default Policy settings.
QATE-99637 GEN - QAT instances on PCI domains other than 0000 are inaccessible.
QATE-99638 GEN - Incompatible service to ring configuration with non in-tree QAT kernel modules.
QATE-98551 GEN - On a multi-socket platform, there can be a performance degradation on the remote sockets.
QATE-41707 CY - Incorrect digest returned when performing a plain hash operation on input data of size 4GB or larger.
QATE-97977 DC - 'Unable to get the physical address of Data Integrity buffer' error may be observed when using user-provided address translation functions.
QATE-94369 GEN - SELinux Preventing QAT Service Startup.
QATE-94286 GEN - Compression services not detected when crypto-capable VFs are added to VM.
QATE-95905 GEN - Fix build when building outside of main directory, issue #56
QATE-93844 DC - cpaDcLZ4SCompressBound is not returning correct value, which could lead to a buffer overflow.
QATE-93278 GEN - sample_code potential seg-fault, issue #46
QATE-90845 GEN - QAT service fails to start, issue #38
QATE-78459 DC - cpaDcDeflateCompressBound API returns incorrect output buffer size when input size exceeds 477218588 bytes.
QATE-76846 GEN - Forking and re-initializing use-cases do not work
QATE-12241 CY - TLS1.2 with secret key lengths greater than 64 are not supported.

QATE-76698

Title GEN - Multi-process applications running in guest will fail when running with default Policy settings.
Reference # QATE-76698
Description The default Policy setting results in the first process receiving all available VFs allocated to a guest operating system if the BDFs on the guest do not facilitate qatlib recognising which VFs are from the same PF. In the case of a multi-process application, failures will be observed if all available QAT resources are consumed by the first process. 
Implication Multi-process applications running in guest OS may fail with default Policy settings.
Resolution Follow the guidance for specifying guest BDFs here.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-99637

Title QAT instances on PCI domains other than 0000 are inaccessible.
Reference # QATE-99637
Description On multi-domain systems, QuickAssist Technology (QAT) devices that are assigned to PCI domains with identifiers other than the default '0000' are not recognized by the system. Consequently, the QAT instances associated with these devices do not appear available for use or configuration.
Implication The inability to access QAT instances on non-default PCI domains prevents the utilization of QAT devices in those domains. This limitation restricts the deployment of QAT in environments with complex PCI topologies and can lead to under utilization of available hardware acceleration resources.
Resolution Fixed in 24.09
Affected OS Linux
Driver/Module CPM-IA - General

QATE-99638

Title Incompatible service to ring configuration with non in-tree QAT kernel modules.
Reference # QATE-99638
Description QATlib assumes a ring layout corresponding to ring configuration defaults used by the in-tree QAT kernel driver. This assumption is invalid if qatlib is running on a guest and the host has some other QAT kernel driver, e.g. an out-of-tree driver or ESXi driver, which may use different ring configurations. This affects configurations such as ASYM;DC and SYM;DC. All kernel drivers provide ring2service information via pfvfcomms, qatlib should query this rather than rely on an assumed ring layout.
Implication Crypto or compression operations will fail if sent to a ring which doesn’t handle that service.
Resolution Fixed in 24.09
Affected OS Linux OOT, ESXi, Windows Server
Driver/Module CPM-IA - General

QATE-98551

Title GEN - On a multi-socket platform, there can be a performance degradation on the remote sockets.
Reference # QATE-98551
Description On a multi-socket platform, there can be a performance degradation on remote sockets. This can arise when either the threads are not affinitised to the core on the socket the device is on and/or the memory is not allocated on the appropriate NUMA node.
Implication Performance on socket 0 is as expected, but does not scale proportionally on remote sockets.
Resolution Fixed in 24.09
Affected OS Linux
Driver/Module CPM-IA - General

QATE-41707

Title CY - Incorrect digest returned when performing a plain hash operation on input data of size 4GB or larger.
Reference # QATE-41707
Description When performing a plain hash operation on input data size of 4GB or larger, incorrect digest is returned.
Implication Incorrect digest is returned from a plain hash operation.
Resolution Fixed in 24.09
Affected OS Linux
Driver/Module CPM-IA - Crypto

QATE-97977

Title DC - 'Unable to get the physical address of Data Integrity buffer' error may be observed when using user-provided address translation functions.
Reference # QATE-97977
Description When using Integrity CRC feature (integrityCrcCheck in CpaDcOpData) and also user provided address translation functions (cpaDcSetAddressTranslation) the above error may be observed.
Implication Compression request operations may fail in this scenario.
Resolution Fixed in 24.02
Affected OS Linux
Driver/Module CPM-IA - Data Compression

QATE-94369

Title GEN - SELinux Preventing QAT Service Startup
Reference # QATE-94369
Description The qat service fails to start due to SELinux preventing the qat_init.sh script and qatmgr from accessing resources. The issue occurs when the system is running with SELinux enabled, causing insufficient permissions for the qat_init.sh script and qatmgr to function correctly.
Implication This issue affects the proper functioning of the qat service on systems with SELinux enabled, potentially preventing QAT virtual functions (VFs) from functioning.
Resolution The fix is not in the scope of qatlib. Instead there are three possible methods to handle this issue:
1) Update selinux-policy as seen in https://github.com/fedora-selinux/selinux-policy/pull/1992
2) Disable SElinux
3) Update mode to SElinux mode to permissive using following commands:
semanage permissive -a qatlib_exec_t
semanage permissive -a qatlib_t
The audit warnings may be generated, but qatlib will be allowed access to vfio devices.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-94286

Title GEN - Compression services not detected when crypto-capable VFs are also added to VM.
Reference # QATE-94286
Description When configuring a system with different services on different QAT end-points, e.g. asym;sym on one and dc on another, and exposing only one of those Virtual Function (VF) types to the Virtual Machine (VM), the application works as expected. However, when VFs of more than one type are passed to the same VM, the application may only recognize one service-type, e.g. it may detect crypto instances, but not compression instances. There is an assumption that all VFs provide the same services if they come from the same PF. However, detecting which PF they come from is based on domain+bus, which is not always a valid assumption on a VM.
Implication This issue prevents the detection of compression services in a virtualized environment when the default kernel configuration is used, and crypto and dc VFs are passed to the VM, potentially impacting the proper functioning of the system.
Resolution Fixed in 23.11
Affected OS Linux
Driver/Module CPM-IA - General

QATE-95905

Title GEN - Fix build when building outside of main directory, issue #56
Reference # QATE-95905
Description Fix build when building outside of main directory. Added changes to autoconfig to be able to build outside main directory. See issue 56.
Implication A fatal error occurs when trying to build outside main directory.
Resolution Fixed in 23.11.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-93844

Title DC - cpaDcLZ4SCompressBound is not returning correct value, which could lead to a buffer overflow.
Reference # QATE-93844
Description CompressBound API (cpaDcLZ4SCompressBound()) is intended to return the maximum size of the output buffer. However, this API is not returning the correct value, which can lead to a lz4s buffer overflow. 
Implication Applications may experience buffer overflows even when using the output of compressBound API to allocate output buffers.
Resolution Fixed in 23.11
Affected OS Linux
Driver/Module QAT IA - Compression

QATE-93278

Title GEN - sample_code potential seg-fault, issue #46
Reference # QATE-93278
Description cpa_dc_stateless_multi_op_checksum_sample.c missed checking the return value of a memory allocation. See issue 46.
Implication In a low memory system, if the memory allocation fails, the process could crash.
Resolution Fixed in qatlib 23.08.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-90845

Title GEN - QAT service fails to start, issue #38
Reference # QATE-90845
Description QAT service fails to start. The qat service may fail if the kernel driver's initialization is not fully finished when the service starts. See issue 38.
Implication The qatmgr may not detect any or all of the vfio devices.
Resolution Fixed in 23.08. The service waits until the kernel driver has completed initialization of all PFs before starting the service.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-78459

Title DC - cpaDcDeflateCompressBound API returns incorrect output buffer size when input size exceeds 477218588 bytes.
Reference # QATE-74786
Description When cpaDcDeflateCompressBound API is called with input size > 477218588 bytes incorrect buffer size is returned. For any buffer input size, the API should not produce output buffer size greater than the max limit (4 GB).
Implication Incorrect output buffer size is returned instead of error.
Resolution The issue is not present in qatlib.
Affected OS Linux
Driver/Module CPM-IA - Data Compression

QATE-76846

Title GEN - Forking and re-initializing use-cases do not work
Reference # QATE-76846
Description Forking and re-initializing use-cases do not work:
-icp_sal_userStart()/icp_sal_userStop()/icp_sal_userStart() in single process
-icp_sal_userStart()/fork()/icp_sal_userStart() in child.
This is the use case in openssh + QAT_Engine.
Implication The process will have undefined behavior in these use-cases.
Resolution Fixed in 21.08. If using release prior to this release and using these flows, call qaeMemDestroy() immediately after icp_sal_userStop() to prevent this issue.
Affected OS Linux
Driver/Module CPM-IA - General

QATE-12241

Title CY - TLS1.2 with secret key lengths greater than 64 are not supported
Reference # QATE-12241
Description Algorithms, as with Diffie-Hellman using 8K parameters that can use a secret key length greater than 64 bytes is not supported.
Implication Key generation would fail for TLS1.2 algorithms that use more than 64 bytes secret length keys.
Resolution Fixed in 22.07.
Affected OS Linux
Driver/Module CPM-IA - Crypto

Licensing

Legal

Intel, Intel Atom, and Xeon are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Copyright © 2016-2022, Intel Corporation. All rights reserved.

Terminology

Term Description
API Application Programming Interface
BIOS Basic Input/Output System
BSD Berkeley Standard Distribution
CY Cryptographic
CnV Compress and Verify
CnVnR Compress and Verify and Recover
DC Compression
DMA Direct Memory Access
EFI Extensible Firmware Interface
FW Firmware
GPL General Public License
HKDF HMAC-based Extract-and-Expand Key Derivation Function
Intel® QAT Intel® QuickAssist Technology
OS Operating System
SR-IOV Single-root Input/Output Virtualization
TLS Transport Layer Security
VFs Virtual Functions