POSIX User Space

If you want to build the leancrypto shared library, use the provided Meson build system:

1. Setup: meson setup build

2. Compile: meson compile -C build

3. Test: meson test -C build --suite regression

4. Install: meson install -C build

Testing

The leancrypto build system contains the following types of testing. To execute all tests in unison, invoke meson test -C build:

• Regression testing: invoked with meson test -C build --suite regression

• Performance testing: invoked with meson test -C build --suite performance

Limiting the Size of leancrypto

Using Meson, the leancrypto library can be limited in size by deselecting the different algorithms not required. With the following command, all options can be listed:

meson configure build

Each option can be deselected by using the meson command meson configure build -D<option>=disabled.

However, some dependencies exist which are reported by Meson. For example, SHA-3 support is needed for all post-quantum algorithms.

NOTE: All offered options are considered to be selectable independent of each other, except when Meson complains. However, unfortunately it is not feasible to test all permutations. Thus, it is possible that some permutations of options may cause compilation errors. If you spot such, please report them at the Github Issue Tracker to have them resolved.

Example: Compiling Post-Quantum-Algorithms Only

The following command disables all algorithms except the post-quantum asymmetric algorithms approved by NIST with their composite algorithms and including all relevant accelerations: see build-scripts/pqc-only.sh.

Example: Compiling ML-KEM 1024 Support Only

The following command disables all algorithms except ML-KEM 1024 without the hybrid algorithms, but including all relevant accelerations: see build-scripts/mlkem1024-only.sh.

Example: Compiling SHA2-256 Support Only

The following command disables all algorithms except SHA2-256 including all relevant accelerations which yields a shared library of 43kBytes on Intel 64-bit systems: see build-scripts/sha256_only.sh.

Linux Kernel

The leancrypto library is intended to provide the identical services for user space as well as Linux kernel space. This shall allow developers to only have one crypto provider which they need to maintain and learn to develop with.

The user space and kernel space versions of leancrypto are fully independent of each other. Neither requires the presence of the other for full operation.

Leancrypto therefore can be compiled into a separate Linux kernel module called leancrypto.ko.

The status of the leancrypto library is presented with the /proc/leancrypto interface.

Building - Without DKMS

The leancrypto library can also be built as an independent Linux kernel module. This kernel module offers the same APIs and functions as the user space version of the library. This implies that a developer wanting to develop kernel and user space users of cryptographic mechanisms do not need to adjust to a new API.

Note: The user space and kernel space versions of leancrypto are fully independent of each other. Neither requires the presence of the other for full operation.

To build the leancrypto Linux kernel module, use the Makefile in the directory linux_kernel:

1. cd linux_kernel

2. make

3. the leancrypto library is provided with leancrypto.ko

The API specified by the header files installed as part of the meson install -C build command for the user space library is applicable to the kernel module as well. When compiling kernel code, the flag -DLINUX_KERNEL needs to be set.

Building - With DKMS

Please read the steps outlined in dkms.conf found in the root directory.

Building - In-Tree Statically Bound into Linux Kernel

When the use of leancrypto as a kernel module is insufficient, e.g. when its services is required during boot time such as for kernel module integrity verification, it can be compiled statically into the kernel binary. To do that, the following steps have to be taken:

1. Copy the entire leancrypto tree into the Linux kernel source tree into the directory leancrypto:

   cp -av leancrypto-<version> linux-<version>/leancrypto

2. Tell the Linux kernel build system to also use leancrypto by editing the file Kbuild found in the root of the Linux kernel tree and add the following line at the end of that file:

   obj-y += leancrypto/linux_kernel/

3. Tell leancrypto to be compiled statically into the kernel by editing the file leancrypto/linux_kernel/Kbuild.config and modify the option CONFIG_LEANCRYPTO to y.

At this point, leancrypto will now be built statically into the Linux kernel when compiling it. Naturally, all Linux kernel options can be set as leancrypto does not depend on specific kernel options.

