MLKEM-C-EMBEDDED is a collection of MLKEM implementations optimized for embedded microcontrollers. It is free software licensed under an Apache-2.0 license.
It originates from the pqm4 project, but there are some core differences:
The goals and features of a future MLKEM-C-EMBEDDED v1.0 release include:
In the medium term, we hope to include:
In the long term, possible extensions are
div
on most platforms or umull
on Cortex-M3MLKEM-C-EMBEDDED is currently a work in progress and we do not recommend relying on it at this point. WE DO NOT CURRENTLY RECOMMEND RELYING ON THIS LIBRARY IN A PRODUCTION ENVIRONMENT OR TO PROTECT ANY SENSITIVE DATA. Once we have the first stable version, this notice will be removed
The current code is compatible with the standard
branch of the official MLKEM repository.
We are actively seeking contributors who can help us build MLKEM-C-EMBEDDED. If you are interested, please contact us, or volunteer for any of the open issues.
If you are a potential consumer of MLKEM-C-EMBEDDED, please reach out to us. We're interested in hearing the way you are considering using MLKEM-C-EMBEDDED and could benefit from additional features. If you have specific feature requests, please open an issue.
All the develop and build dependencies are specified in flake.nix.
Setup with nix,
nix develop
will execute a bash shell with the development environment specified in flake.nix.direnv
by using direnv allow
, allowing it to handle the environment setup for you.If your're not using nix, please ensure you have installed the same version as specified in flake.nix.
For further details, please refer to scripts/README.md
The build system compiles tests and benchmarks for each mlkem parameter set on specified platform, supported platform can be found by running tests --list-platforms
.
The PLATFORM configuration is optional, with the default platform set to stm32f4discovery
.
For example,
make [PLATFORM=<PLATFORM_NAME>] [RNG=HAL|NOTRAND] test
assembles all binaries for functional tests.
make [PLATFORM=<PLATFORM_NAME>] [RNG=HAL|NOTRAND] speed
assembles all binaries for speed benchmarking
make [PLATFORM=<PLATFORM_NAME>] [RNG=HAL|NOTRAND] stack
assembles all binaries for stack benchmarking
make [PLATFORM=<PLATFORM_NAME>] RNG=NISTKAT nistkat
assembles all binaries for nistkat
make [PLATFORM=<PLATFORM_NAME>] (all)
assembles all the above targets for all parameter sets.
make emulate
run emulatation for the binary file on QEMU
make clean
cleans up intermediate artifacts
After generating the specified hex files, you can flash it to the development board using openocd
.
For example,
openocd -f hal/stm32f4discovery.cfg -c "program bin/mlkem768-test.hex verify reset exit"
To receive output from the develop board, you can, for example, use pyserial-miniterm
:
pyserial-miniterm /dev/<tty_device> 38400
Make sure to run make clean
between running tests on QEMU or on board or running func/stack/speed and nistkat tests. In case of any inconsistencies, refer to the help command for the most up-to-date usage information
▶ tests --help
Usage: tests [OPTIONS] COMMAND [ARGS]...
Options:
--list-platforms List the supported platforms
--help Show this message and exit.
Commands:
func Run functional tests
nistkat Run nistkat tests
run Run for the specified platform and hex file without parsing the
output
speed Run speed tests
stack Run stack tests
func/speed tests depends on the iteration parameter, which is passed to the tests in compile time, therefore it is preferred to build the binaries with the tests script
▶ tests func --help
Usage: tests func [OPTIONS] {stm32f4discovery|mps2-an386|nucleo-f767zi|mps2-an
500|nucleo-f207zg|mps2-an385}
Options:
-v, --verbose Show verbose output or not
-u, --uart PATH TTY serial device for UART, default to the 1st
serial device connected to your board or an empty
string
-i, --iterations INTEGER Number of tests [default: 1]
--help Show this message and exit.