Lean Crypto Library

The leancrypto library is a cryptographic library that exclusively contains only PQC-resistant cryptographic algorithms. It is lean in every of its properties listed in the following:

• minimal dependencies: only minimal POSIX environment needed - function calls are abstracted into helper code that may need to be replaced for other environments (see the Linux kernel support in linux_kernel for replacing the POSIX calls)

• extractable: the algorithms can be extracted and compiled as part of a separate project,

• flexible: you can disable algorithms on an as-needed basis using meson configure,

• fully thread-safe when using different cipher contexts for an invocation: there is no global state maintained for the algorithms,

• stack-only support: all algorithms can be allocated on stack if needed. In addition, allocation functions for a usage on heap is also supported,

• size: minimizing footprint when statically linking by supporting dead-code stripping,

• performance: provide optimized code invoked with minimal overhead,

• testable: all algorithm implementations are directly accessible via their data structures at runtime, and

• side-channel-resistant: A valgrind-based dynamic side channel analysis is applied to find time-variant code paths based on secret data.

The one go-to library usable in any environment - validate it once and use it for all workloads. Currently supported envionments:

• User space (POSIX environments like Linux, macOS, BSDs; Windows)

• Kernel space (Linux including registration into kernel crypto API)

• EFI (including secure boot)

• Rust

Status

Type | Service | Status --- | --- | --- Linux User Space | GitHub | Linux Kernel Space | GitHub | macOS User Space | GitHub | Small Stack | GitHub | ASAN Address Check | GitHub | Codacy Scan | GitHub | Windows User Space | GitHub | Side-Channel Analysis | GitHub | Static Code Analysis | GitHub | Compile Reduced LC | GitHub | EFI compilation | GitHub | Rust | GitHub | FIPS140 Negative | GitHub | No Acceleration | GitHub |

Library Build

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

4. Install: meson install -C build

Library Build for Linux Kernel - 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

Note, the compiled test kernel modules are only provided for regression testing and are not required for production use. Insert the kernel modules and check dmesg for the results. Unload the kernel modules afterwards.

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.

For more details, see linux_kernel/README.md.

Library Build for Linux Kernel - With DKMS

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

Library Build for 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.

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 initialization function of lc_init must be called as the very first API call before calling any other leancrypto service function.

Library Build for Windows

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 above for meson can be used.

The support for full assembler acceleration is enabled.

Library Build 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.

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

Library Build Using Profile Guided Optimization

Using profile guided optimization with GCC is a two phase operation. First, et up leancrypto with profile measurements enabled and compile it.

meson setup build -Db_pgo=generate
meson compile -C build

Then execute the test environment with the regression test suite to create representative input:

meson test -C build --suite regressio