Sources

Github.com

leancrypto is developed at its Github repository.

Releases

Releases of leancrypto are avaiable at the release page as well as at the Github release site.

Releases

• leancrypto version 0.11.0

• leancrypto version 0.10.1

• leancrypto version 0.10.0

• leancrypto version 0.9.2

• leancrypto version 0.9.1

• leancrypto version 0.9.0

• leancrypto version 0.8.0

• leancrypto version 0.7.0

• leancrypto version 0.6.0

• leancrypto version 0.5.3

• leancrypto version 0.5.2

• leancrypto version 0.5.1

• leancrypto version 0.5.0

• leancrypto version 0.4.0

• leancrypto version 0.3.0

Build Instructions

Building User Space Library

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

Building Linux Kernel Library

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.

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.

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.

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

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.

Building

In the linux_kernel directory, the support for building the leancrypto library is provided. To build the leancrypto Linux kernel module, use the Makefile in that directory:

1. make

2. the leancrypto library is provided with leancrypto.ko

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 skcipher to perform a Ascon and Ascon-Keccak encryption / decryption operation.

• leancrypto_kernel_ascon_tester.ko invokes the Linux kernel crypto API of type shash to perform a Ascon 128 and Ascon 128a 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 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 CRYSTALS Kyber 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 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 Kyber KEM 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 Kyber PK to the responder and retrieve the Kyber CT from the responder.

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

• Acting as Responder of a Kyber KEM 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 Kyber 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.

Cryptographic Algorithms

Leancrypto offers various cryptographic algorithms:

• Authenticated Encryption with Associated Data

  • Ascon 128 AEAD and Ascon 128a AEAD

  • Ascon Keccak 256 and 512 AEAD, see Ascon-Keccak for full specification

  • cSHAKE-based AEAD algorithm - algorithm devised with leancrypto, see cSHAKE-AEAD for full specification

  • hash-based AEAD algorithm - algorithm devised with leancrypto, see hash_crypt.c for full specification

  • KMAC-based AEAD algorithm - algorithm devised with leancrypto, see KMAC-AEAD for full specification

  • AES-based AEAD algorithm using SHA2 - see symhmac_crypt.c for full specification

  • AES-based AEAD algorithm using Keccak-based KMAC - see symkmac_crypt.c for full specification

• Pseudo Random Number Generators

  • XDRBG256 and XDRBG128 - see XDRBG specification for full specification and proof

  • cSHAKE-based PRNG - see cshake_drng.c for full specification - it complies with the XDRBG specification

  • KMAC-based PRNG - see kmac_drng.c for full specification - it complies with the XDRBG specification

  • SHAKE-based PRNG

  • SP800-90A Hash and HMAC DRBG

  • ChaCha20-based PRNG - see https://www.chronox.de/lrng for specification

• Message Digest algorithms

  • SHA2-256, SHA2-512

  • SHA3-224, SHA3-256, SHA3-384, SHA3-512

  • SHAKE-128, SHAKE-256

  • cSHAKE-128, cSHAKE-256

  • Ascon 128 / 128a

  • Ascon XOF / XOFa

• Keyed Message Digest algorithms

  • HMAC

  • KMAC

• Key Derivation Functions

  • HKDF

  • SP800-108 KDF (counter, feedback, double pipelining mode)

  • PBKDF2

• Key Encapsulation Mechanism

  • ML-KEM (Kyber) Key Encapsulation Mechanism (KEM)

  • ML-KEM (Kyber) Key Exchange Mechanism (KEX)

  • ML-KEM (Kyber) Integrated Encryption Schema (IES)

  • ML-KEM (Kyber) hybrid KEM / KEX with Curve25519

  • BIKE Key Encapsulation Mechanism (KEM)

• One Time Pad algorithms

  • HOTP

  • TOTP

• Signature algorithm

  • ML-DSA (Dilithium) including HashML-DSA

  • ML-DSA (Dilithium) hybrid signature operation with Curve25519

  • SLH-DSA (Sphincs+) including HashSLH-DSA

• Symmetric algorithms

  • AES: ECB, CBC, CTR, KW

  • ChaCha20

Leancrypto API Documentation

Doxygen Documentation