You may want to consider the option CONFIG_LEANCRYPTO_TEST_MODULES found in leancrypto/linux_kernel/Kbuild.config. When setting this option, all test kernel modules are built which is usually only desired during development or validation of the library. None of these kernel modules are relevant or used in production.

Test Modules

In addition to the leancrypto.ko kernel module, a large number of additional kernel modules are compiled. They are all test modules for regression testing and are not required and even not intended for production use. Insert the kernel modules and check dmesg for the results. Unload the kernel modules afterwards.

The test modules almost all are the user space test application the meson test framework uses too, but compiled into kernel modules. They invoke the leancrypto API to demonstrate that the identical code is supported in user as well as user space.

In addition to the standard leancrypto test code, the following test modules are provided to validate the leancrypto integration into the kernel crypto API:

• leancrypto_kernel_aead_ascon_tester.ko invokes the Linux kernel crypto API of type aead to perform a Ascon and Ascon-Keccak encryption / decryption operation.

• leancrypto_kernel_aes_gcm_tester.ko invokes the Linux kernel crypto API of type aead to perform an AES-GCM encryption / decryption operation.

• leancrypto_kernel_ascon_tester.ko invokes the Linux kernel crypto API of type shash to perform a Ascon-Hash256 message digest calculation.

• leancrypto_kernel_dilithium*_tester.ko invokes the Linux kernel crypto API of type akcipher to perform a FIPS 204 (CRYSTALS Dilithium) signature generation and verification.

• leancrypto_kernel_sphincs_shake_*_tester.ko invokes the Linux kernel crypto API of type akcipher to perform a FIPS 205 (Sphincs Plus) signature generation and verification.

• leancrypto_kernel_kmac_tester.ko invokes the Linux kernel crypto API type shash to invoke KMAC256 XOF, a keyed message digest using FIPS 202 defined in SP800-185.

• leancrypto_kernel_kyber*_tester.ko tests the Linux kernel crypto API type kpp to invoke FIPS 203 (CRYSTALS Kyber) key generation, encapsulation and decapsulation.

• leancrypto_kernel_rng_tester.ko invokes the Linux kernel crypto API type rng to utilize the XDRBG256 deterministic random number generator.

• leancrypto_kernel_sha3_tester.ko performs the testing of leancrypto’s SHA-3 implementation which is registered as a shash.

• leancrypto_kernel_sha256_tester.ko performs the testing of leancrypto’s SHA2-256 implementation which is registered as a shash.

• leancrypto_kernel_sha512_tester.ko performs the testing of leancrypto’s SHA2-512 implementation which is registered as a shash.

Leancrypto Registered with the Linux Kernel Crypto API

The leancrypto.ko offers its own API interface as discussed above. In addition, it registers a subset of algorithms with the kernel crypto API to allow other kernel users, that already use the kernel crypto API for its purposes, to use the algorithms of the leancrypto library without further changes. All algorithms adhere to the kernel crypto API standards and should be usable out of the box.

For the ML-KEM (CRYSTALS Kyber) as well as the HQC support, some special precautions need to be applied considering that there are two modes of operation a user must be aware of: acting as an Initiator or a Responder of a Kyber / HQC key agreement. This consideration is identical to the one that needs to be applied for (EC)Diffie-Hellman. The following listing enumerates the call sequence the user must apply for the given mode. The following sequences for both, the initiator and the responder is implemented in leancrypto_kernel_kyber_tester.c as a reference.

• Acting as Initiator of a ML-KEM / HQC operation:

  1. Generate new keypair: crypto_kpp_set_secret(tfm, NULL, 0); Note, it is permissible to also set an externally-provided key here.

  2. Get public key: crypto_kpp_generate_public_key(req->src = NULL, req->dst = PK)

  3. Send the ML-KEM / HQC PK to the responder and retrieve the ML-KEM CT / HQC CT from the responder.

  4. Calculate shared secret: crypto_kpp_compute_shared_secret(req->src = CT, req->dst = SS)

