13.2.1. Building AOCL-Cryptography from Source on Linux#

Complete the following steps to build AOCL-Cryptography from source on Linux:

1. GitHub URL: amd/aocl-crypto

2. Clone the repository aocl-crypto.

3. cd aocl-crypto

4. mkdir build

5. cd build

6. Run the configure command cmake ../ using the following options:

   Table 13.1 AOCL-Cryptography - Linux Options#

   Option	Description
   ALCP_ENABLE_EXAMPLES (ON/OFF)	Compile the example code (default: ON)
   CMAKE_BUILD_TYPE (Debug/Release)	Specify the build type (default: Release)
   ENABLE_AOCL_UTILS (ON/OFF)	Enable Zen architecture based dynamic dispatch using the AOCL-Utils library (default: ON)
   AOCL_UTILS_INSTALL_DIR	AOCL-Utils library installation path installation path (if not provided, build system picks and compiles aocl-utils from latest release branch)
   OPENSSL_INSTALL_DIR	OpenSSL (3.1.3 through 3.3.0) installation path (if not given, compilation will fail)
   CMAKE_INSTALL_PREFIX	AOCL-Cryptography library installation path (Default: CMake default install path)
   ALCP_SANITIZE (ON/OFF)	Enable sanitizers in compilation (asan, ubsan, and so on). (Default: OFF)
   AOCL_COMPAT_LIBS	Supported values=ipp,openssl/ipp/openssl (Default: “”) Enable compilation of IPP compat and OpenSSL provider libraries. Notes: The IPP header files should be added to the environment variable (working version for IPP is 2021_10.0). OpenSSL provider support is enabled for Cipher (all modes except AES CBC and CCM), Digest (only SHA3 and SHAKE algorithms), CMAC, Poly1305, and RSA Algorithms in 5.1 release. IPP provider support is experimental in 5.1 release
   ALCP_ENABLE_HTML (ON/OFF)	Enable html documentation generation (Default: OFF)
   ALCP_ENABLE_TESTS (ON/OFF)	Compile AOCL-Crypto Integration Tests (Default: OFF)
   ENABLE_TESTS_OPENSSL_API(ON/OFF)	Use OpenSSL API calls in tests and bench (Default: OFF)
   ENABLE_TESTS_IPP_API (ON/OFF)	Use IPP CP API calls in tests and bench (Default: OFF)
   IPP_INSTALL_DIR (ON/OFF)	Provide IPPCP Installation path (Default: ” “)
   ALCP_MEMCHECK_VALGRIND (ON/OFF)	Compile and Run CTEST with valgrind (Default: OFF)
   CMAKE_C_COMPILER (ON/OFF)	Provide full path to C Compiler (Default: Default CC in the environment)
   CMAKE_CXX_COMPILER (ON/OFF)	Provide full path to CXX Compiler (Default: Default CXX in the environment)
   ALCP_ENABLE_BENCH (ON/OFF)	Compile AOCL-Crypto Benchmarks (Default: OFF)
   -G (“Ninja”/ “Unix Makefiles”)	Specify the build system generator (default: Ninja)

7. make -j$(nproc)

8. make install

   For detailed steps on cmake flags and compilation steps on linux, please refer to

   build_readme_linux amd/aocl-crypto

9. To execute tests/benchmarks using KAT framework, run the following commands:

   $ git-lfs fetch
   $ git-lfs checkout
   

   For detailed steps to execute KAT tests/bench, refer to tests_Readme amd/aocl-crypto and bench_Readme amd/aocl-crypto files respectively.

Testing Examples

1. Navigate to the installed directory.

2. Ensure that AOCL and OpenSSL lib directories are added to LD_LIBRARY_PATH and LIBRARY_PATH environment variables:

$ export LD_LIBRARY_PATH=<path to aocl crypto lib>:<path to OpenSSL lib>:$LD_LIBRARY_PATH;
$ export LIBRARY_PATH=<path to aocl crypto lib>:<path to OpenSSL lib>:$LIBRARY_PATH;