The Doxygen Documentation is automatically generated during the compilation of the source code if the doxygen binary is found on the host system.

API Documentation in Header Files

The leancrypto API is documented in the exported header files. The only header file that needs to be included in the target code is #include <leancrypto.h>. This header file includes all algorithm-specific header files for the compiled and supported algorithms.

To fully understand the API, please consider the following base concept of leancrypto: Different algorithm implementations are accessible via common APIs. For example, different random number generator algorithms are accessible via the RNG API. To ensure the common APIs act on the proper algorithm, the caller must use algorithm-specific initialization functions. The initialization logic returns a “cipher handle” that can be used with the common API for all subequent operations.

The various header files contain data structures which are provided solely for the purpose that appropriate memory on stack can be allocated. These data structures do not consititute an API in the sense that calling applications should access member variables directly. If access to member variables is desired, proper accessor functions are available. This implies that changes to the data structures in newer versions of the library are not considered as API changes!

The following list enumerates all algorithm-specific header files which contains the respective API documentation:

• AEAD Algorithms:

  • Main API: lc_aead.h

  • Ascon AEAD: lc_ascon_lightweight.h

  • Ascon-Keccak AEAD: lc_ascon_keccak.h

  • cSHAKE AEAD: lc_cshake_crypt.h

  • Hash-based AEAD: lc_hash_crypt.h

  • KMAC-based AEAD lc_kmac_crypt.h

  • Symmetric algorithm + HMAC AEAD: lc_symhmac.h

  • Symmetric algorithm + KMAC AEAD: lc_symkmac.h

• Deterministic RNGs:

  • Main API: lc_rng.h

  • ChaCha20-based DRNG: lc_chacha20_drng.h

  • KMAC-based DRNG: lc_kmac256_drng.h

  • cSHAKE-based DRNG: lc_cshake256_drng.h

  • XDRBG-based DRNG: lc_xdrbg.h

  • SP800-90A Hash-based DRBG: lc_hash_drbg.h

  • SP800-90A HMAC-based DRBG: lc_hmac_drbg_sha512.h

• Message Digests:

  • Main API: lc_hash.h

  • SHA2-256: lc_sha256.h

  • SHA2-512: lc_sha512.h

  • cSHAKE support: lc_cshake.h

  • SHA-3, SHAKE, cSHAKE: lc_sha3.h

• Key-Derivation Function:

  • RFC5869 HKDF: lc_hkdf.h

  • SP800-108 counter KDF: lc_kdf_ctr.h

  • SP800-108 feedback KDF: lc_kdf_fb.h

  • SP800-108 double-pipeline KDF: lc_kdf_dpi.h

  • SP880-132 PBKDF2: lc_pbkdf2.h

• Key Encapsulation Mechanisms:

  • FIPS 203 ML-KEM / Kyber: lc_kyber.h

  • BIKE: lc_bike.h

• One-time Pads:

  • HOTP: lc_hotp.h

  • TOTP: lc_totp.h

• Signature Algorithms:

  • FIPS 204 ML-DSA / Dilithium: lc_dilithium.h

  • FIPS 205 SLH-DSA / Sphincs+: lc_sphincs.h

• Symmetric Algorithms:

  • Main API: lc_sym.h

  • ChaCha20: lc_chacha20.h

  • AES: lc_aes.h

• Keyed Message Digests:

  • FIPS 198 HMAC: lc_hmac.h

  • SP800-185 KMAC: lc_kmac.h

• Helper Functions:

  • Constant-time memcmp: lc_memcmp_secure.h

  • Secure memset: lc_memset_secure.h

  • Status API: lc_status.h

Example Code

Almost all test cases found in the various tests directories use the aforementioned public APIs and thus serve as example code for the given algorithms.

Debugging Support

The leancrypto library offers various types of debugging support outlined in the following sections.

Kyber / Dilithium: Print Results of Intermediate Calculation Steps

An implementation that is compliant with the NIST implementation that complies with FIPS 203 draft as well as additional changes expressed by NIST at the PQC-Forum is provided with leancrypto. It allows developers to compile both Kyber and Dilithium in a debug mode where the calculation results of each step of the key generation, Kyber encapsulation and decapsulation, as well as the Dilithium signature generation and verification can be displayed. This allows other developers to compare their implementation to match with leancrypto. The following steps have to be taken to obtain the debug output after fetching the library from the provided link and making sure the meson build system is available:

