Build Instructions
Building User Space Library
If you want to build the leancrypto shared library, use the provided Meson
build system:
-
Setup: meson setup build
-
Compile: meson compile -C build
-
Test: meson test -C build
-
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
:
-
cd linux_kernel
-
make
-
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:
-
Adjust the build system as needed to compile and link it
-
Adjust the file ext_headers.h
to point to the right header files and
locations.
-
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:
-
make
-
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_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.
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.
Debugging Support
The leancrypto library offers various types of debugging support outlined in the following sections.
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:
-
Setup of the build directory: meson setup build
-
Configure Kyber debug mode: meson configure build -Dkyber_debug=enabled
-
Compile the code: meson compile -C build
-
Execute the test tool providing the output of Kyber, ML-KEM-1024: build/kem/tests/kyber_kem_tester_c
-
Execute the test tool providing the output of Kyber, ML-KEM-768: build/kem/tests/kyber_768_kem_tester_c
-
Execute the test tool providing the output of Kyber, ML-KEM-512: build/kem/tests/kyber_512_kem_tester_c
Dilithium:
-
Setup of the build directory (if it was not already set up for the Kyber tests): meson setup build
-
Configure Dilithium debug mode: meson configure build -Ddilithium_debug=enabled`
-
Compile the code: meson compile -C build
-
Execute the test tool providing the output of Dilithium, ML-DSA-87: build/signature/tests/dilithium_tester_c
-
Execute the test tool providing the output of Dilithium, ML-DSA-65: build/signature/tests/dilithium_65_tester_c
-
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:
-
Configure leancrypto with the following option: meson configure build -Dtimecop=enabled
-
Compile the code
-
Execute different test cases with Valgrind as follows: valgrind --track-origins=yes build/kem/tests/kyber_kem_tester_common
-
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.