• Acting as Responder of a ML-KEM / HQC operation:

  1. Generate new keypair: crypto_kpp_set_secret(tfm, NULL, 0); Note, it is permissible to also set an externally-provided key here.

  2. Get the initiator PK to generate the CT and shared secret: crypto_kpp_generate_public_key(req->src = PK, req->dst = CT)

  3. Send CT to the initiator

  4. Get the shared secret that was already calculated in step 2: crypto_kpp_compute_shared_secret(req->src = NULL, req->dst = SS)

Please note that the leancrypto ML-KEM / HQC support allows specifying arbitrary sizes of the shared secret (referenced as SS above). When the caller specifies a length that is not equal to 32 bytes, the leancrypto built-in KDF is applied to generate the shared secret of appropriate size.

Leancrypto Kernel Support Configuration

The kernel-compilation of leancrypto is equally flexible as the user space part and thus can still be called “lean”. It allows at compile time to enable or disable algorithms as needed.

Unfortunately, the Linux kernel build system’s graphical configuration tools cannot be used for out-of-tree modules. Thus, if changes to the set of algorithms is intended, the file Kbuild.config must be modified as follows:

The file Kbuild.config contains a configuration of the services. Simply comment out the respective symbols that are not desired to be present. The Kbuild.config file contains a description of each option including its dependencies, if any. You MUST adhere to the specified dependencies as otherwise the compilation will fail due to missing symbols.

EFI Environment

The leancrypto library is designed to run without any dependencies and thus can be used in environments like (U)EFI. To compile it for the EFI environment, configure the compilation with the following command:

meson setup build -Defi=enabled
meson compile -C build
meson compile -C build pkcs7_trust_tester.efi

The compilation uses the GNU-EFI environment and generates:

1. The static library leancrypto.a that could be bound into an EFI application compiled externally to the build environment.

2. A test application in build/efi/tests/pkcs7_trust_tester.efi which is statically linked with leancrypto.a and implements the test “PKCS7 Trust Validation - PKCS#7 with trust chain” from asn1/tests/meson.build. This application is a UEFI application:

   $ file ./build/efi/tests/pkcs7_trust_tester.efi
   ./build/efi/tests/pkcs7_trust_tester.efi: PE32+ executable for EFI (application), x86-64 (stripped to external PDB), 7 sections

Naturally, all other options offered by the meson build enviornment can be toggled for EFI support as well allowing leancrypto to be configured to implement the exact algorithms required. See POSIX user space for details about the use of options.

When programming with leancrypto in the EFI environment, the following considerations must be applied:

• The API specified by the header files installed as part of the meson install -C build command for the user space library is applicable to the EFI environment as well.

• As the EFI environment does not offer an automatic constructor functionality the leancrypto initalization function of lc_init must be called as the very first API call before calling any other leancrypto service function.

Windows User Space

The leancrypto library can be built on Windows using MSYS2. Once MSYS2 is installed along with meson and the mingw compiler, the standard compilation procedure outlined for the POSIX user space can be used.

The support for full assembler acceleration is enabled.

Building for Other Environments

If you need leancrypto to work in other environments like small embedded systems, you need:

1. Adjust the build system as needed to compile and link it

2. Adjust the file ext_headers.h to point to the right header files and locations.

3. set the flag LC_MEM_ON_HEAP if your environment only has a limited stack size. When set, functions with large memory requirements use the heap instead of the stack for this memory. The maximum stack size used by a function is 2048 bytes and is verified by a compiler check.

4. If your environment does not offer an automated constructor logic that is invoked by the compiler attribute __attribute__((constructor)) you must add the appropriate handling to visibility.h by adding an appropriate LC_CONSTRUCTOR macro. It could be as easy as making LC_CONSTRUCTOR just defining the symbol (see how this macro is defined for LC_EFI) and require that leancrypto is initialized with lc_init.

An example on the approach is given with the Linux kernel support found in the directory linux_kernel.