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
   CMAKE_BUILD_TYPE (Debug/Release)	Specify the build type
   ENABLE_AOCL_UTILS (ON/OFF)	Enable Zen architecture based dynamic dispatch using the AOCL-Utils library
   AOCL_UTILS_INSTALL_DIR	AOCL-Utils library installation path
   OPENSSL_INSTALL_DIR	OpenSSL (3.0.8 through 3.3.0) installation path
   CMAKE_INSTALL_PREFIX	AOCL-Cryptography library installation path
   ALCP_SANITIZE (ON/OFF)	Enable sanitizers to compile the library (asan, ubsan, , and so on)
   AOCL_COMPAT_LIBS	Supported values= ipp,openssl/ipp/openssl Enable compilation of IPP OpenSSL provider libraries. Notes: The IPP header files should be added to the CPLUS_INCLUDE_PATH environment variable (working version for IPP is 2021_10.0). OpenSSL provider support is only enabled for Cipher, CMAC, Poly1305, and RSA Algorithms in 5.0 release.s. IPP provider support is experimental in 5.0 release
   OPENSSL_INSTALL_DIR	Path to openssl installation directory (Supported openssl versions are 3.0.8 through 3.3.0)
   ALCP_ENABLE_HTML	Values: ON/OFF Enable ALCP html documentation generation. Note: Doxygen version supported: v1.9.6 or later.
   ALCP_ENABLE_DOCS	Values: ON/OFF Generate PDFs from .MD files using Pandoc utility (Note: Needs the proprietary font “Klavika” to be installed in the system)
   AOCL_UTILS_INSTALL_DIR	Path to AOCL Utils installation directory (If not provided, build system will compile and install aocl utils library from the latest release branch.

7. make -j$(nproc)

8. make install

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.

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.

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.0.8 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:

https://docs.amd.com/go/en-US/63862-AOCL-cryptography

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

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