3. make

4. Run the executables generated in ./bin/<module>. For example, ./bin/mac/hmac.

   For detailed steps to compile and run the examples, please refer to examples_Readme amd/aocl-crypto

Force runtime CPU architecture

• To force runtime CPU Architecture, use the environment variable ALCP_ENABLE_INSTRUCTIONS before

  running the test executable.

• The supported options are ZEN1, ZEN2, ZEN3, ZEN4 and ZEN5

• Example (to force runtime architecture as ZEN3):

  export ALCP_ENABLE_INSTRUCTIONS=ZEN3 && ./examples/cipher/Release/aes-gcm

• NOTE: You cannot force the usage of an architecture higher than the system runtime architecture. If you attempt this, the library falls back to the highest supported architecture.

13.2.2. Building AOCL-Cryptography from Source on Windows#

AOCL-Cryptography requires CMake and Microsoft Visual Studio for building the binaries from the sources on Windows.

For detailed steps on compilation flags and build on windows, please refer to

build_windows_Readme amd/aocl-crypto

Prerequisites

• For more information on CMake versions validated, refer to Build Utilities.

• Microsoft Visual Studio 2019 (build 16.8.7) through 2022 (build 17.5.3)

• Desktop development with C++: C++ Clang-tools for windows (x64 or x86)

• LLVM plug-in for Microsoft Visual Studio (if the latest version of LLVM is installed separately, this plug-in enables linking Microsoft Visual Studio with the installed LLVM toolchain)

• Install OpenSSL (3.1.3 through 3.3.0) and add openssl\bin path to the PATH environment variables, if not set

Configure and Build

1. Clone the repository aocl-crypto.

2. Open Command Prompt or PowerShell.

3. cd aocl-crypto

4. mkdir build

5. Run cmake configure using the following options:

   Table 13.2 AOCL-Cryptography - Windows Options#

   Option	Description
   -A (platform)	x86/x64
   -B (build directory)	Build
   -T (toolset)	ClangCl/LLVM
   -G (specify generator)	Visual Studio 17 2022/ Visual Studio 16 2019 / Ninja

6. Build the library:

--config=release/debug
PS>cmake --build ./build --config=release -j

7. To execute tests/benchmarks using the KAT framework, run the following commands:

   $ git-lfs fetch
   $ git-lfs checkout
   

   For detailed steps to execute KAT tests/bench, refer to tests_Readme amd/aocl-crypto and bench_Readme amd/aocl-crypto files respectively.

Testing Examples

1. Navigate to the build directory.

2. Ensure that the lib\Release directory is added to PATH environment variables.

3. If not set already, add openssl\bin path to the PATH environment variables.

4. Run the executables generated in .\examples\<module>\Release\*.exe. Example: .\examples\cipher\Release\aes-ccm.exe

13.3.1. Compiling and Running Examples#

Complete the following steps to compile and run the AOCL-Cryptography examples from the downloaded packages:

1. Download and untar the aocl-crypto package.

2. cd amd-crypto

3. export LIBRARY_PATH=<path to aocl crypto lib>:<path to aocl utils lib>:<path to openssl lib>:$LIBRARY_PATH;

4. make

5. To run example applications (for digest):

LD_LIBRARY_PATH=<path to aocl crypto lib>:<path to aocl utils
lib>:<path to openssl lib> ./bin/digest/sha2_384_example;

13.3.2. AOCL-Cryptography Library Provider for OpenSSL#

For more information on usage instructions, refer to the following URL:

amd/aocl-crypto

13.3.3. Integrating AOCL-Crypto Library with Applications that Use IPP#

For detailed instructions on using the IPP-CP Compat library, refer to the following URL:

amd/aocl-crypto

(Note: IPP Compat library is in experimental state in 5.1 release)