Kyber:

1. Setup of the build directory: meson setup build

2. Configure Kyber debug mode: meson configure build -Dkyber_debug=enabled

3. Compile the code: meson compile -C build

4. Execute the test tool providing the output of Kyber, ML-KEM-1024: build/kem/tests/kyber_kem_tester_c

5. Execute the test tool providing the output of Kyber, ML-KEM-768: build/kem/tests/kyber_768_kem_tester_c

6. Execute the test tool providing the output of Kyber, ML-KEM-512: build/kem/tests/kyber_512_kem_tester_c

Dilithium:

1. Setup of the build directory (if it was not already set up for the Kyber tests): meson setup build

2. Configure Dilithium debug mode: meson configure build -Ddilithium_debug=enabled`

3. Compile the code: meson compile -C build

4. Execute the test tool providing the output of Dilithium, ML-DSA-87: build/signature/tests/dilithium_tester_c

5. Execute the test tool providing the output of Dilithium, ML-DSA-65: build/signature/tests/dilithium_65_tester_c

6. Execute the test tool providing the output of Dilithium, ML-DSA-44: build/signature/tests/dilithium_44_tester_c

The test tool outputs is segmented into the key generation steps, Dilithium signature generation and verification steps, as well as Kyber encapsulation and decapsulation steps. The output specifies the mathematical operation whose result is shown. When displaying the output of a vector, one line is used. When displaying a matrix, the output of one row of the matrix is displayed per line. This implies that as many lines are printed as rows are present in the matrix.

During the course of the development of both Kyber and Dilithium reference implementations, NIST developers reached out to compare intermediate results of both algorithms with the ones produced by leancrypto. The debug logging information was used as a basis for the discussion with the NIST development team to verify that both implementations i.e. the NIST reference implementation as well as leancrypto, correspond.

Side-Channel Analysis

Side channels is a recurring problem which can inadvertently leak sensitive data where the leak may be visible not just locally, but possibly also remotely. Thus, finding side channels based on sensitive data is important.

The leancrypto library has built-in support for finding side-channels (or the lack thereof) by marking memory holding sensitive data and using Valgrind to identify any possible side channels. The concept is summarized on the Timecop web page as follows:

Even though modern CPUs and operating systems have various methods to separate processes from one another, some side-channels can remain that allow attackers to extract information across process, CPU, or even network boundaries.

One such side-channel can open up when the execution time of a piece of code depends on secret data. This class of vulnerabilities has been used succesfully in the past to extract encryption keys from AES, private keys from RSA, and other kinds of attacks.

Timing side-channels can be hard to spot in the wild, but they can be detected automatically to some degree with dynamic analysis.

How it works

Most timing side-channels are rooted in one of the following three causes:

• Conditional jumps based on secret data [1] e.g. if (key[i] == 0)

• Table lookups at secret indices [2], [3], [4], [5] e.g. s[i] = substitution_table[key[i]]

• Variable-time CPU instructions operating on secret data [6], e.g. key[i] / c On Intel Pentium 4, the number of cycles for a division instruction depends on the arguments.

Adam Langley described in 2010 how the first two types can be detected automatically using Valgrind.

Valgrind is a framework for dynamic code analysis that comes with a large range of tools for specific analysis tasks. One of those tools checks memory usage to identify memory leaks, use of uninitialized memory, read after free, and other common problems related to memory management.

When Valgrind checks for the use of uninitialized memory, it performs exactly the checks necessary to spot timing side-channels. By flagging secret data as uninitialized for Valgrind, it will report any cases where conditional jumps or table lookups are based on secret data.

Limitations

Valgrind cannot spot cases where variable-time code is caused by variable-time CPU instructions.

Testing Instructions

To perform such a side channel analysis, apply the following steps:

1. Configure leancrypto with the following option: meson configure build -Dtimecop=enabled

2. Compile the code

3. Execute different test cases with Valgrind as follows: valgrind --track-origins=yes build/kem/tests/kyber_kem_tester_common

4. A side channel is present if Valgrind reports an issue like the following where it reports a “Conditional jump or move depends on uninitialised value(s)” based on “Uninitialised value was created by a client request”:

==13317== Conditional jump or move depends on uninitialised value(s)
==13317==    at 0x4851A2E: bcmp (in /usr/libexec/valgrind/vgpreload_memcheck-amd64-linux.so)
==13317==    by 0x10A86F: lc_compare (../internal/src/compare.c:52)
==13317==    by 0x10A6A8: _kmac_256_tester (../kmac/tests/kmac_256_tester.c:912)
==13317==    by 0x10A410: kmac_tester (../kmac/tests/kmac_256_tester.c:942)
==13317==    by 0x10A410: main (???:956)
==13317==  Uninitialised value was created by a client request
==13317==    at 0x48A0E7A: lc_kmac_init (../kmac/src/kmac.c:119)
==13317==    by 0x10A665: _kmac_256_tester (../kmac/tests/kmac_256_tester.c:909)
==13317==    by 0x10A410: kmac_tester (../kmac/tests/kmac_256_tester.c:942)
==13317==    by 0x10A410: main (???:956)

References

[1] Onur Acıiçmez, Çetin Kaya Koç, Jean-Pierre Seifert, Predicting secret keys via branch prediction. In Proceedings of the 7th Cryptographers’ Track at the RSA Conference on Topics in Cryptology

[2] Yuval Yarom, Katrina Falkner, FLUSH+RELOAD: a High Resolution, Low Noise, L3 Cache Side-Channel Attack.

[3] Daniel J. Bernstein, Cache-timing attacks on AES.

[4] Paul C. Kocher, Timing Attacks in Implementations of Diffie-Hellman, RSA, DSS, and Other Systems.

[5] Mehmet Sinan İnci, Berk Gülmezoğlu, Gorka Irazoqui, Thomas Eisenbarth, Berk Sunar, Seriously, get off my cloud! Cross-VM RSA Key Recovery in a Public Cloud.

[6] Thierry Kaufmann, Hervé Pelletier, Serge Vaudenay, and Karine Villegas When Constant-time Source Yields Variable-time Binary: Exploiting Curve25519-donna Built with MSVC 2015.

CAVP Certificates

The leancrypto library is tested with the NIST ACVP framework and received the following certificates.

The testing was conducted using the ACVP Parser.

Version 1.1.0

leancrypto CAVP Certificates

Version 1.0.1

leancrypto CAVP certificates

Version 1.0.0

This version obtained the first ever ML-DSA and ML-KEM CAVP certificates!

leancrypto CAVP certificates

Version 0.8.0

• A4850 non-accelerated C cipher implementations

• A4866 AVX2 accelerated cipher implementations

• A4867 Intel 4-way SIMD accelerated cipher implementations

• A4864 AVX512 accelerated cipher implementations

• A4865 AES-NI accelerated cipher implementations

• A4851 RISC-V assembler cipher implementations

• A4852 ARMv8 assembler cipher implementations

• A4853 ARMv8 Crypto Extensions cipher implementations

• A4854 ARMv8 2-way SIMD accelerated cipher implementations

• A4860 ARMv7 NEON cipher implementations

Version 0.7.0

• A4405 non-accelerated C cipher implementations

• A4409 AVX2 accelerated cipher implementations

• A4410 4-way SIMD accelerated cipher implementations

• A4413 AVX512 accelerated cipher implementations

• A4411 AES-NI accelerated cipher implementations

• A4408 RISC-V assembler cipher implementations

• A4407 ARMv8 assembler cipher implementations

• A4412 ARMv8 Crypto Extensions cipher implementations

• A4406 ARMv7 NEON cipher implementations

Version 0.6.0

• A3770 non-accelerated C cipher implementations

• A3771 AVX2 accelerated cipher implementations

• A3772 4-way SIMD accelerated cipher implementations

• A3773 AVX512 accelerated cipher implementations

• A3774 AES-NI accelerated cipher implementations

• A3775 RISC-V assembler cipher implementations

• A3776 ARMv8 assembler cipher implementations

• A3777 ARMv8 Crypto Extensions cipher implementations

• A3778 ARMv7 NEON cipher implementations