From d68d3df353114dbbd4235a9859bab0fd788beb3f Mon Sep 17 00:00:00 2001 From: willieyz Date: Wed, 13 Aug 2025 11:34:01 +0800 Subject: [PATCH 1/2] Example: add the `multilevel_build_no_stdlib` example - This commit add an example demonstrating how to build mlkem-native without the standard library (-nostdlib) - Create an example folder named `multilevel_build_no_stdlib` - Add the `example_no_stdlib_config.h` reference from `test/custom_stdlib_config.h`, this config provide custom implementations for mlk_memcpy and mlk_memset - Add the `-nostdlib` cflag during generating objects file. - Integrate this example to the `tests` script and ./Makefile - Add this example to the `base.yml` for CI testing Signed-off-by: willieyz --- .github/workflows/base.yml | 3 + BIBLIOGRAPHY.md | 1 + Makefile | 1 + examples/README.md | 5 + examples/multilevel_build/Makefile | 2 +- .../multilevel_build_no_stdlib/.gitignore | 3 + examples/multilevel_build_no_stdlib/Makefile | 128 +++++ examples/multilevel_build_no_stdlib/README.md | 17 + examples/multilevel_build_no_stdlib/main.c | 208 ++++++++ .../mlkem_native/example_no_stdlib_config.h | 496 ++++++++++++++++++ .../mlkem_native/mlkem | 1 + .../mlkem_native_all.h | 33 ++ .../test_only_rng/notrandombytes.c | 1 + .../test_only_rng/notrandombytes.h | 1 + mlkem/README.md | 2 +- scripts/tests | 9 + 16 files changed, 909 insertions(+), 2 deletions(-) create mode 100644 examples/multilevel_build_no_stdlib/.gitignore create mode 100644 examples/multilevel_build_no_stdlib/Makefile create mode 100644 examples/multilevel_build_no_stdlib/README.md create mode 100644 examples/multilevel_build_no_stdlib/main.c create mode 100644 examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h create mode 120000 examples/multilevel_build_no_stdlib/mlkem_native/mlkem create mode 100644 examples/multilevel_build_no_stdlib/mlkem_native_all.h create mode 120000 examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.c create mode 120000 examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.h diff --git a/.github/workflows/base.yml b/.github/workflows/base.yml index 435f2fe5e..22c019a8d 100644 --- a/.github/workflows/base.yml +++ b/.github/workflows/base.yml @@ -254,6 +254,9 @@ jobs: - name: multilevel_build_native run: | CFLAGS="-O0" make run -C examples/multilevel_build_native + - name: multilevel_build_no_stdlib + run: | + CFLAGS="-O0" make run -C examples/multilevel_build_no_stdlib simpasm: strategy: fail-fast: false diff --git a/BIBLIOGRAPHY.md b/BIBLIOGRAPHY.md index f10a15f6e..74279fb38 100644 --- a/BIBLIOGRAPHY.md +++ b/BIBLIOGRAPHY.md @@ -27,6 +27,7 @@ source code and documentation. * URL: https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements * Referenced from: - [examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h](examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h) + - [examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h](examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h) - [integration/liboqs/config_aarch64.h](integration/liboqs/config_aarch64.h) - [integration/liboqs/config_c.h](integration/liboqs/config_c.h) - [integration/liboqs/config_x86_64.h](integration/liboqs/config_x86_64.h) diff --git a/Makefile b/Makefile index bec1a9c9f..4c7a0e446 100644 --- a/Makefile +++ b/Makefile @@ -236,3 +236,4 @@ clean: -make clean -C examples/monolithic_build_multilevel_native >/dev/null -make clean -C examples/multilevel_build >/dev/null -make clean -C examples/multilevel_build_native >/dev/null + -make clean -C examples/multilevel_build_no_stdlib > /dev/null diff --git a/examples/README.md b/examples/README.md index 65957ebc3..6402ff306 100644 --- a/examples/README.md +++ b/examples/README.md @@ -16,6 +16,11 @@ See [basic_deterministic](basic_deterministic) for a basic example of how to bui See [multilevel_build](multilevel_build) for an example of how to build one instance of mlkem-native per security level, in such a way that level-independent code is shared. +## Multi-level build without the standard library (C only) + +See multilevel_build_no_stdlib for an example of how to build one instance of mlkem-native per security level without the standard library. +In this example, `mlk_memcpy` and `mlk_memset` are replaced with custom implementations through [custom_no_stdlib_config.h](../test/custom_stdlib_config.h). + ## Multi-level build (with native code) See [multilevel_build_native](multilevel_build_native) for an example of how to build one instance of mlkem-native per diff --git a/examples/multilevel_build/Makefile b/examples/multilevel_build/Makefile index 870b2996c..91b89fa31 100644 --- a/examples/multilevel_build/Makefile +++ b/examples/multilevel_build/Makefile @@ -89,7 +89,7 @@ CFLAGS := \ -Wno-unknown-pragmas \ -Wno-unused-command-line-argument \ -fomit-frame-pointer \ - -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem \ + -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem \ -std=c99 \ -pedantic \ -MMD \ diff --git a/examples/multilevel_build_no_stdlib/.gitignore b/examples/multilevel_build_no_stdlib/.gitignore new file mode 100644 index 000000000..eb98a94f1 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/.gitignore @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + +build diff --git a/examples/multilevel_build_no_stdlib/Makefile b/examples/multilevel_build_no_stdlib/Makefile new file mode 100644 index 000000000..aff753b23 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/Makefile @@ -0,0 +1,128 @@ +# (SPDX-License-Identifier: CC-BY-4.0) + +.PHONY: build run clean mlkem512_objs mlkem768_objs mlkem1024_objs mlkem_objs size size_objs +.DEFAULT_GOAL := all + +Q ?= @ +# Append cross-prefix for cross compilation +# Remove or ignore for native builds +CC ?= gcc +SIZE ?= size +# When called from the root Makefile, CROSS_PREFIX has already been added here +ifeq (,$(findstring $(CROSS_PREFIX),$(CC))) +CC := $(CROSS_PREFIX)$(CC) +endif + +ifeq (,$(findstring $(CROSS_PREFIX),$(SIZE))) +SIZE := $(CROSS_PREFIX)$(SIZE) +endif + +# Part A: +# +# mlkem-native source and header files +# +# If you are not concerned about minimizing for a specific backend, +# you can just include _all_ source files into your build. +MLK_SOURCE_ALL := $(wildcard \ + mlkem_native/mlkem/src/*.c \ + mlkem_native/mlkem/src/**/*.c \ + mlkem_native/mlkem/src/**/**/*.c \ + mlkem_native/mlkem/src/**/**/**/*.c) +MLK_SOURCE:=$(foreach S,$(MLK_SOURCE_ALL),\ + $(if $(findstring /native/,$S),,$S)) + +INC=-Imlkem_native -Imlkem_native/mlkem -Imlkem_native/mlkem/src + +BUILD_DIR=build +MLKEM512_DIR = $(BUILD_DIR)/mlkem512 +MLKEM768_DIR = $(BUILD_DIR)/mlkem768 +MLKEM1024_DIR = $(BUILD_DIR)/mlkem1024 + +MLKEM512_OBJS=$(patsubst %,$(MLKEM512_DIR)/%.o,$(MLK_SOURCE)) +MLKEM768_OBJS=$(patsubst %,$(MLKEM768_DIR)/%.o,$(MLK_SOURCE)) +MLKEM1024_OBJS=$(patsubst %,$(MLKEM1024_DIR)/%.o,$(MLK_SOURCE)) + +$(MLKEM512_OBJS): $(MLKEM512_DIR)/%.c.o: %.c + $(Q)[ -d $(@D) ] || mkdir -p $(@D) + $(Q)$(CC) -nostdlib -DMLK_CONFIG_MULTILEVEL_WITH_SHARED -DMLK_CONFIG_PARAMETER_SET=512 $(INC) $(CFLAGS) -c $^ -o $@ + +$(MLKEM768_OBJS): $(MLKEM768_DIR)/%.c.o: %.c + $(Q)[ -d $(@D) ] || mkdir -p $(@D) + $(Q)$(CC) -nostdlib -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=768 $(INC) $(CFLAGS) -c $^ -o $@ + +$(MLKEM1024_OBJS): $(MLKEM1024_DIR)/%.c.o: %.c + $(Q)[ -d $(@D) ] || mkdir -p $(@D) + $(Q)$(CC) -nostdlib -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) $(CFLAGS) -c $^ -o $@ + +mlkem512_objs: $(MLKEM512_OBJS) +mlkem768_objs: $(MLKEM768_OBJS) +mlkem1024_objs: $(MLKEM1024_OBJS) +mlkem_objs: mlkem512_objs mlkem768_objs mlkem1024_objs + +# Part B: +# +# Random number generator +# +# !!! WARNING !!! +# +# The randombytes() implementation used here is for TESTING ONLY. +# You MUST NOT use this implementation outside of testing. +# +# !!! WARNING !!! +RNG_SOURCE=$(wildcard test_only_rng/*.c) + +# Part C: +# +# Your application source code +APP_SOURCE=$(wildcard *.c) + +BIN=test_binary + +CFLAGS := \ + -Wall \ + -Wextra \ + -Werror \ + -Wmissing-prototypes \ + -Wshadow \ + -Werror \ + -Wpointer-arith \ + -Wredundant-decls \ + -Wno-long-long \ + -Wno-unknown-pragmas \ + -Wno-unused-command-line-argument \ + -fomit-frame-pointer \ + -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem \ + -std=c99 \ + -pedantic \ + -MMD \ + -O3 \ + $(CFLAGS) + +BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN) + +CFLAGS += -DMLK_CONFIG_FILE="\"example_no_stdlib_config.h\"" + +$(BINARY_NAME_FULL): $(APP_SOURCE) $(RNG_SOURCE) $(MLKEM512_OBJS) $(MLKEM768_OBJS) $(MLKEM1024_OBJS) + echo "$@" + mkdir -p $(BUILD_DIR) + $(CC) $(CFLAGS) $(INC) $^ -o $@ + +all: build size_objs + +build: $(BINARY_NAME_FULL) + +run: $(BINARY_NAME_FULL) + $(EXEC_WRAPPER) ./$(BINARY_NAME_FULL) + +size: build + @echo "=== Size info for $(BINARY_NAME_FULL) ===" + $(Q)$(SIZE) $(BINARY_NAME_FULL) + +size_objs: size + $(Q)echo "=== Object size summary ===" + $(Q)$(SIZE) $(shell find $(BUILD_DIR)/mlkem512 -name '*.o') | (read header; echo "$$header"; awk '$$5 != 0' | sort -k5 -n -r) + $(Q)$(SIZE) $(shell find $(BUILD_DIR)/mlkem768 -name '*.o') | (read header; echo "$$header"; awk '$$5 != 0' | sort -k5 -n -r) + $(Q)$(SIZE) $(shell find $(BUILD_DIR)/mlkem1024 -name '*.o') | (read header; echo "$$header"; awk '$$5 != 0' | sort -k5 -n -r) + +clean: + rm -rf $(BUILD_DIR) diff --git a/examples/multilevel_build_no_stdlib/README.md b/examples/multilevel_build_no_stdlib/README.md new file mode 100644 index 000000000..2102093fb --- /dev/null +++ b/examples/multilevel_build_no_stdlib/README.md @@ -0,0 +1,17 @@ +[//]: # (SPDX-License-Identifier: CC-BY-4.0) + +# Multi-level build with no standard library + +This directory contains a minimal example demonstrating how to build mlkem-native with support for all three security levels: MLKEM-512, MLKEM-768, and MLKEM-1024, and so that level-independent code is shared. Unlike a simple [`multilevel_build`](../multilevel_build/README.md), this example also demonstrates how to replace `mlk_memcpy` and `mlk_memset` with custom implementations, allowing the build to proceed without using the standard library (stdlib). +In this example, only the C-backend of mlkem-native is used. + +The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the MLKEM-512 build, we set +`MLK_CONFIG_MULTILEVEL_WITH_SHARED` to force the inclusion of all level-independent code in the +MLKEM512-build. For ML-KEM-768 and ML-KEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any +level-independent code, beside this, this example replace the `mlk_memcpy`, `mlk_memset` with the custom implementation memcpy and memset instead of using the stdlib by adding `example_no_stdlib_config.h`, and add `-nostdlib` to the compilation flags, +Finally, we use the common namespace prefix `mlkem` as `MLK_CONFIG_NAMESPACE_PREFIX` for all three builds; +the suffix 512/768/1024 will be added to level-dependent functions automatically. + +## Usage + +Build this example with `make build`, run with `make run`. diff --git a/examples/multilevel_build_no_stdlib/main.c b/examples/multilevel_build_no_stdlib/main.c new file mode 100644 index 000000000..37e3d2d58 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/main.c @@ -0,0 +1,208 @@ +/* + * Copyright (c) The mlkem-native project authors + * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + */ + +#include +#include +#include + +#include "mlkem_native_all.h" +#include "test_only_rng/notrandombytes.h" + +#define CHECK(x) \ + do \ + { \ + int rc; \ + rc = (x); \ + if (!rc) \ + { \ + fprintf(stderr, "ERROR (%s,%d)\n", __FILE__, __LINE__); \ + return 1; \ + } \ + } while (0) + +static int test_keys_mlkem512(void) +{ + /* The PCT modifies the PRNG state, so the KAT tests don't work. + * We run KAT tests only for disabled PCT. */ +#if !defined(MLK_CONFIG_KEYGEN_PCT) + const uint8_t expected_key[] = { + 0x77, 0x6c, 0x74, 0xdf, 0x30, 0x1f, 0x8d, 0x82, 0x52, 0x5e, 0x8e, + 0xbb, 0xb4, 0x00, 0x95, 0xcd, 0x2e, 0x92, 0xdf, 0x6d, 0xc9, 0x33, + 0xe7, 0x86, 0x62, 0x59, 0xf5, 0x31, 0xc7, 0x35, 0x0a, 0xd5}; +#endif /* !MLK_CONFIG_KEYGEN_PCT */ + + uint8_t pk[MLKEM512_PUBLICKEYBYTES]; + uint8_t sk[MLKEM512_SECRETKEYBYTES]; + uint8_t ct[MLKEM512_CIPHERTEXTBYTES]; + uint8_t key_a[MLKEM512_BYTES]; + uint8_t key_b[MLKEM512_BYTES]; + + /* WARNING: Test-only + * Normally, you would want to seed a PRNG with trustworthy entropy here. */ + randombytes_reset(); + + /* Alice generates a public key */ + CHECK(mlkem512_keypair(pk, sk) == 0); + + /* Bob derives a secret key and creates a response */ + CHECK(mlkem512_enc(ct, key_b, pk) == 0); + + /* Alice uses Bobs response to get her shared key */ + CHECK(mlkem512_dec(key_a, ct, sk) == 0); + + CHECK(memcmp(key_a, key_b, MLKEM512_BYTES) == 0); + + printf("Shared secret: "); + { + size_t i; + for (i = 0; i < sizeof(key_a); i++) + { + printf("%02x", key_a[i]); + } + } + printf("\n"); + +#if !defined(MLK_CONFIG_KEYGEN_PCT) + /* Check against hardcoded result to make sure that + * we integrated custom FIPS202 correctly */ + CHECK(memcmp(key_a, expected_key, sizeof(key_a)) == 0); +#else + printf( + "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); +#endif + + printf("[MLKEM-512] OK\n"); + return 0; +} + +static int test_keys_mlkem768(void) +{ + /* The PCT modifies the PRNG state, so the KAT tests don't work. + * We run KAT tests only for disabled PCT. */ +#if !defined(MLK_CONFIG_KEYGEN_PCT) + const uint8_t expected_key[] = { + 0xe9, 0x13, 0x77, 0x84, 0x0e, 0x6b, 0x66, 0x94, 0xea, 0xa9, 0xf0, + 0x1c, 0x97, 0xff, 0x68, 0x87, 0x4e, 0x8b, 0x0c, 0x52, 0x0b, 0x00, + 0xc2, 0xcd, 0xe3, 0x7c, 0x4f, 0xc2, 0x39, 0x62, 0x6e, 0x70}; +#endif /* !MLK_CONFIG_KEYGEN_PCT */ + + uint8_t pk[MLKEM768_PUBLICKEYBYTES]; + uint8_t sk[MLKEM768_SECRETKEYBYTES]; + uint8_t ct[MLKEM768_CIPHERTEXTBYTES]; + uint8_t key_a[MLKEM768_BYTES]; + uint8_t key_b[MLKEM768_BYTES]; + + /* WARNING: Test-only + * Normally, you would want to seed a PRNG with trustworthy entropy here. */ + randombytes_reset(); + + /* Alice generates a public key */ + CHECK(mlkem768_keypair(pk, sk) == 0); + + /* Bob derives a secret key and creates a response */ + CHECK(mlkem768_enc(ct, key_b, pk) == 0); + + /* Alice uses Bobs response to get her shared key */ + CHECK(mlkem768_dec(key_a, ct, sk) == 0); + + CHECK(memcmp(key_a, key_b, MLKEM768_BYTES) == 0); + + printf("Shared secret: "); + { + size_t i; + for (i = 0; i < sizeof(key_a); i++) + { + printf("%02x", key_a[i]); + } + } + printf("\n"); + +#if !defined(MLK_CONFIG_KEYGEN_PCT) + /* Check against hardcoded result to make sure that + * we integrated custom FIPS202 correctly */ + CHECK(memcmp(key_a, expected_key, sizeof(key_a)) == 0); +#else + printf( + "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); +#endif + + printf("[MLKEM-768] OK\n"); + return 0; +} + + +static int test_keys_mlkem1024(void) +{ + /* The PCT modifies the PRNG state, so the KAT tests don't work. + * We run KAT tests only for disabled PCT. */ +#if !defined(MLK_CONFIG_KEYGEN_PCT) + const uint8_t expected_key[] = { + 0x5d, 0x9e, 0x23, 0x5f, 0xcc, 0xb2, 0xb3, 0x49, 0x9a, 0x5f, 0x49, + 0x0a, 0x56, 0xe3, 0xf0, 0xd3, 0xfd, 0x9b, 0x58, 0xbd, 0xa2, 0x8b, + 0x69, 0x0f, 0x91, 0xb5, 0x7b, 0x88, 0xa5, 0xa8, 0x0b, 0x90}; +#endif /* !MLK_CONFIG_KEYGEN_PCT */ + uint8_t pk[MLKEM1024_PUBLICKEYBYTES]; + uint8_t sk[MLKEM1024_SECRETKEYBYTES]; + uint8_t ct[MLKEM1024_CIPHERTEXTBYTES]; + uint8_t key_a[MLKEM1024_BYTES]; + uint8_t key_b[MLKEM1024_BYTES]; + + /* WARNING: Test-only + * Normally, you would want to seed a PRNG with trustworthy entropy here. */ + randombytes_reset(); + + /* Alice generates a public key */ + CHECK(mlkem1024_keypair(pk, sk) == 0); + + /* Bob derives a secret key and creates a response */ + CHECK(mlkem1024_enc(ct, key_b, pk) == 0); + + /* Alice uses Bobs response to get her shared key */ + CHECK(mlkem1024_dec(key_a, ct, sk) == 0); + + CHECK(memcmp(key_a, key_b, MLKEM1024_BYTES) == 0); + + printf("Shared secret: "); + { + size_t i; + for (i = 0; i < sizeof(key_a); i++) + { + printf("%02x", key_a[i]); + } + } + printf("\n"); + +#if !defined(MLK_CONFIG_KEYGEN_PCT) + /* Check against hardcoded result to make sure that + * we integrated custom FIPS202 correctly */ + CHECK(memcmp(key_a, expected_key, sizeof(key_a)) == 0); +#else + printf( + "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); +#endif + + printf("[MLKEM-1024] OK\n"); + return 0; +} + +int main(void) +{ + if (test_keys_mlkem512() != 0) + { + return 1; + } + + if (test_keys_mlkem768() != 0) + { + return 1; + } + + if (test_keys_mlkem1024() != 0) + { + return 1; + } + + return 0; +} diff --git a/examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h b/examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h new file mode 100644 index 000000000..2ed0bceb1 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/mlkem_native/example_no_stdlib_config.h @@ -0,0 +1,496 @@ +/* + * Copyright (c) The mlkem-native project authors + * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + */ + +/* References + * ========== + * + * - [FIPS140_3_IG] + * Implementation Guidance for FIPS 140-3 and the Cryptographic Module + * Validation Program National Institute of Standards and Technology + * https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements + */ + +#ifndef MLK_CONFIG_H +#define MLK_CONFIG_H + +/****************************************************************************** + * Name: MLK_CONFIG_PARAMETER_SET + * + * Description: Specifies the parameter set for ML-KEM + * - MLK_CONFIG_PARAMETER_SET=512 corresponds to ML-KEM-512 + * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 + * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#ifndef MLK_CONFIG_PARAMETER_SET +#define MLK_CONFIG_PARAMETER_SET \ + 768 /* Change this for different security strengths */ +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_FILE + * + * Description: If defined, this is a header that will be included instead + * of this default configuration file mlkem/src/config.h. + * + * When you need to build mlkem-native in multiple configurations, + * using varying MLK_CONFIG_FILE can be more convenient + * then configuring everything through CFLAGS. + * + * To use, MLK_CONFIG_FILE _must_ be defined prior + * to the inclusion of any mlkem-native headers. For example, + * it can be set by passing `-DMLK_CONFIG_FILE="..."` + * on the command line. + * + *****************************************************************************/ +/* #define MLK_CONFIG_FILE "config.h" */ + +/****************************************************************************** + * Name: MLK_CONFIG_NAMESPACE_PREFIX + * + * Description: The prefix to use to namespace global symbols from mlkem/. + * + * In a multi-level build (that is, if either + * - MLK_CONFIG_MULTILEVEL_WITH_SHARED, or + * - MLK_CONFIG_MULTILEVEL_NO_SHARED, + * are set, level-dependent symbols will additionally be prefixed + * with the parameter set (512/768/1024). + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#if !defined(MLK_CONFIG_NAMESPACE_PREFIX) +#define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED + * + * Description: This is for multi-level builds of mlkem-native only. If you + * need only a single parameter set, keep this unset. + * + * If this is set, all MLK_CONFIG_PARAMETER_SET-independent + * code will be included in the build, including code needed only + * for other parameter sets. + * + * Example: mlk_poly_cbd3 is only needed for + * MLK_CONFIG_PARAMETER_SET == 512. Yet, if this option is set + * for a build with MLK_CONFIG_PARAMETER_SET == 768/1024, it + * would be included. + * + * To build mlkem-native with support for all parameter sets, + * build it three times -- once per parameter set -- and set the + * option MLK_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and MLK_CONFIG_MULTILEVEL_NO_SHARED for the others. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_WITH_SHARED */ + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_NO_SHARED + * + * Description: This is for multi-level builds of mlkem-native only. If you + * need only a single parameter set, keep this unset. + * + * If this is set, no MLK_CONFIG_PARAMETER_SET-independent code + * will be included in the build. + * + * To build mlkem-native with support for all parameter sets, + * build it three times -- once per parameter set -- and set the + * option MLK_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and MLK_CONFIG_MULTILEVEL_NO_SHARED for the others. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_NO_SHARED */ + +/****************************************************************************** + * Name: MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS + * + * Description: This is only relevant for single compilation unit (SCU) + * builds of mlkem-native. In this case, it determines whether + * directives defined in parameter-set-independent headers should + * be #undef'ined or not at the of the SCU file. This is needed + * in multilevel builds. + * + * See examples/multilevel_build_native for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS */ + +/****************************************************************************** + * Name: MLK_CONFIG_USE_NATIVE_BACKEND_ARITH + * + * Description: Determines whether an native arithmetic backend should be used. + * + * The arithmetic backend covers performance critical functions + * such as the number-theoretic transform (NTT). + * + * If this option is unset, the C backend will be used. + * + * If this option is set, the arithmetic backend to be use is + * determined by MLK_CONFIG_ARITH_BACKEND_FILE: If the latter is + * unset, the default backend for your the target architecture + * will be used. If set, it must be the name of a backend metadata + * file. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#if !defined(MLK_CONFIG_USE_NATIVE_BACKEND_ARITH) +/* #define MLK_CONFIG_USE_NATIVE_BACKEND_ARITH */ +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_ARITH_BACKEND_FILE + * + * Description: The arithmetic backend to use. + * + * If MLK_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * is ignored. + * + * If MLK_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * either be undefined or the filename of an arithmetic backend. + * If unset, the default backend will be used. + * + * This can be set using CFLAGS. + * + *****************************************************************************/ +#if defined(MLK_CONFIG_USE_NATIVE_BACKEND_ARITH) && \ + !defined(MLK_CONFIG_ARITH_BACKEND_FILE) +#define MLK_CONFIG_ARITH_BACKEND_FILE "native/meta.h" +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 + * + * Description: Determines whether an native FIPS202 backend should be used. + * + * The FIPS202 backend covers 1x/2x/4x-fold Keccak-f1600, which is + * the performance bottleneck of SHA3 and SHAKE. + * + * If this option is unset, the C backend will be used. + * + * If this option is set, the FIPS202 backend to be use is + * determined by MLK_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * unset, the default backend for your the target architecture + * will be used. If set, it must be the name of a backend metadata + * file. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#if !defined(MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202) +/* #define MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 */ +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_FIPS202_BACKEND_FILE + * + * Description: The FIPS-202 backend to use. + * + * If MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * must either be undefined or the filename of a FIPS202 backend. + * If unset, the default backend will be used. + * + * This can be set using CFLAGS. + * + *****************************************************************************/ +#if defined(MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202) && \ + !defined(MLK_CONFIG_FIPS202_BACKEND_FILE) +#define MLK_CONFIG_FIPS202_BACKEND_FILE "fips202/native/auto.h" +#endif + +/****************************************************************************** + * Name: MLK_CONFIG_FIPS202_CUSTOM_HEADER + * + * Description: Custom header to use for FIPS-202 + * + * This should only be set if you intend to use a custom + * FIPS-202 implementation, different from the one shipped + * with mlkem-native. + * + * If set, it must be the name of a file serving as the + * replacement for mlkem/fips202/fips202.h, and exposing + * the same API (see FIPS202.md). + * + *****************************************************************************/ +/* #define MLK_CONFIG_FIPS202_CUSTOM_HEADER "SOME_FILE.h" */ + +/****************************************************************************** + * Name: MLK_CONFIG_FIPS202X4_CUSTOM_HEADER + * + * Description: Custom header to use for FIPS-202-X4 + * + * This should only be set if you intend to use a custom + * FIPS-202 implementation, different from the one shipped + * with mlkem-native. + * + * If set, it must be the name of a file serving as the + * replacement for mlkem/fips202/fips202x4.h, and exposing + * the same API (see FIPS202.md). + * + *****************************************************************************/ +/* #define MLK_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_ZEROIZE + * + * Description: In compliance with FIPS 203 Section 3.3, mlkem-native zeroizes + * intermediate stack buffers before returning from function calls. + * + * Set this option and define `mlk_zeroize` if you want to + * use a custom method to zeroize intermediate stack buffers. + * The default implementation uses SecureZeroMemory on Windows + * and a memset + compiler barrier otherwise. If neither of those + * is available on the target platform, compilation will fail, + * and you will need to use MLK_CONFIG_CUSTOM_ZEROIZE to provide + * a custom implementation of `mlk_zeroize()`. + * + * WARNING: + * The explicit stack zeroization conducted by mlkem-native + * reduces the likelihood of data leaking on the stack, but + * does not eliminate it! The C standard makes no guarantee about + * where a compiler allocates structures and whether/where it makes + * copies of them. Also, in addition to entire structures, there + * may also be potentially exploitable leakage of individual values + * on the stack. + * + * If you need bullet-proof zeroization of the stack, you need to + * consider additional measures instead of of what this feature + * provides. In this case, you can set mlk_zeroize to a no-op. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CUSTOM_ZEROIZE + #if !defined(__ASSEMBLER__) + #include + #include "sys.h" + static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_RANDOMBYTES + * + * Description: mlkem-native does not provide a secure randombytes + * implementation. Such an implementation has to provided by the + * consumer. + * + * If this option is not set, mlkem-native expects a function + * void randombytes(uint8_t *out, size_t outlen). + * + * Set this option and define `mlk_randombytes` if you want to + * use a custom method to sample randombytes with a different name + * or signature. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CUSTOM_RANDOMBYTES + #if !defined(__ASSEMBLER__) + #include + #include "sys.h" + static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_MEMCPY + * + * Description: Set this option and define `mlk_memcpy` if you want to + * use a custom method to copy memory instead of the standard + * library memcpy function. + * + * The custom implementation must have the same signature and + * behavior as the standard memcpy function: + * void *mlk_memcpy(void *dest, const void *src, size_t n) + * + *****************************************************************************/ +#define MLK_CONFIG_CUSTOM_MEMCPY +#if !defined(__ASSEMBLER__) +#include +#include +#include "mlkem/src/sys.h" +static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) +{ + /* Simple byte-by-byte copy implementation for testing */ + size_t i; + unsigned char *d = (unsigned char *)dest; + const unsigned char *s = (const unsigned char *)src; + for (i = 0; i < n; i++) + { + d[i] = s[i]; + } + return dest; +} +#endif /* !__ASSEMBLER__ */ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_MEMSET + * + * Description: Set this option and define `mlk_memset` if you want to + * use a custom method to set memory instead of the standard + * library memset function. + * + * The custom implementation must have the same signature and + * behavior as the standard memset function: + * void *mlk_memset(void *s, int c, size_t n) + * + *****************************************************************************/ +#define MLK_CONFIG_CUSTOM_MEMSET +#if !defined(__ASSEMBLER__) +#include +#include +#include "mlkem/src/sys.h" +static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) +{ + /* Simple byte-by-byte set implementation for testing */ + size_t i; + unsigned char *ptr = (unsigned char *)s; + for (i = 0; i < n; i++) + { + ptr[i] = (unsigned char)c; + } + return s; +} +#endif /* !__ASSEMBLER__ */ + +/****************************************************************************** + * Name: MLK_CONFIG_INTERNAL_API_QUALIFIER + * + * Description: If set, this option provides an additional function + * qualifier to be added to declarations of internal API. + * + * The primary use case for this option are single-CU builds, + * in which case this option can be set to `static`. + * + *****************************************************************************/ +/* #define MLK_CONFIG_INTERNAL_API_QUALIFIER */ + +/****************************************************************************** + * Name: MLK_CONFIG_EXTERNAL_API_QUALIFIER + * + * Description: If set, this option provides an additional function + * qualifier to be added to declarations of mlkem-native's + * public API. + * + * The primary use case for this option are single-CU builds + * where the public API exposed by mlkem-native is wrapped by + * another API in the consuming application. In this case, + * even mlkem-native's public API can be marked `static`. + * + *****************************************************************************/ +/* #define MLK_CONFIG_EXTERNAL_API_QUALIFIER */ + +/****************************************************************************** + * Name: MLK_CONFIG_CT_TESTING_ENABLED + * + * Description: If set, mlkem-native annotates data as secret / public using + * valgrind's annotations VALGRIND_MAKE_MEM_UNDEFINED and + * VALGRIND_MAKE_MEM_DEFINED, enabling various checks for secret- + * dependent control flow of variable time execution (depending + * on the exact version of valgrind installed). + * + *****************************************************************************/ +/* #define MLK_CONFIG_CT_TESTING_ENABLED */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_ASM + * + * Description: If this option is set, mlkem-native will be built without + * use of native code or inline assembly. + * + * By default, inline assembly is used to implement value barriers. + * Without inline assembly, mlkem-native will use a global volatile + * 'opt blocker' instead; see verify.h. + * + * Inline assembly is also used to implement a secure zeroization + * function on non-Windows platforms. If this option is set and + * the target platform is not Windows, you MUST set + * MLK_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * function. + * + * If this option is set, MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * and MLK_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * native backends will be used. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_ASM */ + +/****************************************************************************** + * Name: MLK_CONFIG_KEYGEN_PCT + * + * Description: Compliance with @[FIPS140_3_IG, p.87] requires a + * Pairwise Consistency Test (PCT) to be carried out on a freshly + * generated keypair before it can be exported. + * + * Set this option if such a check should be implemented. + * In this case, crypto_kem_keypair_derand and crypto_kem_keypair + * will return a non-zero error code if the PCT failed. + * + * NOTE: This feature will drastically lower the performance of + * key generation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_KEYGEN_PCT */ + +/****************************************************************************** + * Name: MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST + * + * Description: If this option is set, the user must provide a runtime + * function `static inline int mlk_break_pct() { ... }` to + * indicate whether the PCT should be made fail. + * + * This option only has an effect if MLK_CONFIG_KEYGEN_PCT is set. + * + *****************************************************************************/ +/* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST + #if !defined(__ASSEMBLER__) + #include "sys.h" + static MLK_INLINE int mlk_break_pct(void) + { + ... return 0/1 depending on whether PCT should be broken ... + } + #endif +*/ + +/************************* Config internals ********************************/ + +/* Default namespace + * + * Don't change this. If you need a different namespace, re-define + * MLK_CONFIG_NAMESPACE_PREFIX above instead, and remove the following. + * + * The default MLKEM namespace is + * + * PQCP_MLKEM_NATIVE_MLKEM_ + * + * e.g., PQCP_MLKEM_NATIVE_MLKEM512_ + */ + +#if MLK_CONFIG_PARAMETER_SET == 512 +#define MLK_DEFAULT_NAMESPACE_PREFIX PQCP_MLKEM_NATIVE_MLKEM512 +#elif MLK_CONFIG_PARAMETER_SET == 768 +#define MLK_DEFAULT_NAMESPACE_PREFIX PQCP_MLKEM_NATIVE_MLKEM768 +#elif MLK_CONFIG_PARAMETER_SET == 1024 +#define MLK_DEFAULT_NAMESPACE_PREFIX PQCP_MLKEM_NATIVE_MLKEM1024 +#endif + +#endif /* !MLK_CONFIG_H */ diff --git a/examples/multilevel_build_no_stdlib/mlkem_native/mlkem b/examples/multilevel_build_no_stdlib/mlkem_native/mlkem new file mode 120000 index 000000000..f4ec7bdb2 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/mlkem_native/mlkem @@ -0,0 +1 @@ +../../../mlkem \ No newline at end of file diff --git a/examples/multilevel_build_no_stdlib/mlkem_native_all.h b/examples/multilevel_build_no_stdlib/mlkem_native_all.h new file mode 100644 index 000000000..c7915fd45 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/mlkem_native_all.h @@ -0,0 +1,33 @@ +/* + * Copyright (c) The mlkem-native project authors + * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + */ + +#if !defined(MLK_ALL_H) +#define MLK_ALL_H + +/* API for MLKEM-512 */ +#define MLK_CONFIG_API_PARAMETER_SET 512 +#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 +#include "mlkem_native/mlkem/mlkem_native.h" +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_H + +/* API for MLKEM-768 */ +#define MLK_CONFIG_API_PARAMETER_SET 768 +#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 +#include "mlkem_native/mlkem/mlkem_native.h" +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_H + +/* API for MLKEM-1024 */ +#define MLK_CONFIG_API_PARAMETER_SET 1024 +#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 +#include "mlkem_native/mlkem/mlkem_native.h" +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_H + +#endif /* !MLK_ALL_H */ diff --git a/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.c b/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.c new file mode 120000 index 000000000..65b7801b8 --- /dev/null +++ b/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.c @@ -0,0 +1 @@ +../../../test/notrandombytes/notrandombytes.c \ No newline at end of file diff --git a/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.h b/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.h new file mode 120000 index 000000000..e72c12b9c --- /dev/null +++ b/examples/multilevel_build_no_stdlib/test_only_rng/notrandombytes.h @@ -0,0 +1 @@ +../../../test/notrandombytes/notrandombytes.h \ No newline at end of file diff --git a/mlkem/README.md b/mlkem/README.md index 63f6c92bd..d82dc4804 100644 --- a/mlkem/README.md +++ b/mlkem/README.md @@ -20,4 +20,4 @@ The public API is defined in [mlkem_native.h](mlkem_native.h). Before you includ ## Supporting multiple parameter sets -If you want to support multiple parameter sets, build the library once per parameter set you want to support. Set `MLK_CONFIG_MULTILEVEL_WITH_SHARED` for one of the builds, and `MLK_CONFIG_MULTILEVEL_NO_SHARED` for the others, to avoid duplicating shared functionality. Finally, link with RNG and your application as before. This is demonstrated in the examples [examples/multilevel_build](../examples/multilevel_build), [examples/multilevel_build_native](../examples/multilevel_build_native), [examples/monolithic_build_multilevel](../examples/monolithic_build_multilevel) and [examples/monolithic_build_multilevel_native](../examples/monolithic_build_multilevel_native). +If you want to support multiple parameter sets, build the library once per parameter set you want to support. Set `MLK_CONFIG_MULTILEVEL_WITH_SHARED` for one of the builds, and `MLK_CONFIG_MULTILEVEL_NO_SHARED` for the others, to avoid duplicating shared functionality. Finally, link with RNG and your application as before. This is demonstrated in the examples [examples/multilevel_build](../examples/multilevel_build), [examples/multilevel_build_no_stdlib](../examples/multilevel_build_no_stdlib), [examples/multilevel_build_native](../examples/multilevel_build_native), [examples/monolithic_build_multilevel](../examples/monolithic_build_multilevel) and [examples/monolithic_build_multilevel_native](../examples/monolithic_build_multilevel_native). diff --git a/scripts/tests b/scripts/tests index e6362a65c..cfe56894b 100755 --- a/scripts/tests +++ b/scripts/tests @@ -210,6 +210,7 @@ class TEST_TYPES(Enum): SIZE = 16 BASIC_DETERMINISTIC = 17 UNIT = 18 + MULTILEVEL_BUILD_NO_STDLIB = 19 def is_benchmark(self): return self in [TEST_TYPES.BENCH, TEST_TYPES.BENCH_COMPONENTS] @@ -223,6 +224,7 @@ class TEST_TYPES(Enum): TEST_TYPES.BRING_YOUR_OWN_FIPS202, TEST_TYPES.CUSTOM_BACKEND, TEST_TYPES.BASIC, + TEST_TYPES.MULTILEVEL_BUILD_NO_STDLIB, TEST_TYPES.MONOLITHIC_BUILD, TEST_TYPES.MONOLITHIC_BUILD_NATIVE, TEST_TYPES.MONOLITHIC_BUILD_MULTILEVEL, @@ -265,6 +267,8 @@ class TEST_TYPES(Enum): return "Example (mlkem-native as code package)" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "Example (mlkem-native as code package without randombytes() implementation)" + if self == TEST_TYPES.MULTILEVEL_BUILD_NO_STDLIB: + return "Example (multilevel build, no_stdlib)" if self == TEST_TYPES.MONOLITHIC_BUILD: return "Example (monobuild)" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -291,6 +295,8 @@ class TEST_TYPES(Enum): return "examples/basic" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "examples/basic_deterministic" + if self == TEST_TYPES.MULTILEVEL_BUILD_NO_STDLIB: + return "examples/multilevel_build_no_stdlib" if self == TEST_TYPES.MONOLITHIC_BUILD: return "examples/monolithic_build" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -326,6 +332,8 @@ class TEST_TYPES(Enum): return "" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "" + if self == TEST_TYPES.MULTILEVEL_BUILD_NO_STDLIB: + return "" if self == TEST_TYPES.MONOLITHIC_BUILD: return "" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -1169,6 +1177,7 @@ def cli(): "custom_backend", "basic", "basic_deterministic", + "multilevel_build_no_stdlib", "monolithic_build", "monolithic_build_native", "monolithic_build_multilevel", From 208fe20b7135e627e4130a65cc4d90036b86e963 Mon Sep 17 00:00:00 2001 From: willieyz Date: Thu, 18 Sep 2025 15:00:44 +0800 Subject: [PATCH 2/2] Rename all parameter sets: from `MLKEM-{512/768/1024}` to `ML-KEM-{512/768/1024}` - This typo was pre-existing before this PR #1153, we sort this out with a separate commit Signed-off-by: willieyz --- .github/workflows/cbmc.yml | 6 +++--- examples/monolithic_build_multilevel/README.md | 8 ++++---- examples/monolithic_build_multilevel/main.c | 6 +++--- examples/monolithic_build_multilevel/mlkem_native_all.h | 6 +++--- examples/monolithic_build_multilevel_native/README.md | 2 +- examples/monolithic_build_multilevel_native/main.c | 6 +++--- examples/multilevel_build/README.md | 6 +++--- examples/multilevel_build/main.c | 6 +++--- examples/multilevel_build/mlkem_native_all.h | 6 +++--- examples/multilevel_build_native/README.md | 6 +++--- examples/multilevel_build_native/main.c | 6 +++--- examples/multilevel_build_native/mlkem_native_all.h | 6 +++--- examples/multilevel_build_no_stdlib/README.md | 6 +++--- examples/multilevel_build_no_stdlib/main.c | 6 +++--- examples/multilevel_build_no_stdlib/mlkem_native_all.h | 6 +++--- mlkem/mlkem_native.S | 2 +- mlkem/mlkem_native.c | 2 +- scripts/autogen | 4 ++-- 18 files changed, 48 insertions(+), 48 deletions(-) diff --git a/.github/workflows/cbmc.yml b/.github/workflows/cbmc.yml index 131f2cbc3..f24d00da1 100644 --- a/.github/workflows/cbmc.yml +++ b/.github/workflows/cbmc.yml @@ -16,7 +16,7 @@ jobs: id-token: 'write' uses: ./.github/workflows/ci_ec2_reusable.yml with: - name: CBMC (MLKEM-512) + name: CBMC (ML-KEM-512) ec2_instance_type: c7g.4xlarge ec2_ami: ubuntu-latest (custom AMI) ec2_ami_id: ami-08ddb0acd99dc3d33 # aarch64, ubuntu-latest, 64g @@ -38,7 +38,7 @@ jobs: id-token: 'write' uses: ./.github/workflows/ci_ec2_reusable.yml with: - name: CBMC (MLKEM-768) + name: CBMC (ML-KEM-768) ec2_instance_type: c7g.4xlarge ec2_ami: ubuntu-latest (custom AMI) ec2_ami_id: ami-08ddb0acd99dc3d33 # aarch64, ubuntu-latest, 64g @@ -60,7 +60,7 @@ jobs: id-token: 'write' uses: ./.github/workflows/ci_ec2_reusable.yml with: - name: CBMC (MLKEM-1024) + name: CBMC (ML-KEM-1024) ec2_instance_type: c7g.4xlarge ec2_ami: ubuntu-latest (custom AMI) ec2_ami_id: ami-08ddb0acd99dc3d33 # aarch64, ubuntu-latest, 64g diff --git a/examples/monolithic_build_multilevel/README.md b/examples/monolithic_build_multilevel/README.md index b571b4a94..1b9cca6bb 100644 --- a/examples/monolithic_build_multilevel/README.md +++ b/examples/monolithic_build_multilevel/README.md @@ -41,7 +41,7 @@ by `MLK_CONFIG_PARAMETER_SET`) every time. ``` Note the setting `MLK_CONFIG_MULTILEVEL_WITH_SHARED` which forces the inclusion of all level-independent -code in the MLKEM-512 build, and the setting `MLK_CONFIG_MULTILEVEL_NO_SHARED`, which drops all +code in the ML-KEM-512 build, and the setting `MLK_CONFIG_MULTILEVEL_NO_SHARED`, which drops all level-independent code in the subsequent builds. Finally, `MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS` entails that `mlkem_native.c` does not `#undefine` the `#define` clauses from level-independent files. @@ -54,7 +54,7 @@ would lead to name-clashes upon multiple use. ```C #define MLK_CONFIG_API_NO_SUPERCOP -/* API for MLKEM-512 */ +/* API for ML-KEM-512 */ #define MLK_CONFIG_API_PARAMETER_SET 512 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 #include @@ -62,7 +62,7 @@ would lead to name-clashes upon multiple use. #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-768 */ +/* API for ML-KEM-768 */ #define MLK_CONFIG_API_PARAMETER_SET 768 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 #include @@ -70,7 +70,7 @@ would lead to name-clashes upon multiple use. #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-1024 */ +/* API for ML-KEM-1024 */ #define MLK_CONFIG_API_PARAMETER_SET 1024 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 #include diff --git a/examples/monolithic_build_multilevel/main.c b/examples/monolithic_build_multilevel/main.c index ebcc9c0f2..981b1b9c2 100644 --- a/examples/monolithic_build_multilevel/main.c +++ b/examples/monolithic_build_multilevel/main.c @@ -73,7 +73,7 @@ static int test_keys_mlkem512(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-512] OK\n"); + printf("[ML-KEM-512] OK\n"); return 0; } @@ -128,7 +128,7 @@ static int test_keys_mlkem768(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-768] OK\n"); + printf("[ML-KEM-768] OK\n"); return 0; } @@ -184,7 +184,7 @@ static int test_keys_mlkem1024(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-1024] OK\n"); + printf("[ML-KEM-1024] OK\n"); return 0; } diff --git a/examples/monolithic_build_multilevel/mlkem_native_all.h b/examples/monolithic_build_multilevel/mlkem_native_all.h index 70a59f1d3..515d8d2a7 100644 --- a/examples/monolithic_build_multilevel/mlkem_native_all.h +++ b/examples/monolithic_build_multilevel/mlkem_native_all.h @@ -8,7 +8,7 @@ #define MLK_CONFIG_API_NO_SUPERCOP -/* API for MLKEM-512 */ +/* API for ML-KEM-512 */ #define MLK_CONFIG_API_PARAMETER_SET 512 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 #include @@ -16,7 +16,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-768 */ +/* API for ML-KEM-768 */ #define MLK_CONFIG_API_PARAMETER_SET 768 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 #include @@ -24,7 +24,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-1024 */ +/* API for ML-KEM-1024 */ #define MLK_CONFIG_API_PARAMETER_SET 1024 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 #include diff --git a/examples/monolithic_build_multilevel_native/README.md b/examples/monolithic_build_multilevel_native/README.md index 737e30ef8..3726a7d95 100644 --- a/examples/monolithic_build_multilevel_native/README.md +++ b/examples/monolithic_build_multilevel_native/README.md @@ -42,7 +42,7 @@ appropriately first, and then includes the monobuild: ``` Note the setting `MLK_CONFIG_MULTILEVEL_WITH_SHARED` which forces the inclusion of all level-independent -code in the MLKEM-512 build, and the setting `MLK_CONFIG_MULTILEVEL_NO_SHARED`, which drops all +code in the ML-KEM-512 build, and the setting `MLK_CONFIG_MULTILEVEL_NO_SHARED`, which drops all level-independent code in the subsequent builds. Finally, `MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS` entails that [mlkem_native.c](mlkem/mlkem_native.c) does not `#undefine` the `#define` clauses from level-independent files. diff --git a/examples/monolithic_build_multilevel_native/main.c b/examples/monolithic_build_multilevel_native/main.c index 9f4c28008..d6d8eb49d 100644 --- a/examples/monolithic_build_multilevel_native/main.c +++ b/examples/monolithic_build_multilevel_native/main.c @@ -77,7 +77,7 @@ static int test_keys_mlkem512(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-512] OK\n"); + printf("[ML-KEM-512] OK\n"); return 0; } @@ -132,7 +132,7 @@ static int test_keys_mlkem768(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-768] OK\n"); + printf("[ML-KEM-768] OK\n"); return 0; } @@ -188,7 +188,7 @@ static int test_keys_mlkem1024(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-1024] OK\n"); + printf("[ML-KEM-1024] OK\n"); return 0; } diff --git a/examples/multilevel_build/README.md b/examples/multilevel_build/README.md index 25fb3d1c1..b581542c7 100644 --- a/examples/multilevel_build/README.md +++ b/examples/multilevel_build/README.md @@ -3,12 +3,12 @@ # Multi-level build This directory contains a minimal example for how to build mlkem-native with support for all 3 security levels -MLKEM-512, MLKEM-768, and MLKEM-1024, and so that level-independent code is shared. In this example, only the C-backend +ML-KEM-512, ML-KEM-768, and ML-KEM-1024, and so that level-independent code is shared. In this example, only the C-backend of mlkem-native is used. -The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the MLKEM-512 build, we set +The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the ML-KEM-512 build, we set `MLK_CONFIG_MULTILEVEL_WITH_SHARED` to force the inclusion of all level-independent code in the -MLKEM512-build. For MLKEM-768 and MLKEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any +MLKEM512-build. For ML-KEM-768 and ML-KEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any level-independent code. Finally, we use the common namespace prefix `mlkem` as `MLK_CONFIG_NAMESPACE_PREFIX` for all three builds; the suffix 512/768/1024 will be added to level-dependent functions automatically. diff --git a/examples/multilevel_build/main.c b/examples/multilevel_build/main.c index 37e3d2d58..f5aab6e75 100644 --- a/examples/multilevel_build/main.c +++ b/examples/multilevel_build/main.c @@ -73,7 +73,7 @@ static int test_keys_mlkem512(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-512] OK\n"); + printf("[ML-KEM-512] OK\n"); return 0; } @@ -128,7 +128,7 @@ static int test_keys_mlkem768(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-768] OK\n"); + printf("[ML-KEM-768] OK\n"); return 0; } @@ -183,7 +183,7 @@ static int test_keys_mlkem1024(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-1024] OK\n"); + printf("[ML-KEM-1024] OK\n"); return 0; } diff --git a/examples/multilevel_build/mlkem_native_all.h b/examples/multilevel_build/mlkem_native_all.h index c7915fd45..94ae407e6 100644 --- a/examples/multilevel_build/mlkem_native_all.h +++ b/examples/multilevel_build/mlkem_native_all.h @@ -6,7 +6,7 @@ #if !defined(MLK_ALL_H) #define MLK_ALL_H -/* API for MLKEM-512 */ +/* API for ML-KEM-512 */ #define MLK_CONFIG_API_PARAMETER_SET 512 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 #include "mlkem_native/mlkem/mlkem_native.h" @@ -14,7 +14,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-768 */ +/* API for ML-KEM-768 */ #define MLK_CONFIG_API_PARAMETER_SET 768 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 #include "mlkem_native/mlkem/mlkem_native.h" @@ -22,7 +22,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-1024 */ +/* API for ML-KEM-1024 */ #define MLK_CONFIG_API_PARAMETER_SET 1024 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 #include "mlkem_native/mlkem/mlkem_native.h" diff --git a/examples/multilevel_build_native/README.md b/examples/multilevel_build_native/README.md index 21da82d28..0f41c37a2 100644 --- a/examples/multilevel_build_native/README.md +++ b/examples/multilevel_build_native/README.md @@ -3,11 +3,11 @@ # Multi-level build This directory contains a minimal example for how to build mlkem-native with support for all 3 security levels -MLKEM-512, MLKEM-768, and MLKEM-1024. All level-independent code is shared, and native backends are in use. +ML-KEM-512, ML-KEM-768, and ML-KEM-1024. All level-independent code is shared, and native backends are in use. -The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the MLKEM-512 build, we set +The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the ML-KEM-512 build, we set `MLK_CONFIG_MULTILEVEL_WITH_SHARED` to force the inclusion of all level-independent code in the -MLKEM512-build. For MLKEM-768 and MLKEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any +MLKEM512-build. For ML-KEM-768 and ML-KEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any level-independent code. Finally, we use the common namespace prefix `mlkem` as `MLK_CONFIG_NAMESPACE_PREFIX` for all three builds; the suffix 512/768/1024 will be added to level-dependent functions automatically. diff --git a/examples/multilevel_build_native/main.c b/examples/multilevel_build_native/main.c index ebcc9c0f2..981b1b9c2 100644 --- a/examples/multilevel_build_native/main.c +++ b/examples/multilevel_build_native/main.c @@ -73,7 +73,7 @@ static int test_keys_mlkem512(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-512] OK\n"); + printf("[ML-KEM-512] OK\n"); return 0; } @@ -128,7 +128,7 @@ static int test_keys_mlkem768(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-768] OK\n"); + printf("[ML-KEM-768] OK\n"); return 0; } @@ -184,7 +184,7 @@ static int test_keys_mlkem1024(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-1024] OK\n"); + printf("[ML-KEM-1024] OK\n"); return 0; } diff --git a/examples/multilevel_build_native/mlkem_native_all.h b/examples/multilevel_build_native/mlkem_native_all.h index c7915fd45..94ae407e6 100644 --- a/examples/multilevel_build_native/mlkem_native_all.h +++ b/examples/multilevel_build_native/mlkem_native_all.h @@ -6,7 +6,7 @@ #if !defined(MLK_ALL_H) #define MLK_ALL_H -/* API for MLKEM-512 */ +/* API for ML-KEM-512 */ #define MLK_CONFIG_API_PARAMETER_SET 512 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 #include "mlkem_native/mlkem/mlkem_native.h" @@ -14,7 +14,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-768 */ +/* API for ML-KEM-768 */ #define MLK_CONFIG_API_PARAMETER_SET 768 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 #include "mlkem_native/mlkem/mlkem_native.h" @@ -22,7 +22,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-1024 */ +/* API for ML-KEM-1024 */ #define MLK_CONFIG_API_PARAMETER_SET 1024 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 #include "mlkem_native/mlkem/mlkem_native.h" diff --git a/examples/multilevel_build_no_stdlib/README.md b/examples/multilevel_build_no_stdlib/README.md index 2102093fb..24b0f8c32 100644 --- a/examples/multilevel_build_no_stdlib/README.md +++ b/examples/multilevel_build_no_stdlib/README.md @@ -2,12 +2,12 @@ # Multi-level build with no standard library -This directory contains a minimal example demonstrating how to build mlkem-native with support for all three security levels: MLKEM-512, MLKEM-768, and MLKEM-1024, and so that level-independent code is shared. Unlike a simple [`multilevel_build`](../multilevel_build/README.md), this example also demonstrates how to replace `mlk_memcpy` and `mlk_memset` with custom implementations, allowing the build to proceed without using the standard library (stdlib). +This directory contains a minimal example demonstrating how to build mlkem-native with support for all three security levels: ML-KEM-512, ML-KEM-768, and ML-KEM-1024, and so that level-independent code is shared. Unlike a simple [`multilevel_build`](../multilevel_build/README.md), this example also demonstrates how to replace `mlk_memcpy` and `mlk_memset` with custom implementations, allowing the build to proceed without using the standard library (stdlib). In this example, only the C-backend of mlkem-native is used. -The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the MLKEM-512 build, we set +The library is built 3 times in different build directories `build/mlkem{512,768,1024}`. For the ML-KEM-512 build, we set `MLK_CONFIG_MULTILEVEL_WITH_SHARED` to force the inclusion of all level-independent code in the -MLKEM512-build. For ML-KEM-768 and ML-KEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any +ML-KEM-512-build. For ML-KEM-768 and ML-KEM-1024, we set `MLK_CONFIG_MULTILEVEL_NO_SHARED` to not include any level-independent code, beside this, this example replace the `mlk_memcpy`, `mlk_memset` with the custom implementation memcpy and memset instead of using the stdlib by adding `example_no_stdlib_config.h`, and add `-nostdlib` to the compilation flags, Finally, we use the common namespace prefix `mlkem` as `MLK_CONFIG_NAMESPACE_PREFIX` for all three builds; the suffix 512/768/1024 will be added to level-dependent functions automatically. diff --git a/examples/multilevel_build_no_stdlib/main.c b/examples/multilevel_build_no_stdlib/main.c index 37e3d2d58..f5aab6e75 100644 --- a/examples/multilevel_build_no_stdlib/main.c +++ b/examples/multilevel_build_no_stdlib/main.c @@ -73,7 +73,7 @@ static int test_keys_mlkem512(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-512] OK\n"); + printf("[ML-KEM-512] OK\n"); return 0; } @@ -128,7 +128,7 @@ static int test_keys_mlkem768(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-768] OK\n"); + printf("[ML-KEM-768] OK\n"); return 0; } @@ -183,7 +183,7 @@ static int test_keys_mlkem1024(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-1024] OK\n"); + printf("[ML-KEM-1024] OK\n"); return 0; } diff --git a/examples/multilevel_build_no_stdlib/mlkem_native_all.h b/examples/multilevel_build_no_stdlib/mlkem_native_all.h index c7915fd45..94ae407e6 100644 --- a/examples/multilevel_build_no_stdlib/mlkem_native_all.h +++ b/examples/multilevel_build_no_stdlib/mlkem_native_all.h @@ -6,7 +6,7 @@ #if !defined(MLK_ALL_H) #define MLK_ALL_H -/* API for MLKEM-512 */ +/* API for ML-KEM-512 */ #define MLK_CONFIG_API_PARAMETER_SET 512 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 #include "mlkem_native/mlkem/mlkem_native.h" @@ -14,7 +14,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-768 */ +/* API for ML-KEM-768 */ #define MLK_CONFIG_API_PARAMETER_SET 768 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 #include "mlkem_native/mlkem/mlkem_native.h" @@ -22,7 +22,7 @@ #undef MLK_CONFIG_API_NAMESPACE_PREFIX #undef MLK_H -/* API for MLKEM-1024 */ +/* API for ML-KEM-1024 */ #define MLK_CONFIG_API_PARAMETER_SET 1024 #define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 #include "mlkem_native/mlkem/mlkem_native.h" diff --git a/mlkem/mlkem_native.S b/mlkem/mlkem_native.S index bff040079..300449973 100644 --- a/mlkem/mlkem_native.S +++ b/mlkem/mlkem_native.S @@ -14,7 +14,7 @@ * Single assembly unit for fixed-level build of mlkem-native * * This assembly unit bundles together all assembly files for a build - * of mlkem-native for a fixed security level (MLKEM-512/768/1024). + * of mlkem-native for a fixed security level (ML-KEM-512/768/1024). * * # Multi-level build * diff --git a/mlkem/mlkem_native.c b/mlkem/mlkem_native.c index 74c1f9387..a96040c94 100644 --- a/mlkem/mlkem_native.c +++ b/mlkem/mlkem_native.c @@ -14,7 +14,7 @@ * Single compilation unit (SCU) for fixed-level build of mlkem-native * * This compilation unit bundles together all source files for a build - * of mlkem-native for a fixed security level (MLKEM-512/768/1024). + * of mlkem-native for a fixed security level (ML-KEM-512/768/1024). * * # API * diff --git a/scripts/autogen b/scripts/autogen index c619f5c06..60b89502c 100755 --- a/scripts/autogen +++ b/scripts/autogen @@ -1369,7 +1369,7 @@ def gen_monolithic_source_file(dry_run=False): yield " * Single compilation unit (SCU) for fixed-level build of mlkem-native" yield " *" yield " * This compilation unit bundles together all source files for a build" - yield " * of mlkem-native for a fixed security level (MLKEM-512/768/1024)." + yield " * of mlkem-native for a fixed security level (ML-KEM-512/768/1024)." yield " *" yield " * # API" yield " *" @@ -1463,7 +1463,7 @@ def gen_monolithic_asm_file(dry_run=False): yield " * Single assembly unit for fixed-level build of mlkem-native" yield " *" yield " * This assembly unit bundles together all assembly files for a build" - yield " * of mlkem-native for a fixed security level (MLKEM-512/768/1024)." + yield " * of mlkem-native for a fixed security level (ML-KEM-512/768/1024)." yield " *" yield " * # Multi-level build" yield " *"