Documentation of Crypto Multi-buffer Library was updated. Position Independent Execution (PIE) option was added to Crypto Multi-buffer Library build scripts.

ElenaTyuleneva · ElenaTyuleneva · commit 21a202306409 · 2020-04-21T12:41:17.000+03:00
diff --git a/BUILD.md b/BUILD.md
@@ -1,4 +1,4 @@
-# How to Build Intel® IPP Cryptography <!-- omit in toc -->
+# How to Build Intel® Integrated Performance Primitives Cryptography (Intel® IPP Cryptography) <!-- omit in toc -->
 
 - [Software Requirements](#software-requirements)
   - [Common](#common)
@@ -17,7 +17,7 @@
   - [How to build a 64-bit generic library without any CPU-specific optimizations?](#how-to-build-a-64-bit-generic-library-without-any-cpu-specific-optimizations)
   - [How to build two libraries with optimizations for Intel® Advanced Vector Extensions 2 and Intel® Advanced Vector Extensions 512 instruction sets?](#how-to-build-two-libraries-with-optimizations-for-intel%c2%ae-advanced-vector-extensions-2-and-intel%c2%ae-advanced-vector-extensions-512-instruction-sets)
   - [How to build a library to work in a kernel space?](#how-to-build-a-library-to-work-in-a-kernel-space)
-- [Incorporating Intel® IPP Cryptography sources into custom build system](#incorporating-intel%c2%ae-ipp-cryptography-sources-into-custom-build-system)
+- [Incorporating Intel IPP Cryptography sources into custom build system](#incorporating-intel%c2%ae-ipp-cryptography-sources-into-custom-build-system)
 
 ## Software Requirements
 ### Common
@@ -54,7 +54,7 @@ To build the Intel IPP Cryptography library on Linux\* OS, complete the followin
 
 2. Set the environment for one of the supported C/C++ compilers.
 
-   *Example for Intel(R) Compiler:*
+   *Example for Intel® Compiler:*
 
     ```bash
     source /opt/intel/bin/compilervars.sh intel64
@@ -267,17 +267,17 @@ add_executable("test_proj" main.cpp)
 target_link_libraries("test_proj" "ippcp_s")
 ```
 
-Also you can use CMake module to find the IPP Crypto library installed on the system. The module location is `examples/FindIPPCrypto.cmake` and here is the example of its usage:
+Also you can use CMake module to find the Intel IPP Cryptography library installed on the system. The module location is `examples/FindIPPCrypto.cmake` and here is the example of its usage:
 
 ``` bash
 find_package(IPPCrypto REQUIRED MODULE)
 
 if (NOT IPPCRYPTO_FOUND)
-   message(FATAL_ERROR "No Intel(R) IPP Cryptography library found on the system.")
+   message(FATAL_ERROR "No Intel IPP Cryptography library found on the system.")
 endif()
 
 # If Intel IPP Cryptography is found, the following variables will be defined:
 #     `IPPCRYPTO_LIBRARIES` - static library name
-#     `IPPCRYPTO_INCLUDE_DIRS` - path to IPP Crypto headers
+#     `IPPCRYPTO_INCLUDE_DIRS` - path to Intel IPP Cryptography headers
 #     `IPPCRYPTO_ROOT_DIR` - library root dir (a folder with 'include' and 'lib' directories)
-```
+```
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,11 +1,15 @@
-# Intel(R) Integrated Performance Primitives Cryptography (Intel(R) IPP Cryptography)
+# Intel® Integrated Performance Primitives Cryptography (Intel® IPP Cryptography)
 
 This is a list of notable changes to Intel(R) IPP Cryptography, in reverse chronological order.
 
+## 2020-04-21
+- Documentation of Crypto Multi-buffer Library was updated.
+- Position Independent Execution (PIE) option was added to Crypto Multi-buffer Library build scripts.
+
 ## 2020-04-19
 - AES-XTS optimization for Ice Lake with vector extensions of Intel(R) AES New Instructions (Intel(R) AES-NI) was improved.
 - Fixed a build issue that affect build of the Intel(R) IPP Crypto library with MSVC\* compiler on Windows\* OS.
-- Duplicated APIs of HASH, HMAC, MGF, RSA, ECCP functionality were marked as deprecated.For more information see [Deprecation notes](./DEPRECATION_NOTES.md)
+- Duplicated APIs of HASH, HMAC, MGF, RSA, ECCP functionality were marked as deprecated. For more information see [Deprecation notes](./DEPRECATION_NOTES.md)
 - Added examples demonstrating usage of SMS4-CBC encryption and decryption.
 
 ## 2020-02-25
@@ -29,11 +33,11 @@ This is a list of notable changes to Intel(R) IPP Cryptography, in reverse chron
 ## 2019-08-27
 - Added Intel(R) IPP Cryptography library examples: AES-CTR, RSA-OAEP, RSA-PSS.
 - Fixed code generation for kernel code model in Linux* Intel(R) 64 non-PIC builds.
-- Fixes in Intel(R) IPP Custom Library Tool.
+- Fixes in Intel IPP Custom Library Tool.
 
 ## 2019-07-23
 - Added Microsoft\* Visual Studio\* 2019 build support.
-- Added Intel(R) IPP Custom Library Tool.
+- Added Intel IPP Custom Library Tool.
 
 ## 2019-06-24
 - AES-GCM was enabled with vector extensions of Intel(R) AES New Instructions (Intel(R) AES-NI).
diff --git a/OVERVIEW.md b/OVERVIEW.md
@@ -142,7 +142,7 @@ The corresponding build target names for the libraries are shown at the picture
 
 Be default, the Intel IPP Cryptography library is built with the [Position Independent Code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code) option.
 
-But on Linux* OS, when the library is supposed to work in kernel space, it is possible to compile the static library in a non-PIC mode. For more information about build options, refer to the [Linux* OS build options](./INSTALL.txt).
+But on Linux* OS, when the library is supposed to work in kernel space, it is possible to compile the static library in a non-PIC mode. For more information about build options, refer to the [Linux* OS build options](./BUILD.md).
 
 ### Target Instruction Set Architecture (ISA)
 
diff --git a/sources/ippcp/crypto_mb/Readme.md b/sources/ippcp/crypto_mb/Readme.md
@@ -1,41 +1,118 @@
-# RSA IFMA Muti-buffer Library
+# Crypto Multi-buffer Library
 
-It is a library separate from Intel IPP Cryptography. The library provides optimized version of RSA multi-buffer based on Intel(R) Advanced Vector Extensions 512 (Intel(R) AVX-512) Integer Fused Multiply Add (IFMA). Currently, the library is compatible with OpenSSL\* only.
+Currently, the library provides optimized version of RSA multi-buffer encryption and decryption algorithms based on Intel® Advanced Vector Extensions 512 (Intel® AVX-512) integer fused multiply-add (IFMA) operations. This CPU feature is introduced with Intel® Microarchitecture Code Named Ice Lake.
 
-## System Requirements
+## Multiple Buffers Processing Overview
 
-The library build process was tested on the following operating systems and tools:
-- Linux\* OS
-- GCC\* 8.2
-- CMake\* 3.12
-- Python\* 2.7.16
+Some of the cryptography algorithms cannot be parallelized due to their specificity. For example, the RSA algorithm consists of big-number (multi-digit) arithmetic: multi-precision modular multiplications and squaring operations.
+
+Digits of multi-digit numbers are dependent because of carry propagation during arithmetic operations. Therefore, single RSA computation based on general purpose mul/adc instructions is not efficient.
+
+The way to get high-performance implementations of such cryptographic algorithms is a parallel processing using *single instruction, multiple data* (SIMD) architecture. The usage model implies presence of several independent and homogeneous (encryption or decryption) requests for RSA operations, using of SIMD leads to performance improvement.
+
+Multi-buffer processing collects up to eight RSA operations. Each request is computed independently from the others, so it is possible to process several packets at the same time.
+
+This library consists of highly-optimized kernels taking advantage of Intel’s multi-buffer processing and Intel® AVX-512 instruction set.
+
+## Software Requirements
+
+### Common
+
+- CMake\* 3.10 or higher
+- The Netwide Assembler (NASM) 2.14\*
 - OpenSSL\* 1.1.0
 
-## Building from Source
+### Linux* OS
 
-1. Clone the repository and navigate to the `sources/ippcp/ifma_rsa_mb` folder.
+- Intel® C++ Compiler 19.0 Update 4 for Linux\* OS
+- GCC 8.2
+- Clang 9
+- GNU binutils 2.32
 
-2. Run CMake on the command line. Example CMake lines and avaliable options:
+### Windows* OS
 
-Use `-B` to specify path to the resulting project. Do not specify any additional options to use Python and OpenSSL from default system paths:
-```
-cmake . -B../build
-```
+- Intel® C++ Compiler 19.0 Update 4 for Windows\* OS
+- Microsoft Visual C++ Compiler\* version 19.16 provided by Microsoft Visual Studio\* 2017 version 15.9
 
-Use `PYTHON_EXECUTABLE` variable to override path to Python:
-```
-cmake . -B../build -DPYTHON_EXECUTABLE=/path/to/python27
-```
+### macOS*
 
-Use `OPENSSL_INCLUDE_DIR`, `OPENSSL_LIBRARIES` and `OPENSSL_ROOT_DIR` variables to override path to OpenSSL:
-```
-cmake . -B../build -DOPENSSL_INCLUDE_DIR=/path/to/openssl/include -DOPENSSL_LIBRARIES=/path/to/openssl/lib -DOPENSSL_ROOT_DIR=/path/to/openssl
-```
+- Intel® C++ Compiler 19.0 Update 4 for macOS\*
+
+## Installation
+
+You can install the Crypto Multi-buffer library in two different ways:
+1. Installation to the default directories.  
+   > **Note**: To run this installation type, you need to have appropriate permissions to write to the installation directory.
 
-3. Go to the project folder that was specified with `-B` and run `make` to build the library (`librsa_ifma` target) and, optionally, tests (`vfy_ifma_rsa_mb`, `vfy_ifma_cp_rsa_mb` targets). The resulting binaries will be placed in the `bin` subfolder inside the build folder.
+   Default locations (default values of `CMAKE_INSTALL_PREFIX`):
+   - Unix:  /usr/local
+   - Windows: C:\Program Files\crypto_mb or C:\Program Files (x86)\crypto_mb
+   
+   To begin installation, run the command below in the project folder that was specified with `-B`:
+   ``` bash
+   make install
+   ```
 
-Example:
+2. Installation to your own directory.  
+   If you want to install the library not by default paths, specify the `CMAKE_INSTALL_PREFIX` variable at the configuration step, for example:
+   ``` bash
+   cmake . -B"../build" -DCMAKE_INSTALL_PREFIX=path/to/libcrypto_mb/installation
+   ```
+
+You can find the installed files in:
+
+``` bash
+
+├── ${CMAKE_INSTALL_PREFIX}
+    ├── include
+    |    └── crypto_mb
+    │        ├── ed25519_ifma.h
+    │        ├── ifma_method.h
+    │        ├── rsa_ifma.h
+    │        ├── rsa_ifma_cp.h
+    │        ├── rsa_ifma_defs.h
+    │        └── rsa_ifma_status.h
+    └── lib
+        └── libcrypto_mb.a
 ```
-make -j8
-./bin/vfy_ifma_rsa_mb
+## How to Build
+
+You can build the library in two ways:
+- Using universal building, which can be used with any target API (in particular, with Intel® Integrated Performance Primitives (Intel® IPP) Cryptography\* API)
+- Using the OpenSSL\* library
+
+### Universal building
+
+1. Clone the repository from GitHub\* as follows:
+
+   ``` bash
+   git clone --recursive https://github.com/intel/ipp-crypto
+   ```
+   and navigate to the `sources/ippcp/crypto_mb` folder.
+2. Set the environment variables for one of the supported C/C++ compilers.
+3. Run CMake on the command line. Use `-B` to specify path to the resulting project and define the variable `-DBN_OPENSSL_DISABLE` to exclude all the OpenSSL dependencies:
+
+   ``` bash
+   cmake . -B"../build" -DBN_OPENSSL_DISABLE
+   ```
+4. Go to the project folder that was specified with `-B` and run `make` to build the library (`libcrypto_mb` target) and, optionally, tests (`vfy_ifma_rsa_mb` and `vfy_ifma_cp_rsa_mb` targets).
+
+### Building with Intel® IPP Cryptography library
+
+To get access to the optimized kernels through Intel® IPP Cryptography API, build the Intel® IPP Cryptography library as it is described in [Intel IPP Cryptography Build Instructions](../../../BUILD.md). The Crypto IFMA Multi-buffer library will be built automatically if optimization for Intel® Microarchitecture Code Named Ice Lake is available.
+
+### Building with OpenSSL\*
+
+The only difference from universal building is the availability of additional options: `OPENSSL_INCLUDE_DIR`, `OPENSSL_LIBRARIES` and `OPENSSL_ROOT_DIR`.  
+Use them to override path to OpenSSL\*:
+
+``` bash
+cmake . -B"../build"  
+-DOPENSSL_INCLUDE_DIR=/path/to/openssl/include  
+-DOPENSSL_LIBRARIES=/path/to/openssl/lib  
+-DOPENSSL_ROOT_DIR=/path/to/openssl
 ```
+
+## Usage Examples
+
+You can find the examples of usage of the optimized kernels with Intel IPP Cryptography\* API in the `<ipp-crypto-dir>/examples/rsa_mb` folder.
diff --git a/sources/ippcp/crypto_mb/src/CMakeLists.txt b/sources/ippcp/crypto_mb/src/CMakeLists.txt
@@ -52,7 +52,7 @@ set_source_files_properties(${RSA_AVX512_SOURCES} ${COMMON_SOURCES} ${ECDSA_SOUR
 # Library
 add_library(${IFMA_LIB_TARGET} STATIC ${RSA_AVX512_SOURCES} ${COMMON_SOURCES} ${ED25519_SOURCES})  
 if(NOT BN_OPENSSL_DISABLE)
-    target_link_libraries(${IFMA_LIB_TARGET} OpenSSL::Crypto) # to get includes
+    target_link_libraries(${IFMA_LIB_TARGET} OpenSSL::Crypto)
 else()
     set_target_properties(${IFMA_LIB_TARGET} PROPERTIES COMPILE_DEFINITIONS "BN_OPENSSL_DISABLE")
 endif()
diff --git a/sources/ippcp/crypto_mb/src/cmake/linux/Clang.cmake b/sources/ippcp/crypto_mb/src/cmake/linux/Clang.cmake
@@ -26,6 +26,11 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -falign-functions=32")
 # Optimization level = 3
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3")
 
+if(NOT BN_OPENSSL_DISABLE)
+    # Position Independent Execution (PIE)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fpic -fPIC")
+endif()
+
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_CXX_FLAGS}")
 
 # Suppress warnings from casts from a pointer to an integer type of a different size
diff --git a/sources/ippcp/crypto_mb/src/cmake/linux/GNU.cmake b/sources/ippcp/crypto_mb/src/cmake/linux/GNU.cmake
@@ -25,6 +25,11 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -falign-functions=32 -falign-loops=32")
 # Optimization level = 3
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3")
 
+if(NOT BN_OPENSSL_DISABLE)
+    # Position Independent Execution (PIE)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fpic -fPIC")
+endif()
+
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_CXX_FLAGS}")
 
 # Suppress warnings from casts from a pointer to an integer type of a different size
diff --git a/sources/ippcp/crypto_mb/src/cmake/linux/Intel.cmake b/sources/ippcp/crypto_mb/src/cmake/linux/Intel.cmake
@@ -25,6 +25,11 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -falign-functions=32 -falign-loops=32")
 # Optimization level = 3
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3")
 
+if(NOT BN_OPENSSL_DISABLE)
+    # Position Independent Execution (PIE)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fpic -fPIC")
+endif()
+
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_CXX_FLAGS}")
 
 # Suppress warnings from casts from a pointer to an integer type of a different size
diff --git a/sources/ippcp/crypto_mb/src/cmake/macosx/Intel.cmake b/sources/ippcp/crypto_mb/src/cmake/macosx/Intel.cmake
@@ -25,6 +25,11 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -falign-functions=32 -falign-loops=32")
 # Optimization level = 3
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3")
 
+if(NOT BN_OPENSSL_DISABLE)
+    # Position Independent Execution (PIE)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fpic -fPIC")
+endif()
+
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_CXX_FLAGS}")
 
 # Suppress warnings from casts from a pointer to an integer type of a different size
