Refactor README with additional information.

- Refactor Installation instructions and testing - Add Application Integration & Case Studies - Fix typos & Update requirements, Limitations & Troubleshooting section. Signed-off-by: Yogaraj Alamenda <[email protected]>
intel · Jul 26, 2024 · b109a0a · b109a0a
1 parent 00077c2
commit b109a0a
Show file tree

Hide file tree

Showing 18 changed files with 650 additions and 964 deletions.
diff --git a/README.md b/README.md
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,7 +1,8 @@
 # Security Policy
+Intel&reg; is committed to rapidly addressing security vulnerabilities
+affecting our customers and providing clear guidance on the solution,
+impact, severity and mitigation.
 
-## Reporting a Security Vulnerability
-
-Visit https://intel.com/security for information on how to report a
-security vulnerability and the Intel Bug Bounty Program. Do not report
-any security vulnerability as a regular issue in this repository.
+## Reporting a Vulnerability
+Please report any security vulnerabilities in this project utilizing
+the guidelines [here](https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html).
diff --git a/docs/additional_information.md b/docs/additional_information.md
diff --git a/docs/apps.md b/docs/apps.md
@@ -0,0 +1,41 @@
+## Application Integration
+### Asynchronous Mode Nginx\* with QAT
+NGINX\* with asynchronous mode for Intel&reg; OpenSSL QAT Engine provides
+significant performance improvement with QAT acceleration.
+The asynchronous fork of NGINX\* can be found at the following Github\*
+repository:
+
+* [Intel&reg; QuickAssist Technology (QAT) Async Mode NGINX\*](https://github.com/intel/asynch_mode_nginx)
+
+Follow the below link on how to enable Async mode Nginx\* with QAT Hardware and software
+Aceeleration using best known configuration.
+[Async mode for Nginx\*](https://intel.github.io/quickassist/qatlib/asynch_nginx.html)
+
+### NGINX\* QUIC with QAT
+Experimental QUIC support for NGINX\* with Intel&reg; QAT Engine for
+BoringSSL\* Library can be found [here](https://www.intel.com/content/www/us/en/content-details/737522/experimental-quic-support-for-nginx.html)
+
+### HAProxy\* with QAT
+HAProxy\* is a free, very fast and reliable reverse-proxy offering high availability,
+load balancing, and proxying for TCP and HTTP-based applications.
+
+Follow the instructions from HAProxy [Install](https://github.com/haproxy/haproxy/blob/master/INSTALL)
+to build and install Haproxy. Use `USE_PTHREAD_EMULATION=1` option in the make command which improves performance
+utilizing HAProxy's much lighter locks replacing OpensSL\* Pthread locks.
+
+Add the following options along with other standard settings in the
+HAProxy\* [Configuration File](https://www.haproxy.com/documentation/haproxy-configuration-manual/latest)
+to utilize QAT Acceleration.
+
+```bash
+ssl-engine qatengine algo ALL
+ssl-mode-async
+```
+
+## Case Studies
+* [Intel&reg; QuickAssist Technology and OpenSSL-1.1.0:Performance](https://www.intel.com/content/www/us/en/content-details/709581/intel-quickassist-technology-and-openssl-1-1-0-performance.html)
+* [Intel® QuickAssist Technology - NGINX\* Performance White Paper](https://networkbuilders.intel.com/solutionslibrary/intel-quickassist-technology-nginx-performance-white-paper)
+* [Accelerate HAProxy\* with Intel QAT](https://www.intel.com/content/www/us/en/content-details/814574/accelerating-haproxy-with-intel-quickassist-technology.html)
+
+Other Application Integration and more case studies can be found at QAT link below
+* [Intel® QuickAssist Technology (Intel® QAT)](https://www.intel.com/content/www/us/en/developer/topic-technology/open/quick-assist-technology/overview.html)
diff --git a/docs/bssl_support.md b/docs/bssl_support.md
@@ -1,7 +1,7 @@
-# Intel® QuickAssist Technology(QAT) BoringSSL* Library
-Intel® QuickAssist Technology BoringSSL* Library is a prototype accelerating asymmetric cryptographic algorithms for BoringSSL*, the Google*'s OpenSSL* fork which doesn't support engine mechanism. It checks the type of user input SSL library during configuration time and builds out a traditional engine library if OpenSSL* is detected or a library fitting in with BoringSSL* private key method if BoringSSL* is applied.
+# Intel® QuickAssist Technology(QAT) BoringSSL\* Library
+Intel® QuickAssist Technology BoringSSL\* Library is a prototype accelerating asymmetric cryptographic algorithms for BoringSSL\*, the Google\*'s OpenSSL\* fork which doesn't support engine mechanism. It checks the type of user input SSL library during configuration time and builds out a traditional engine library if OpenSSL\* is detected or a library fitting in with BoringSSL\* private key method if BoringSSL\* is applied.
 
-This document details the capabilities, interfaces and limitations of the BoringSSL* based library. Both the hardware and software requirements are explained followed by detailed instructions on how to install and use the library.
+This document details the capabilities, interfaces and limitations of the BoringSSL\* based library. Both the hardware and software requirements are explained followed by detailed instructions on how to install and use the library.
 
 ## Features
 - Asynchronous and Synchronous PKE QAT_HW Acceleration
@@ -12,91 +12,81 @@ This document details the capabilities, interfaces and limitations of the Boring
   - ECDSA Support for NIST Prime Curves: P-256/P-384.(Disabled by default)
 
 ## Limitations
-Some limitations specific for the current BoringSSL* Library:
-* NIST Binary Curves and NIST Koblitz Curves are not supported by BoringSSL.
+Some limitations specific for the current BoringSSL\* Library:
+* NIST Binary Curves and NIST Koblitz Curves are not supported by BoringSSL\.
 * Supports QAT_HW and QAT_SW on Linux. QAT_SW and QAT_HW FreeBSD is not supported.
-* `RSA_padding_add_PKCS1_OAEP` function is exported by BoringSSL `libdecrepit.so`,
-so it needs to be linked in the BoringSSL* Library. It may cause linking error while
+* `RSA_padding_add_PKCS1_OAEP` function is exported by BoringSSL\* `libdecrepit.so`,
+so it needs to be linked in the BoringSSL\* Library. It may cause linking error while
 building with the system lack of that library.
 
 ## Requirements
 - [Hardware Requirements](hardware_requirements.md)
 - [Software Requirements](software_requirements.md)
 
 ## Installation
-### Install Prerequisites
-Refer to the [Install Prerequisites](../README.md##installation-instructions)
-
-**Note:** Replace the OpenSSL with BoringSSL installation described below.
-
 ### Build BoringSSL
 
-Clone BoringSSL* from Github* at the following location:
-```bash
-git clone https://github.com/google/boringssl.git
 ```
-
-Navigate to BoringSSL directory:
-```bash
-cd <path/to/boringssl/source/code>
+git clone https://github.com/google/boringssl.git
+cd boringssl
 mkdir -p build
 cd build/
 ```
 
-Note: BoringSSL* builds static library by default. To align with the QAT_Engine use case within NGINX*, an explicit option is added to build it as a dynamic library.
-  ```bash
-  cmake .. -DBUILD_SHARED_LIBS=1 -DCMAKE_BUILD_TYPE=Release
-  make
-  ```
-
-BoringSSL* doesn't support "make install" to consolidate build output to an appropriate location. Here is a solution to integrate all output libraries into one customized path 'lib' by symbol links.
-  ```bash
-  cd ..
-  mkdir -p lib
-  ln -sf $(pwd)/build/libboringssl_gtest.so lib/
-  ln -sf $(pwd)/build/crypto/libcrypto.so lib/
-  ln -sf $(pwd)/build/ssl/libssl.so lib/
-  ln -sf $(pwd)/build/decrepit/libdecrepit.so lib/
-  ```
+Note: BoringSSL\* builds static library by default. To align with the QAT_Engine use case within NGINX\*, an explicit option is added to build it as a dynamic library.
+```
+cmake .. -DBUILD_SHARED_LIBS=1 -DCMAKE_BUILD_TYPE=Release
+make
+```
 
-Note: RSA Padding schemes are handled by BoringSSL* rather than accelerated, so the engine supports the same padding schemes as BoringSSL* does natively.
+BoringSSL\* doesn't support "make install" to consolidate build output to an appropriate location. Here is a solution to integrate all output libraries into one customized path 'lib' by symbol links.
+```
+cd ..
+mkdir -p lib
+ln -sf $(pwd)/build/libboringssl_gtest.so lib/
+ln -sf $(pwd)/build/crypto/libcrypto.so lib/
+ln -sf $(pwd)/build/ssl/libssl.so lib/
+ln -sf $(pwd)/build/decrepit/libdecrepit.so lib/
+```
 
-### Build the Intel® QuickAssist Technology BoringSSL* Library
+Note: RSA Padding schemes are handled by BoringSSL\* rather than accelerated, so the engine supports the same padding schemes as BoringSSL\* does natively.
 
-  The prerequisite to run autogen.sh is to have autotools (autoconf, automake, libtool and pkg-config) installed in the system.
-  ```bash
-  cd <path/to/qat_engine/source/code>
-  ./autogen.sh
-  ```
-  Note: autogen.sh will regenerate autoconf tools files.
+### Build the Intel® QuickAssist Technology BoringSSL\* Library
 
-  To build and install the Intel® QAT_HW BoringSSL* Library:
-  ```bash
-  ./configure --with-openssl_install_dir=<path/to/boringssl/source/code> --with-qat_hw_dir=<path/to/qat/driver>
-  make
-  make install
-  ```
-  To build and install the Intel® QAT_SW BoringSSL* Library:
-  ```bash
-  ./configure --enable-qat_sw --with-openssl_install_dir=<path/to/boringssl/source/code>
-  make
-  make install
-  ```
-  In the above example, `--disable-qat_hw` needs to be provided if the system
-  has qatlib installed.
-  Note : `--enable-qat_sw` checks crypto_mb and IPSec_MB libraries in its
-  respective default path (/usr/local/lib and /usr/lib) or in the path provided
-  in the config flag `--with-qat_sw_crypto_mb_install_dir` (for crypto_mb) and
-  `--with-qat_sw_ipsec_mb_install_dir` (for ipsec_mb). If any of the libraries
-  is not installed then their corresponding algorithm support is disabled.
-  By here, the QAT BoringSSL* Library `libqatengine.so` is installed to system path `/usr/local/lib`. Set the `--prefix` if specific install path is expected.
+The prerequisite to run autogen.sh is to have autotools (autoconf, automake, libtool and pkg-config) installed in the system.
+```
+cd <path/to/qat_engine/source/code>
+./autogen.sh
+```
 
-### Test the Intel® QuickAssist Technology BoringSSL* Library
+To build and install the Intel® QAT_HW BoringSSL\* Library:
+```
+./configure --with-openssl_install_dir=<path/to/boringssl/source/code> --with-qat_hw_dir=<path/to/qat/driver>
+make
+install
+```
+To build and install the Intel® QAT_SW BoringSSL\* Library:
+```
+./configure --enable-qat_sw --with-openssl_install_dir=<path/to/boringssl/source/code>
+make
+make install
+```
+In the above example, `--disable-qat_hw` needs to be provided if the system
+has qatlib installed.
+Note : `--enable-qat_sw` checks crypto_mb and IPSec_MB libraries in its
+respective default path (/usr/local/lib and /usr/lib) or in the path provided
+in the config flag `--with-qat_sw_crypto_mb_install_dir` (for crypto_mb) and
+`--with-qat_sw_ipsec_mb_install_dir` (for ipsec_mb). If any of the libraries
+is not installed then their corresponding algorithm support is disabled.
+By here, the QAT BoringSSL\* Library `libqatengine.so` is installed to
+system path `/usr/local/lib`. Set the `--prefix` if specific install path is expected.
+
+### Test the Intel® QuickAssist Technology BoringSSL\* Library
 
 The test code is under `test_bssl/` directory and will be compiled along with this library.
 
 - Get usage help by running `qatengine_test` with `-h` option
-    ```bash
+    ```
     # ./qatengine_test -h
     Usage: ./qatengine_test [-h/-d/-a] <-k>
     -a :    Enable async mode

diff --git a/docs/config_options.md b/docs/config_options.md
@@ -54,7 +54,7 @@ The following is a list of the options that can be used with the
     the in-tree driver even though QAT SW acceleration is enabled via
     use of the '--enable-qat_sw' option, if both capabilities are
     available (both QAT HW or QAT SW) then QAT HW acceleration will
-    be used by default. However, use of this --disable-qat_hw option will
+    be used by default. However, use of this `--disable-qat_hw` option will
     force the use of QAT SW acceleration.
 
 ```

diff --git a/docs/features.md b/docs/features.md
@@ -1,63 +1,64 @@
 # Features
 
 ## qat_hw Features
-* Synchronous and [Asynchronous](async_job.md) Operation
-* Asymmetric PKE Acceleration
-    * RSA Support for Key Sizes 512/1024/2048/4096.
-    * DH Support for Key Sizes 768/1024/1536/2048/3072/4096.
-    * DSA Support for Key Sizes 160/1024, 224/2048, 256/2048, 256/3072.
-    * ECDH Support for the following curves:
+* Asymmetric PKE
+    * RSA for Key Sizes 512/1024/2048/4096/8192.
+    * DH for Key Sizes 768/1024/1536/2048/3072/4096/8192.
+    * DSA for Key Sizes 160/1024, 224/2048, 256/2048, 256/3072.
+    * ECDH for the following curves:
         * NIST Prime Curves: P-192/P-224/P-256/P-384/P-521.
         * NIST Binary Curves: B-163/B-233/B-283/B-409/B-571.
         * NIST Koblitz Curves: K-163/K-233/K-283/K-409/K-571.
         * Montgomery EC Curves: X25519/X448 (ECX).
-    * ECDSA Support for the following curves:
+    * ECDSA for the following curves:
         * NIST Prime Curves: P-192/P-224/P-256/P-384/P-521.
         * NIST Binary Curves: B-163/B-233/B-283/B-409/B-571.
         * NIST Koblitz Curves: K-163/K-233/K-283/K-409/K-571.
-* Symmetric Chained Cipher acceleration with pipelining capability:
+    * SM2
+* Symmetric Ciphers
     * AES128-CBC-HMAC-SHA1/AES256-CBC-HMAC-SHA1.
     * AES128-CBC-HMAC-SHA256/AES256-CBC-HMAC-SHA256.
-* Symmetric ciphers AES128-CCM, AES128-GCM and AES256-GCM
-* Pseudo Random Function (PRF) Acceleration.
-* [HMAC Key Derivation Function (HKDF) Acceleration.](qat_hw.md#intel-qat-openssl-engine-hkdf-support)
+    * AES128-CCM, AES192-CCM, AES256-CCM.
+    * AES128-GCM, AES256-GCM.
+    * ChaCha20-Poly1305
+    * SM4-CBC
+* Key Derivation 
+    * PRF
+    * HKDF
+* Hashing
+    * SHA3-224/256/384/512
+    * SM3
+* Synchronous and [Asynchronous](async_job.md) Operation
 * [Pipelined Operations](qat_hw.md#using-the-openssl-pipelining-capability)
 * [Intel&reg; QAT OpenSSL\* Engine Software Fallback](qat_hw.md#intel-qat-openssl-engine-software-fallback-feature)
-* [BoringSSL Support](bssl_support.md)
-* Algorithms specific to QAT Hardware driver v2.0 and qatlib(QAT gen4 devices)
-  *  RSA8K
-  *  DH8K
-  *  SM4-CBC (Not supported in qatlib)
-  *  SHA3-224/256/384/512
-  *  ChaCha20-Poly1305
-  *  SM2 (Not supported in qatlib)
-  *  SM3 (Not supported in qatlib)
-  *  AES128-CCM, AES192-CCM and AES256-CCM
 * [Key Protection Technology (KPT) Support using QAT_HW driver v2.0](qat_hw_kpt.md)
 
-Please refer [here](qat_hw_algo.md) for supported platforms list and default behaviour.
+Please refer [here](qat_hw_algo.md) for applicable QAT Hardware versions and algorithms enabled by default.
 
 ## qat_sw Features
-* [Intel&reg; QAT Software Acceleration for Asymmetric PKE and AES-GCM](qat_sw.md)
-    * RSA Support for Key size 2048, 3072, 4096
-    * ECDH Support for the following curves:
+* [Intel&reg; QAT Software Acceleration](qat_sw.md)
+* Asymmetric PKE
+    * RSA for Key size 2048, 3072, 4096
+    * ECDH for the following curves:
         * Montgomery EC Curve: X25519
         * NIST Prime Curves: P-256/P-384
         * SM2
-    * ECDSA Support for the following curves:
+    * ECDSA for the following curves:
         * NIST Prime Curves: P-256/P-384
         * SM2
-    * SM3 Hash Support using 16 Multibuffer requests (Experimental)
-    * SM4-CBC Support using 16 Multibuffer requests (Tongsuo only)
-    * SM4-GCM Support using 16 Multibuffer requests (Tongsuo only)
-    * SM4-CCM Support using 16 Multibuffer requests (Tongsuo only)
+* Symmetric Ciphers
     * AES128-GCM, AES192-GCM and AES256-GCM
+    * SM4-CBC using 16 Multibuffer requests (Tongsuo only)
+    * SM4-GCM using 16 Multibuffer requests (Tongsuo only)
+    * SM4-CCM using 16 Multibuffer requests (Tongsuo only)
+* Hashing
+    * SM3 Hash using 16 Multibuffer requests (Experimental)
 
 ## Common Features to qat_hw & qat_sw
-* [QAT_HW & QAT_SW Co-existence with runtime configuration](qat_coex.md#qat-hw-and-qat-sw-co-existence)
+* [BoringSSL Support](bssl_support.md)
 * [OpenSSL 3.0 Provider Support](qat_common.md#openssl-30-provider-support)
-* [FIPS 140-3 Certification requirements Support using QAT Provider](qat_common.md#fips-140-3-certification-requirements-support-using-qat-provider)
-* [Binary RPM Package](qat_common.md#binary-rpm-package)
+* [QAT_HW & QAT_SW Co-existence](qat_coex.md#qat-hw-and-qat-sw-co-existence)
+* [FIPS 140-3 Certification](qat_common.md#fips-140-3-certification)
 
 Note: RSA Padding schemes are handled by OpenSSL\* or BoringSSL\* rather than accelerated, so the
 engine supports the same padding schemes as OpenSSL\* or BoringSSL\* does natively.
diff --git a/docs/hardware_requirements.md b/docs/hardware_requirements.md
@@ -1,21 +1,15 @@
 # Hardware Requirements
 
-## qat_hw Requirements
-
-This Intel&reg; QAT OpenSSL\* Engine supports crypto Hardware acceleration to the following
-acceleration devices:
-
-* [Intel® Xeon® Scalable Processor family with Intel® QAT Gen4/Gen4m][1]
+QAT_HW acceleration is supported on the platforms with the following QAT devices
+* [Intel® QuickAssist 4xxx Series][1]
 * [Intel® QuickAssist Adapter 8970][2]
 * [Intel® QuickAssist Adapter 8960][3]
 * [Intel® QuickAssist Adapter 8950][4]
-* [Intel&reg; Atom&trade; Processor C3000][5]
-
-## qat_sw Requirements
+* [Intel® Atom&trade; Processor C3000][5]
 
-The [qat_sw features](features.md#qat_sw-features) are only supported in the platforms starting with [3rd Generation Intel&reg; Xeon&reg; Scalable Processors family][6] and later.
+QAT_SW acceleration is supported in the platforms starting with [3rd Generation Intel&reg; Xeon&reg; Scalable Processors family][6] and later.
 
-[1]:https://www.intel.com/content/www/us/en/products/docs/processors/xeon-accelerated/4th-gen-xeon-scalable-processors.html
+[1]:https://www.intel.com/content/www/us/en/products/details/processors/xeon/scalable.html
 [2]:https://www.intel.com/content/www/us/en/products/sku/125200/intel-quickassist-adapter-8970/downloads.html
 [3]:https://www.intel.com/content/www/us/en/products/sku/125199/intel-quickassist-adapter-8960/downloads.html
 [4]:https://www.intel.com/content/www/us/en/products/sku/80371/intel-communications-chipset-8950/specifications.html

diff --git a/docs/images/qat_engine.png b/docs/images/qat_engine.png