diff --git a/.github/actions/config-variations/action.yml b/.github/actions/config-variations/action.yml index 09a7f454b0..c89256149d 100644 --- a/.github/actions/config-variations/action.yml +++ b/.github/actions/config-variations/action.yml @@ -37,7 +37,7 @@ runs: shell: bash run: | make clean - CFLAGS='-DMLK_CONFIG_FILE=\"../../test/break_pct_config.h\"' make func -j4 + CFLAGS='-Itest -DMLK_CONFIG_FILE=\"break_pct_config.h\"' make func -j4 # PCT breakage is done at runtime via MLK_BREAK_PCT make run_func # Should be OK MLK_BREAK_PCT=0 make run_func # Should be OK @@ -53,7 +53,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_zeroize_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_zeroize_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -66,7 +66,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_1.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_native_capability_config_1.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -79,7 +79,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_0.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_native_capability_config_0.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -92,7 +92,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -march=armv8.4-a+sha3 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_ID_AA64PFR1_EL1.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -march=armv8.4-a+sha3 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_native_capability_config_ID_AA64PFR1_EL1.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -105,7 +105,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -mavx2 -mbmi2 -mpopcnt -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_CPUID_AVX2.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -mavx2 -mbmi2 -mpopcnt -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_native_capability_config_CPUID_AVX2.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -118,7 +118,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/no_asm_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"no_asm_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -131,7 +131,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/serial_fips202_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"serial_fips202_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -144,7 +144,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_randombytes_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_randombytes_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -157,7 +157,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_memcpy_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_memcpy_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -170,7 +170,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_memset_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_memset_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true @@ -183,7 +183,7 @@ runs: with: gh_token: ${{ inputs.gh_token }} compile_mode: native - cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_stdlib_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_stdlib_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" func: true kat: true diff --git a/BIBLIOGRAPHY.md b/BIBLIOGRAPHY.md index 30c0f61350..8e37a5fda7 100644 --- a/BIBLIOGRAPHY.md +++ b/BIBLIOGRAPHY.md @@ -35,20 +35,20 @@ source code and documentation. - National Institute of Standards and Technology * 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/custom_backend/mlkem_native/custom_config.h](examples/custom_backend/mlkem_native/custom_config.h) - - [examples/monolithic_build/config_1024.h](examples/monolithic_build/config_1024.h) - - [examples/monolithic_build/config_512.h](examples/monolithic_build/config_512.h) - - [examples/monolithic_build/config_768.h](examples/monolithic_build/config_768.h) - - [examples/monolithic_build_multilevel/multilevel_config.h](examples/monolithic_build_multilevel/multilevel_config.h) - - [examples/monolithic_build_multilevel_native/multilevel_config.h](examples/monolithic_build_multilevel_native/multilevel_config.h) - - [examples/monolithic_build_native/config_1024.h](examples/monolithic_build_native/config_1024.h) - - [examples/monolithic_build_native/config_512.h](examples/monolithic_build_native/config_512.h) - - [examples/monolithic_build_native/config_768.h](examples/monolithic_build_native/config_768.h) + - [examples/basic_deterministic/mlkem_native/mlkem_native_config.h](examples/basic_deterministic/mlkem_native/mlkem_native_config.h) + - [examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h](examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h) + - [examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h](examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h) + - [examples/custom_backend/mlkem_native/mlkem_native_config.h](examples/custom_backend/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build/mlkem_native/mlkem_native_config.h](examples/monolithic_build/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h](examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h](examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_native/mlkem_native/mlkem_native_config.h](examples/monolithic_build_native/mlkem_native/mlkem_native_config.h) + - [examples/multilevel_build/mlkem_native/mlkem_native_config.h](examples/multilevel_build/mlkem_native/mlkem_native_config.h) + - [examples/multilevel_build_native/mlkem_native/mlkem_native_config.h](examples/multilevel_build_native/mlkem_native/mlkem_native_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) - - [mlkem/src/config.h](mlkem/src/config.h) + - [mlkem/mlkem_native_config.h](mlkem/mlkem_native_config.h) - [mlkem/src/kem.c](mlkem/src/kem.c) - [test/break_pct_config.h](test/break_pct_config.h) - [test/custom_memcpy_config.h](test/custom_memcpy_config.h) @@ -81,20 +81,20 @@ source code and documentation. * URL: https://csrc.nist.gov/pubs/fips/203/final * Referenced from: - [README.md](README.md) - - [examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h](examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h) - - [examples/custom_backend/mlkem_native/custom_config.h](examples/custom_backend/mlkem_native/custom_config.h) - - [examples/monolithic_build/config_1024.h](examples/monolithic_build/config_1024.h) - - [examples/monolithic_build/config_512.h](examples/monolithic_build/config_512.h) - - [examples/monolithic_build/config_768.h](examples/monolithic_build/config_768.h) - - [examples/monolithic_build_multilevel/multilevel_config.h](examples/monolithic_build_multilevel/multilevel_config.h) - - [examples/monolithic_build_multilevel_native/multilevel_config.h](examples/monolithic_build_multilevel_native/multilevel_config.h) - - [examples/monolithic_build_native/config_1024.h](examples/monolithic_build_native/config_1024.h) - - [examples/monolithic_build_native/config_512.h](examples/monolithic_build_native/config_512.h) - - [examples/monolithic_build_native/config_768.h](examples/monolithic_build_native/config_768.h) + - [examples/basic_deterministic/mlkem_native/mlkem_native_config.h](examples/basic_deterministic/mlkem_native/mlkem_native_config.h) + - [examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h](examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h) + - [examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h](examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h) + - [examples/custom_backend/mlkem_native/mlkem_native_config.h](examples/custom_backend/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build/mlkem_native/mlkem_native_config.h](examples/monolithic_build/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h](examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h](examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h) + - [examples/monolithic_build_native/mlkem_native/mlkem_native_config.h](examples/monolithic_build_native/mlkem_native/mlkem_native_config.h) + - [examples/multilevel_build/mlkem_native/mlkem_native_config.h](examples/multilevel_build/mlkem_native/mlkem_native_config.h) + - [examples/multilevel_build_native/mlkem_native/mlkem_native_config.h](examples/multilevel_build_native/mlkem_native/mlkem_native_config.h) - [mlkem/mlkem_native.h](mlkem/mlkem_native.h) + - [mlkem/mlkem_native_config.h](mlkem/mlkem_native_config.h) - [mlkem/src/compress.c](mlkem/src/compress.c) - [mlkem/src/compress.h](mlkem/src/compress.h) - - [mlkem/src/config.h](mlkem/src/config.h) - [mlkem/src/fips202/fips202.c](mlkem/src/fips202/fips202.c) - [mlkem/src/fips202/fips202x4.c](mlkem/src/fips202/fips202x4.c) - [mlkem/src/indcpa.c](mlkem/src/indcpa.c) diff --git a/examples/basic/Makefile b/examples/basic/Makefile index 187f4f2158..ffe3c436f8 100644 --- a/examples/basic/Makefile +++ b/examples/basic/Makefile @@ -54,11 +54,11 @@ endif # In this example, we compile the individual mlkem-native source files directly. # Alternatively, you can compile the 'monobuild' source file mlkem_native.c. # See examples/monolithic_build for that. -MLK_SOURCE=$(wildcard \ - mlkem_native/mlkem/src/*.c \ - mlkem_native/mlkem/src/**/*.c \ - mlkem_native/mlkem/src/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/*.c) +MLK_SOURCE=$(wildcard \ + mlkem_native/src/*.c \ + mlkem_native/src/**/*.c \ + mlkem_native/src/**/**/*.c \ + mlkem_native/src/**/**/**/*.c) # Part B: # @@ -86,6 +86,8 @@ BIN=test_binary # Configuration adjustments # +# Include path for mlkem_native_config.h +CFLAGS += -I mlkem_native # Pick prefix CFLAGS += -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem diff --git a/examples/basic/README.md b/examples/basic/README.md index 82b645b63f..e98040550f 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -1,20 +1,41 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Building mlkem-native +# Basic build -This directory contains a minimal example for how to build mlkem-native. +This directory contains a minimal example for how to build mlkem-native for a single security level. + +## Use Case + +Use this approach when: +- You need only one ML-KEM parameter set (512, 768, or 1024) +- You want to build the mlkem-native C files separately, not as a single compilation unit. +- You're using C only, no native backends. ## Components -An application using mlkem-native as-is needs to include the following components: +1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202) +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Your application source code + +## Configuration -1. mlkem-native source tree, including [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202). -2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h). -3. The application source code +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_PARAMETER_SET`: Security level (512, 768, or 1024). Default is 768. +- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mlkem` in this example. -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +To change the security level, modify `MLK_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS: +```bash +make build CFLAGS="-DMLK_CONFIG_PARAMETER_SET=512" +``` ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/basic/main.c b/examples/basic/main.c index b07e7b66a7..4f35662e35 100644 --- a/examples/basic/main.c +++ b/examples/basic/main.c @@ -11,9 +11,8 @@ * This requires specifying the parameter set and namespace prefix * used for the build. */ -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem -#include "mlkem_native/mlkem/mlkem_native.h" +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem +#include "mlkem_native/mlkem_native.h" #include "test_only_rng/notrandombytes.h" diff --git a/examples/basic/mlkem_native/mlkem b/examples/basic/mlkem_native/mlkem deleted file mode 120000 index f4ec7bdb2d..0000000000 --- a/examples/basic/mlkem_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../../mlkem \ No newline at end of file diff --git a/examples/monolithic_build/mlkem/mlkem_native.h b/examples/basic/mlkem_native/mlkem_native.h similarity index 100% rename from examples/monolithic_build/mlkem/mlkem_native.h rename to examples/basic/mlkem_native/mlkem_native.h diff --git a/examples/basic/mlkem_native/mlkem_native_config.h b/examples/basic/mlkem_native/mlkem_native_config.h new file mode 120000 index 0000000000..5158e37cb3 --- /dev/null +++ b/examples/basic/mlkem_native/mlkem_native_config.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native_config.h \ No newline at end of file diff --git a/examples/basic/mlkem_native/src b/examples/basic/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/basic/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/basic_deterministic/Makefile b/examples/basic_deterministic/Makefile index 39cb2749e5..bc26245a28 100644 --- a/examples/basic_deterministic/Makefile +++ b/examples/basic_deterministic/Makefile @@ -55,10 +55,10 @@ endif # Alternatively, you can compile the 'monobuild' source file mlkem_native.c. # See examples/monolithic_build for that. MLK_SOURCE=$(wildcard \ - mlkem_native/mlkem/src/*.c \ - mlkem_native/mlkem/src/**/*.c \ - mlkem_native/mlkem/src/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/*.c) + mlkem_native/src/*.c \ + mlkem_native/src/**/*.c \ + mlkem_native/src/**/**/*.c \ + mlkem_native/src/**/**/**/*.c) # Part B: # @@ -74,10 +74,8 @@ BIN=test_binary # Configuration adjustments # -# Pick prefix -CFLAGS += -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem -# Set configuration option for deterministic build -CFLAGS += -DMLK_CONFIG_NO_RANDOMIZED_API +# Include path for config +CFLAGS += -Imlkem_native BINARY_NAME_FULL_512=$(BUILD_DIR)/$(BIN)512 BINARY_NAME_FULL_768=$(BUILD_DIR)/$(BIN)768 diff --git a/examples/basic_deterministic/README.md b/examples/basic_deterministic/README.md index 465722080a..e0a92f0d04 100644 --- a/examples/basic_deterministic/README.md +++ b/examples/basic_deterministic/README.md @@ -1,17 +1,37 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Building mlkem-native +# Basic derandomized-only build -This directory contains a minimal example showing how to build **mlkem-native** for use cases only requiring the deterministic key generation and encapsulation APIs (`crypto_kem_keypair_derand` and `crypto_kem_enc_derand`). In that case, no implementation of `randombytes()` has to be provided. +This directory contains a minimal example for building mlkem-native using only the deterministic API, +without requiring a `randombytes()` implementation. + +## Use Case + +Use this approach when: +- Your application manages its own entropy/randomness externally +- You only need `crypto_kem_keypair_derand` and `crypto_kem_enc_derand` (deterministic variants) ## Components -An application using mlkem-native as-is needs to include the following components: +1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202) +2. Your application source code + +No `randombytes()` implementation is required. + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_NO_RANDOMIZED_API`: Disables `crypto_kem_keypair` and `crypto_kem_enc` +- `MLK_CONFIG_PARAMETER_SET`: Security level (default 768) +- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mlkem`) -1. mlkem-native source tree, including [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202). -2. The application source code +## Notes +- This is incompatible with `MLK_CONFIG_KEYGEN_PCT` (pairwise consistency test) ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` diff --git a/examples/basic_deterministic/main.c b/examples/basic_deterministic/main.c index 05f23bc8a6..a7573c92c1 100644 --- a/examples/basic_deterministic/main.c +++ b/examples/basic_deterministic/main.c @@ -11,9 +11,7 @@ * This requires specifying the parameter set and namespace prefix * used for the build. */ -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem -#include "mlkem_native/mlkem/mlkem_native.h" +#include "mlkem_native/mlkem_native.h" /* No randombytes needed for deterministic API */ diff --git a/examples/basic_deterministic/mlkem_native/mlkem b/examples/basic_deterministic/mlkem_native/mlkem deleted file mode 120000 index f4ec7bdb2d..0000000000 --- a/examples/basic_deterministic/mlkem_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../../mlkem \ No newline at end of file diff --git a/examples/basic_deterministic/mlkem_native/mlkem_native.h b/examples/basic_deterministic/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/basic_deterministic/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h b/examples/basic_deterministic/mlkem_native/mlkem_native_config.h similarity index 87% rename from examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h rename to examples/basic_deterministic/mlkem_native/mlkem_native_config.h index a037f0b02b..31feeeca6d 100644 --- a/examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h +++ b/examples/basic_deterministic/mlkem_native/mlkem_native_config.h @@ -25,10 +25,12 @@ */ /* - * Test configuration: Config without randomized API + * Test configuration: Configuration for deterministic-only build of + * mlkem-native * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_NO_RANDOMIZED_API */ @@ -44,6 +46,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,19 +83,103 @@ * * 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). + * In a multi-level build, 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 +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +#define MLK_CONFIG_NO_RANDOMIZED_API + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -381,7 +474,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -404,7 +497,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -424,21 +517,6 @@ *****************************************************************************/ /* #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 * @@ -488,24 +566,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -#define MLK_CONFIG_NO_RANDOMIZED_API - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -535,7 +595,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -567,6 +627,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/basic_deterministic/mlkem_native/src b/examples/basic_deterministic/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/basic_deterministic/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/bring_your_own_fips202/Makefile b/examples/bring_your_own_fips202/Makefile index 7cfadeb88a..538a204bd4 100644 --- a/examples/bring_your_own_fips202/Makefile +++ b/examples/bring_your_own_fips202/Makefile @@ -87,13 +87,8 @@ ALL_SOURCE=$(MLK_SOURCE) $(FIPS202_SOURCE) $(RNG_SOURCE) $(APP_SOURCE) # Configuration adjustments # -# Pick prefix -CFLAGS += -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem -# Tell mlkem-native where to find the header for the custom FIPS202 -# The structure names and function signatures exposed in those headers must -# match those from the standard FIPS202 implementation. See FIPS202.md. -CFLAGS += -DMLK_CONFIG_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\"" -CFLAGS += -DMLK_CONFIG_FIPS202X4_CUSTOM_HEADER="\"../custom_fips202/fips202x4.h\"" +# Include path for mlkem_native_config.h +CFLAGS += -Imlkem_native BUILD_DIR=build BIN=test_binary diff --git a/examples/bring_your_own_fips202/README.md b/examples/bring_your_own_fips202/README.md index fba2630640..5ab5aea024 100644 --- a/examples/bring_your_own_fips202/README.md +++ b/examples/bring_your_own_fips202/README.md @@ -1,26 +1,56 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Bring your own FIPS-202 +# Bring Your Own FIPS-202 -This directory contains a minimal example for how to use mlkem-native as a code package, with a custom FIPS-202 +This directory contains a minimal example for using mlkem-native with a custom FIPS-202 (SHA-3/SHAKE) implementation. We use tiny_sha3[^tiny_sha3] as an example. +## Use Case + +Use this approach when: +- You need only one ML-KEM parameter set (512, 768, or 1024) +- Your application already has a FIPS-202 software/hardware implementation you want to reuse + ## Components -An application using mlkem-native with a custom FIPS-202 implementation needs the following: +1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src) (excluding `fips202/`) +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Custom FIPS-202 implementation with headers compatible with: + - [`fips202.h`](../../mlkem/src/fips202/fips202.h) + - [`fips202x4.h`](../../mlkem/src/fips202/fips202x4.h) +4. Your application source code + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h` +- `MLK_CONFIG_FIPS202X4_CUSTOM_HEADER`: Path to your custom `fips202x4.h` -1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) -2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h). -2. A custom FIPS-202 with `fips202.h` and `fips202x4.h` headers compatible with - [`mlkem/src/fips202/fips202.h`](../../mlkem/src/fips202/fips202.h) and [`mlkem/src/fips202/fips202x4.h`](../../mlkem/src/fips202/fips202x4.h). -3. The application source code +Your custom FIPS-202 implementation must provide: +- `mlk_shake128_absorb_once()`, `mlk_shake128_squeezeblocks()`, `mlk_shake128_release()` +- `mlk_shake256()`, `mlk_sha3_256()`, `mlk_sha3_512()` +- `mlk_shake256x4()` +- `mlk_shake128x4_absorb_once()`, `mlk_shake128x4_squeezeblocks()`, `mlk_shake128x4_release()` +- Structure definitions for `mlk_shake128ctx` and `mlk_shake128x4ctx` -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +See [FIPS202.md](../../FIPS202.md) for the complete API specification. + +## Notes + +- The 4x batched functions (`x4`) can fall back to 4 sequential calls if batching isn't available +- Structure definitions may differ from mlkem-native's defaults (e.g., for incremental hashing) ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3) diff --git a/examples/bring_your_own_fips202/main.c b/examples/bring_your_own_fips202/main.c index 9c37952568..d9a645fe09 100644 --- a/examples/bring_your_own_fips202/main.c +++ b/examples/bring_your_own_fips202/main.c @@ -11,8 +11,7 @@ * This requires specifying the parameter set and namespace prefix * used for the build. */ -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem #include #include "test_only_rng/notrandombytes.h" diff --git a/examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h b/examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h new file mode 100644 index 0000000000..3dc4ce77f2 --- /dev/null +++ b/examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h @@ -0,0 +1,652 @@ +/* + * 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 + * + * - [FIPS203] + * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard + * National Institute of Standards and Technology + * https://csrc.nist.gov/pubs/fips/203/final + */ + +/* + * WARNING: This file is auto-generated from scripts/autogen + * in the mlkem-native repository. + * Do not modify it directly. + */ + +/* + * Test configuration: Configuration for custom FIPS202 implementation + * + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_NAMESPACE_PREFIX + * - MLK_CONFIG_FIPS202_CUSTOM_HEADER + * - MLK_CONFIG_FIPS202X4_CUSTOM_HEADER + */ + + +#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 + * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * + * 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 the 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. + * + *****************************************************************************/ +/* No need to set this -- we _are_ already in a custom config */ +/* #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, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) +/****************************************************************************** + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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 "../custom_fips202/fips202.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 "../custom_fips202/fips202x4.h" + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_ZEROIZE + * + * Description: In compliance with @[FIPS203, 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 "src/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 "src/sys.h" + static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + * + * Description: mlkem-native backends may rely on specific hardware features. + * Those backends will only be included in an mlkem-native build + * if support for the respective features is enabled at + * compile-time. However, when building for a heteroneous set + * of CPUs to run the resulting binary/library on, feature + * detection at _runtime_ is needed to decided whether a backend + * can be used or not. + * + * Set this option and define `mlk_sys_check_capability` if you + * want to use a custom method to dispatch between implementations. + * + * If this option is not set, mlkem-native uses compile-time + * feature detection only to decide which backend to use. + * + * If you compile mlkem-native on a system with different + * capabilities than the system that the resulting binary/library + * will be run on, you must use this option. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) + __contract__( + ensures(return_value == 0 || return_value == 1) + ) + { + ... your implementation ... + } +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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_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_NO_ASM_VALUE_BARRIER + * + * Description: If this option is set, mlkem-native will be built without + * use of native code or inline assembly for value barriers. + * + * By default, inline assembly (if available) is used to implement + * value barriers. + * Without inline assembly, mlkem-native will use a global volatile + * 'opt blocker' instead; see verify.h. + * + *****************************************************************************/ +/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE int mlk_break_pct(void) + { + ... return 0/1 depending on whether PCT should be broken ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY + * + * Description: Set this to use a FIPS202 implementation with global state + * that supports only one active Keccak computation at a time + * (e.g. some hardware accelerators). + * + * If this option is set, batched Keccak operations are + * disabled for rejection sampling during matrix generation. + * Instead, matrix entries will be generated one at a time. + * + * This allows offloading Keccak computations to a hardware + * accelerator that holds only a single Keccak state locally, + * rather than requiring support for batched (4x) Keccak states. + * + * NOTE: Depending on the target CPU, disabling batched Keccak + * may reduce performance when using software FIPS202 + * implementations. Only enable this when you have to. + * + *****************************************************************************/ +/* #define MLK_CONFIG_SERIAL_FIPS202_ONLY */ + +/************************* Config internals ********************************/ + +#endif /* MLK_BUILD_INTERNAL */ + +/* 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/bring_your_own_fips202/mlkem_native/src/config.h b/examples/bring_your_own_fips202/mlkem_native/src/config.h deleted file mode 120000 index 565d9cd744..0000000000 --- a/examples/bring_your_own_fips202/mlkem_native/src/config.h +++ /dev/null @@ -1 +0,0 @@ -../../../../mlkem/src/config.h \ No newline at end of file diff --git a/examples/bring_your_own_fips202/mlkem_native/src/native b/examples/bring_your_own_fips202/mlkem_native/src/native deleted file mode 120000 index 5083e395c3..0000000000 --- a/examples/bring_your_own_fips202/mlkem_native/src/native +++ /dev/null @@ -1 +0,0 @@ -../../../../mlkem/src/native \ No newline at end of file diff --git a/examples/bring_your_own_fips202_static/Makefile b/examples/bring_your_own_fips202_static/Makefile index 3e449d47e6..538a204bd4 100644 --- a/examples/bring_your_own_fips202_static/Makefile +++ b/examples/bring_your_own_fips202_static/Makefile @@ -87,13 +87,8 @@ ALL_SOURCE=$(MLK_SOURCE) $(FIPS202_SOURCE) $(RNG_SOURCE) $(APP_SOURCE) # Configuration adjustments # -# Pick prefix -CFLAGS += -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem -# Tell mlkem-native to use serial-FIPS202 only -CFLAGS += -DMLK_CONFIG_SERIAL_FIPS202_ONLY -# Tell mlkem-native where to find the header for the custom FIPS202 -CFLAGS += -DMLK_CONFIG_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\"" -CFLAGS += -DMLK_CONFIG_FIPS202X4_CUSTOM_HEADER="\"../custom_fips202/fips202x4.h\"" +# Include path for mlkem_native_config.h +CFLAGS += -Imlkem_native BUILD_DIR=build BIN=test_binary diff --git a/examples/bring_your_own_fips202_static/README.md b/examples/bring_your_own_fips202_static/README.md index c0cbcba8be..76f608ead4 100644 --- a/examples/bring_your_own_fips202_static/README.md +++ b/examples/bring_your_own_fips202_static/README.md @@ -1,28 +1,56 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Bring your own FIPS-202 (Static State Variant) +# Bring Your Own FIPS-202 (Static State Variant) -This directory contains a minimal example for how to use mlkem-native with external FIPS202 -HW/SW-implementations that use a single global state (for example, some hardware accelerators). -Specifically, this example demonstrates the use of the serial-only FIPS-202 configuration -`MLK_CONFIG_SERIAL_FIPS202_ONLY`. +This directory contains a minimal example for using mlkem-native with a custom FIPS-202 implementation +that uses a single global state. This is common for hardware accelerators that can only hold one +Keccak state at a time. + +## Use Case + +Use this approach when: +- You need only one ML-KEM parameter set (512, 768, or 1024) +- Your application already has a FIPS-202 software/hardware implementation you want to reuse +- Your FIPS-202 implementation does not support multiple active SHA3/SHAKE computations. ## Components -An application using mlkem-native with a custom FIPS-202 implementation needs the following: +1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src) (excluding `fips202/`) +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Custom FIPS-202 implementation with headers compatible with [`fips202.h`](../../mlkem/src/fips202/fips202.h) + and [`fips202x4.h`](../../mlkem/src/fips202/fips202x4.h) +4. Your application source code + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_SERIAL_FIPS202_ONLY`: Disables batched Keccak; matrix entries generated one at a time +- `MLK_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h` +- `MLK_CONFIG_FIPS202X4_CUSTOM_HEADER`: Path to stub `fips202x4.h` -1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) -2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h). -2. A custom FIPS202 with `fips202.h` header compatible with [`mlkem/src/fips202/fips202.h`](../../mlkem/src/fips202/fips202.h). - The FIPS202x4 header `fips202x4.h` is unused with `MLK_CONFIG_SERIAL_FIPS202_ONLY` and can be filled with stubs. -3. The application source code +Your custom FIPS-202 implementation must provide: +- `mlk_shake128_absorb_once()`, `mlk_shake128_squeezeblocks()`, `mlk_shake128_release()` +- `mlk_shake256()`, `mlk_sha3_256()`, `mlk_sha3_512()` +- `mlk_shake256x4()` +- Structure definition for `mlk_shake128ctx` -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +## Notes + +- `MLK_CONFIG_SERIAL_FIPS202_ONLY` may reduce performance on CPUs with SIMD support +- Matrix generation becomes sequential instead of batched (4 entries at a time) +- Only enable this when your hardware requires it ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3) diff --git a/examples/bring_your_own_fips202_static/main.c b/examples/bring_your_own_fips202_static/main.c index 9c37952568..d9a645fe09 100644 --- a/examples/bring_your_own_fips202_static/main.c +++ b/examples/bring_your_own_fips202_static/main.c @@ -11,8 +11,7 @@ * This requires specifying the parameter set and namespace prefix * used for the build. */ -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem #include #include "test_only_rng/notrandombytes.h" diff --git a/examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h b/examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h new file mode 100644 index 0000000000..4ca11d0cdf --- /dev/null +++ b/examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h @@ -0,0 +1,653 @@ +/* + * 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 + * + * - [FIPS203] + * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard + * National Institute of Standards and Technology + * https://csrc.nist.gov/pubs/fips/203/final + */ + +/* + * WARNING: This file is auto-generated from scripts/autogen + * in the mlkem-native repository. + * Do not modify it directly. + */ + +/* + * Test configuration: Configuration for custom serial FIPS202 implementation + * + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_NAMESPACE_PREFIX + * - MLK_CONFIG_SERIAL_FIPS202_ONLY + * - MLK_CONFIG_FIPS202_CUSTOM_HEADER + * - MLK_CONFIG_FIPS202X4_CUSTOM_HEADER + */ + + +#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 + * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * + * 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 the 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. + * + *****************************************************************************/ +/* No need to set this -- we _are_ already in a custom config */ +/* #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, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) +/****************************************************************************** + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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 "../custom_fips202/fips202.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 "../custom_fips202/fips202x4.h" + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_ZEROIZE + * + * Description: In compliance with @[FIPS203, 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 "src/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 "src/sys.h" + static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + * + * Description: mlkem-native backends may rely on specific hardware features. + * Those backends will only be included in an mlkem-native build + * if support for the respective features is enabled at + * compile-time. However, when building for a heteroneous set + * of CPUs to run the resulting binary/library on, feature + * detection at _runtime_ is needed to decided whether a backend + * can be used or not. + * + * Set this option and define `mlk_sys_check_capability` if you + * want to use a custom method to dispatch between implementations. + * + * If this option is not set, mlkem-native uses compile-time + * feature detection only to decide which backend to use. + * + * If you compile mlkem-native on a system with different + * capabilities than the system that the resulting binary/library + * will be run on, you must use this option. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) + __contract__( + ensures(return_value == 0 || return_value == 1) + ) + { + ... your implementation ... + } +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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_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_NO_ASM_VALUE_BARRIER + * + * Description: If this option is set, mlkem-native will be built without + * use of native code or inline assembly for value barriers. + * + * By default, inline assembly (if available) is used to implement + * value barriers. + * Without inline assembly, mlkem-native will use a global volatile + * 'opt blocker' instead; see verify.h. + * + *****************************************************************************/ +/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE int mlk_break_pct(void) + { + ... return 0/1 depending on whether PCT should be broken ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY + * + * Description: Set this to use a FIPS202 implementation with global state + * that supports only one active Keccak computation at a time + * (e.g. some hardware accelerators). + * + * If this option is set, batched Keccak operations are + * disabled for rejection sampling during matrix generation. + * Instead, matrix entries will be generated one at a time. + * + * This allows offloading Keccak computations to a hardware + * accelerator that holds only a single Keccak state locally, + * rather than requiring support for batched (4x) Keccak states. + * + * NOTE: Depending on the target CPU, disabling batched Keccak + * may reduce performance when using software FIPS202 + * implementations. Only enable this when you have to. + * + *****************************************************************************/ +#define MLK_CONFIG_SERIAL_FIPS202_ONLY + +/************************* Config internals ********************************/ + +#endif /* MLK_BUILD_INTERNAL */ + +/* 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/bring_your_own_fips202_static/mlkem_native/src/config.h b/examples/bring_your_own_fips202_static/mlkem_native/src/config.h deleted file mode 120000 index 565d9cd744..0000000000 --- a/examples/bring_your_own_fips202_static/mlkem_native/src/config.h +++ /dev/null @@ -1 +0,0 @@ -../../../../mlkem/src/config.h \ No newline at end of file diff --git a/examples/custom_backend/Makefile b/examples/custom_backend/Makefile index da5b4401b5..833350bceb 100644 --- a/examples/custom_backend/Makefile +++ b/examples/custom_backend/Makefile @@ -52,13 +52,13 @@ endif # Alternatively, you can compile the 'monobuild' source file mlkem_native.c. # See examples/monolithic_build for that. MLK_SOURCE=$(wildcard \ - mlkem_native/mlkem/src/*.c \ - mlkem_native/mlkem/src/**/*.c \ - mlkem_native/mlkem/src/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/**/*.c) + mlkem_native/src/*.c \ + mlkem_native/src/**/*.c \ + mlkem_native/src/**/**/*.c \ + mlkem_native/src/**/**/**/*.c \ + mlkem_native/src/**/**/**/**/*.c) -INC=-Imlkem_native -Imlkem_native/mlkem +INC=-Imlkem_native # Part B: # @@ -84,8 +84,7 @@ ALL_SOURCE=$(MLK_SOURCE) $(RNG_SOURCE) $(APP_SOURCE) # Configuration adjustments # -# Pick custom config file -CFLAGS+=-DMLK_CONFIG_FILE="\"custom_config.h\"" +CFLAGS += -Imlkem_native BUILD_DIR=build BIN=test_binary diff --git a/examples/custom_backend/README.md b/examples/custom_backend/README.md index b21f1e4dd4..03f26fe395 100644 --- a/examples/custom_backend/README.md +++ b/examples/custom_backend/README.md @@ -1,39 +1,70 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Using a custom configuration and FIPS-202 backend +# Custom FIPS-202 Backend -This directory contains a minimal example for how to use mlkem-native as a code package, with a custom FIPS-202 -backend and a custom configuration. We use [^tiny_sha3] as an example. +This directory contains a minimal example for using mlkem-native with a custom FIPS-202 *backend* +(as opposed to a complete custom FIPS-202 implementation). We use tiny_sha3[^tiny_sha3] as an example. + +## Use Case + +Use this approach when: +- You need only one ML-KEM parameter set (512, 768, or 1024) +- You want to replace the low-level Keccak-f1600 permutation +- You want to keep mlkem-native's FIPS-202 frontend (absorb/squeeze logic) + +This differs from `bring_your_own_fips202` in that you only replace the *backend* (Keccak permutation), +not the entire FIPS-202 implementation. ## Components -An application using mlkem-native with a custom FIPS-202 backend and custom configuration needs the following: - -1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src). In this example, we disable arithmetic - backends, hence it is safe to remove the entire `native` subfolder. -2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h). **WARNING:** The - `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation outside of testing. -3. FIPS-202 part of the mlkem-native source tree, [`fips202/`](../../mlkem/src/fips202). If you only want to use your backend, - you can remove all existing backends; that's what this example does. -4. A custom FIPS-202 backend. In this example, the backend file is - [custom.h](mlkem_native/mlkem/src/fips202/native/custom/custom.h), wrapping - [sha3.c](mlkem_native/mlkem/src/fips202/native/custom/src/sha3.c) and setting `MLK_USE_FIPS202_X1_NATIVE` to indicate that we - replace 1-fold Keccak-F1600. -5. Either modify the existing [config.h](mlkem_native/mlkem/src/config.h), or register a new config. In this example, we add - a new config [custom_config.h](mlkem_native/custom_config.h) and register it from the command line for - `-DMLK_CONFIG_FILE="custom_config.h"` -- no further changes to the build are needed. For the sake of - demonstration, we set a custom namespace. We set `MLK_CONFIG_FIPS202_BACKEND_FILE` to point to our custom FIPS-202 - backend, but leave `MLK_CONFIG_USE_NATIVE_BACKEND_ARITH` undefined to indicate that we wish to use the C backend. - -## Note - -The tiny_sha3 code uses a byte-reversed presentation of the Keccakf1600 state for big-endian targets. Since -mlkem-native's FIPS202 frontend assumes a standard presentation, the corresponding byte-reversal in -[sha3.c](mlkem_native/mlkem/src/fips202/native/custom/src/sha3.c) is removed. +1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src) +2. FIPS-202 frontend: [`mlkem/src/fips202/`](../../mlkem/src/fips202) (can remove existing backends) +3. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +4. Custom FIPS-202 backend (see below) +5. Your application source code + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202`: Enables native FIPS-202 backend +- `MLK_CONFIG_FIPS202_BACKEND_FILE`: Path to your custom backend metadata file + +A custom backend consists of: +1. A metadata header (e.g., [custom.h](mlkem_native/src/fips202/native/custom/custom.h)) that: + - Sets `MLK_USE_FIPS202_X1_NATIVE` (and/or `X2`/`X4`) to indicate which functions are replaced + - Includes the implementation header +2. An implementation providing `mlk_keccakf1600_native()` (and/or batched variants) + +Example backend metadata file: +```c +#ifndef CUSTOM_FIPS202_BACKEND_H +#define CUSTOM_FIPS202_BACKEND_H + +/* Indicate we're replacing 1-fold Keccak-f1600 */ +#define MLK_USE_FIPS202_X1_NATIVE + +/* Include the implementation */ +#include "custom/src/keccak_impl.h" + +#endif +``` + +## Notes + +- The tiny_sha3 code uses byte-reversed Keccak state on big-endian targets; this example removes + that reversal since mlkem-native's frontend assumes standard byte order ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3) diff --git a/examples/custom_backend/main.c b/examples/custom_backend/main.c index 6fc45ecdaa..b8c1a5635d 100644 --- a/examples/custom_backend/main.c +++ b/examples/custom_backend/main.c @@ -11,8 +11,7 @@ * This requires specifying the parameter set and namespace prefix * used for the build. */ -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX CUSTOM_TINY_SHA3 +#define MLK_CONFIG_NAMESPACE_PREFIX CUSTOM_TINY_SHA3 #include #include "test_only_rng/notrandombytes.h" diff --git a/examples/custom_backend/mlkem_native/mlkem/mlkem_native.h b/examples/custom_backend/mlkem_native/mlkem/mlkem_native.h deleted file mode 120000 index 06ee803ec1..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/mlkem_native.h +++ /dev/null @@ -1 +0,0 @@ -../../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/cbmc.h b/examples/custom_backend/mlkem_native/mlkem/src/cbmc.h deleted file mode 120000 index e04fe9133b..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/cbmc.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/cbmc.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/common.h b/examples/custom_backend/mlkem_native/mlkem/src/common.h deleted file mode 120000 index 6240991365..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/common.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/common.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/compress.c b/examples/custom_backend/mlkem_native/mlkem/src/compress.c deleted file mode 120000 index ac78452f19..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/compress.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/compress.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/compress.h b/examples/custom_backend/mlkem_native/mlkem/src/compress.h deleted file mode 120000 index a1cd4700a6..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/compress.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/compress.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/config.h b/examples/custom_backend/mlkem_native/mlkem/src/config.h deleted file mode 120000 index 1b0ccd6af4..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/config.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/config.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/debug.c b/examples/custom_backend/mlkem_native/mlkem/src/debug.c deleted file mode 120000 index 712d8afe4c..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/debug.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/debug.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/debug.h b/examples/custom_backend/mlkem_native/mlkem/src/debug.h deleted file mode 120000 index f0d7542536..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/debug.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/debug.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.c b/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.c deleted file mode 120000 index ca4f60193e..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/fips202.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.h b/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.h deleted file mode 120000 index 2f29452d23..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/fips202.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.c b/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.c deleted file mode 120000 index dea931d516..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/fips202x4.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.h b/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.h deleted file mode 120000 index 6f07c482d1..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/fips202x4.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/fips202x4.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.c b/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.c deleted file mode 120000 index 588af7bc71..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/keccakf1600.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.h b/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.h deleted file mode 120000 index e8f902838f..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/keccakf1600.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../../mlkem/src/fips202/keccakf1600.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/api.h b/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/api.h deleted file mode 120000 index 08ad7290c6..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/api.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../../../mlkem/src/fips202/native/api.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/indcpa.c b/examples/custom_backend/mlkem_native/mlkem/src/indcpa.c deleted file mode 120000 index 9a4404d761..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/indcpa.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/indcpa.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/indcpa.h b/examples/custom_backend/mlkem_native/mlkem/src/indcpa.h deleted file mode 120000 index 3e51d9b966..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/indcpa.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/indcpa.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/kem.c b/examples/custom_backend/mlkem_native/mlkem/src/kem.c deleted file mode 120000 index cc50fbaf9d..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/kem.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/kem.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/kem.h b/examples/custom_backend/mlkem_native/mlkem/src/kem.h deleted file mode 120000 index 7edc04126d..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/kem.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/kem.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/params.h b/examples/custom_backend/mlkem_native/mlkem/src/params.h deleted file mode 120000 index d952c6661f..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/params.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/params.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/poly.c b/examples/custom_backend/mlkem_native/mlkem/src/poly.c deleted file mode 120000 index 19563c27b5..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/poly.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/poly.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/poly.h b/examples/custom_backend/mlkem_native/mlkem/src/poly.h deleted file mode 120000 index 61f3c4c8bb..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/poly.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/poly.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/poly_k.c b/examples/custom_backend/mlkem_native/mlkem/src/poly_k.c deleted file mode 120000 index d3b12a5cbe..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/poly_k.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/poly_k.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/poly_k.h b/examples/custom_backend/mlkem_native/mlkem/src/poly_k.h deleted file mode 120000 index dfc1e25f03..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/poly_k.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/poly_k.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/randombytes.h b/examples/custom_backend/mlkem_native/mlkem/src/randombytes.h deleted file mode 120000 index f50dba95f4..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/randombytes.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/randombytes.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/sampling.c b/examples/custom_backend/mlkem_native/mlkem/src/sampling.c deleted file mode 120000 index b2ee0a6fad..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/sampling.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/sampling.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/sampling.h b/examples/custom_backend/mlkem_native/mlkem/src/sampling.h deleted file mode 120000 index 134ced942d..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/sampling.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/sampling.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/symmetric.h b/examples/custom_backend/mlkem_native/mlkem/src/symmetric.h deleted file mode 120000 index ed44b1d06f..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/symmetric.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/symmetric.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/sys.h b/examples/custom_backend/mlkem_native/mlkem/src/sys.h deleted file mode 120000 index 6dc25f5704..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/sys.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/sys.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/verify.c b/examples/custom_backend/mlkem_native/mlkem/src/verify.c deleted file mode 120000 index f27d9756da..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/verify.c +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/verify.c \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/verify.h b/examples/custom_backend/mlkem_native/mlkem/src/verify.h deleted file mode 120000 index bb4f867dcf..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/verify.h +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/verify.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/zetas.inc b/examples/custom_backend/mlkem_native/mlkem/src/zetas.inc deleted file mode 120000 index 525b8c55cd..0000000000 --- a/examples/custom_backend/mlkem_native/mlkem/src/zetas.inc +++ /dev/null @@ -1 +0,0 @@ -../../../../../mlkem/src/zetas.inc \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem_native.h b/examples/custom_backend/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/custom_backend/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/custom_config.h b/examples/custom_backend/mlkem_native/mlkem_native_config.h similarity index 88% rename from examples/custom_backend/mlkem_native/custom_config.h rename to examples/custom_backend/mlkem_native/mlkem_native_config.h index 85b9f9202e..69cb9f0db3 100644 --- a/examples/custom_backend/mlkem_native/custom_config.h +++ b/examples/custom_backend/mlkem_native/mlkem_native_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Custom backend config with tiny SHA3 * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_USE_NATIVE_BACKEND_ARITH * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 @@ -47,6 +47,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -80,17 +85,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX CUSTOM_TINY_SHA3 +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -110,6 +201,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,6 +223,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -296,7 +389,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -322,7 +415,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -377,7 +470,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -400,7 +493,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -420,21 +513,6 @@ *****************************************************************************/ /* #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 * @@ -484,24 +562,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -531,7 +591,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -563,6 +623,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/monolithic_build/mlkem/src/cbmc.h b/examples/custom_backend/mlkem_native/src/cbmc.h similarity index 100% rename from examples/monolithic_build/mlkem/src/cbmc.h rename to examples/custom_backend/mlkem_native/src/cbmc.h diff --git a/examples/monolithic_build/mlkem/src/common.h b/examples/custom_backend/mlkem_native/src/common.h similarity index 100% rename from examples/monolithic_build/mlkem/src/common.h rename to examples/custom_backend/mlkem_native/src/common.h diff --git a/examples/monolithic_build/mlkem/src/compress.c b/examples/custom_backend/mlkem_native/src/compress.c similarity index 100% rename from examples/monolithic_build/mlkem/src/compress.c rename to examples/custom_backend/mlkem_native/src/compress.c diff --git a/examples/monolithic_build/mlkem/src/compress.h b/examples/custom_backend/mlkem_native/src/compress.h similarity index 100% rename from examples/monolithic_build/mlkem/src/compress.h rename to examples/custom_backend/mlkem_native/src/compress.h diff --git a/examples/monolithic_build/mlkem/src/debug.c b/examples/custom_backend/mlkem_native/src/debug.c similarity index 100% rename from examples/monolithic_build/mlkem/src/debug.c rename to examples/custom_backend/mlkem_native/src/debug.c diff --git a/examples/monolithic_build/mlkem/src/debug.h b/examples/custom_backend/mlkem_native/src/debug.h similarity index 100% rename from examples/monolithic_build/mlkem/src/debug.h rename to examples/custom_backend/mlkem_native/src/debug.h diff --git a/examples/monolithic_build/mlkem/src/fips202/fips202.c b/examples/custom_backend/mlkem_native/src/fips202/fips202.c similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/fips202.c rename to examples/custom_backend/mlkem_native/src/fips202/fips202.c diff --git a/examples/monolithic_build/mlkem/src/fips202/fips202.h b/examples/custom_backend/mlkem_native/src/fips202/fips202.h similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/fips202.h rename to examples/custom_backend/mlkem_native/src/fips202/fips202.h diff --git a/examples/monolithic_build/mlkem/src/fips202/fips202x4.c b/examples/custom_backend/mlkem_native/src/fips202/fips202x4.c similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/fips202x4.c rename to examples/custom_backend/mlkem_native/src/fips202/fips202x4.c diff --git a/examples/monolithic_build/mlkem/src/fips202/fips202x4.h b/examples/custom_backend/mlkem_native/src/fips202/fips202x4.h similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/fips202x4.h rename to examples/custom_backend/mlkem_native/src/fips202/fips202x4.h diff --git a/examples/monolithic_build/mlkem/src/fips202/keccakf1600.c b/examples/custom_backend/mlkem_native/src/fips202/keccakf1600.c similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/keccakf1600.c rename to examples/custom_backend/mlkem_native/src/fips202/keccakf1600.c diff --git a/examples/monolithic_build/mlkem/src/fips202/keccakf1600.h b/examples/custom_backend/mlkem_native/src/fips202/keccakf1600.h similarity index 100% rename from examples/monolithic_build/mlkem/src/fips202/keccakf1600.h rename to examples/custom_backend/mlkem_native/src/fips202/keccakf1600.h diff --git a/examples/custom_backend/mlkem_native/src/fips202/native/api.h b/examples/custom_backend/mlkem_native/src/fips202/native/api.h new file mode 120000 index 0000000000..890c69b6aa --- /dev/null +++ b/examples/custom_backend/mlkem_native/src/fips202/native/api.h @@ -0,0 +1 @@ +../../../../../../mlkem/src/fips202/native/api.h \ No newline at end of file diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/custom.h b/examples/custom_backend/mlkem_native/src/fips202/native/custom/custom.h similarity index 100% rename from examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/custom.h rename to examples/custom_backend/mlkem_native/src/fips202/native/custom/custom.h diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/LICENSE b/examples/custom_backend/mlkem_native/src/fips202/native/custom/src/LICENSE similarity index 100% rename from examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/LICENSE rename to examples/custom_backend/mlkem_native/src/fips202/native/custom/src/LICENSE diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/README.md b/examples/custom_backend/mlkem_native/src/fips202/native/custom/src/README.md similarity index 100% rename from examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/README.md rename to examples/custom_backend/mlkem_native/src/fips202/native/custom/src/README.md diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/sha3.c b/examples/custom_backend/mlkem_native/src/fips202/native/custom/src/sha3.c similarity index 100% rename from examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/sha3.c rename to examples/custom_backend/mlkem_native/src/fips202/native/custom/src/sha3.c diff --git a/examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/sha3.h b/examples/custom_backend/mlkem_native/src/fips202/native/custom/src/sha3.h similarity index 100% rename from examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/sha3.h rename to examples/custom_backend/mlkem_native/src/fips202/native/custom/src/sha3.h diff --git a/examples/monolithic_build/mlkem/src/indcpa.c b/examples/custom_backend/mlkem_native/src/indcpa.c similarity index 100% rename from examples/monolithic_build/mlkem/src/indcpa.c rename to examples/custom_backend/mlkem_native/src/indcpa.c diff --git a/examples/monolithic_build/mlkem/src/indcpa.h b/examples/custom_backend/mlkem_native/src/indcpa.h similarity index 100% rename from examples/monolithic_build/mlkem/src/indcpa.h rename to examples/custom_backend/mlkem_native/src/indcpa.h diff --git a/examples/monolithic_build/mlkem/src/kem.c b/examples/custom_backend/mlkem_native/src/kem.c similarity index 100% rename from examples/monolithic_build/mlkem/src/kem.c rename to examples/custom_backend/mlkem_native/src/kem.c diff --git a/examples/monolithic_build/mlkem/src/kem.h b/examples/custom_backend/mlkem_native/src/kem.h similarity index 100% rename from examples/monolithic_build/mlkem/src/kem.h rename to examples/custom_backend/mlkem_native/src/kem.h diff --git a/examples/monolithic_build/mlkem/src/params.h b/examples/custom_backend/mlkem_native/src/params.h similarity index 100% rename from examples/monolithic_build/mlkem/src/params.h rename to examples/custom_backend/mlkem_native/src/params.h diff --git a/examples/monolithic_build/mlkem/src/poly.c b/examples/custom_backend/mlkem_native/src/poly.c similarity index 100% rename from examples/monolithic_build/mlkem/src/poly.c rename to examples/custom_backend/mlkem_native/src/poly.c diff --git a/examples/monolithic_build/mlkem/src/poly.h b/examples/custom_backend/mlkem_native/src/poly.h similarity index 100% rename from examples/monolithic_build/mlkem/src/poly.h rename to examples/custom_backend/mlkem_native/src/poly.h diff --git a/examples/monolithic_build/mlkem/src/poly_k.c b/examples/custom_backend/mlkem_native/src/poly_k.c similarity index 100% rename from examples/monolithic_build/mlkem/src/poly_k.c rename to examples/custom_backend/mlkem_native/src/poly_k.c diff --git a/examples/monolithic_build/mlkem/src/poly_k.h b/examples/custom_backend/mlkem_native/src/poly_k.h similarity index 100% rename from examples/monolithic_build/mlkem/src/poly_k.h rename to examples/custom_backend/mlkem_native/src/poly_k.h diff --git a/examples/monolithic_build/mlkem/src/randombytes.h b/examples/custom_backend/mlkem_native/src/randombytes.h similarity index 100% rename from examples/monolithic_build/mlkem/src/randombytes.h rename to examples/custom_backend/mlkem_native/src/randombytes.h diff --git a/examples/monolithic_build/mlkem/src/sampling.c b/examples/custom_backend/mlkem_native/src/sampling.c similarity index 100% rename from examples/monolithic_build/mlkem/src/sampling.c rename to examples/custom_backend/mlkem_native/src/sampling.c diff --git a/examples/monolithic_build/mlkem/src/sampling.h b/examples/custom_backend/mlkem_native/src/sampling.h similarity index 100% rename from examples/monolithic_build/mlkem/src/sampling.h rename to examples/custom_backend/mlkem_native/src/sampling.h diff --git a/examples/monolithic_build/mlkem/src/symmetric.h b/examples/custom_backend/mlkem_native/src/symmetric.h similarity index 100% rename from examples/monolithic_build/mlkem/src/symmetric.h rename to examples/custom_backend/mlkem_native/src/symmetric.h diff --git a/examples/monolithic_build/mlkem/src/sys.h b/examples/custom_backend/mlkem_native/src/sys.h similarity index 100% rename from examples/monolithic_build/mlkem/src/sys.h rename to examples/custom_backend/mlkem_native/src/sys.h diff --git a/examples/monolithic_build/mlkem/src/verify.c b/examples/custom_backend/mlkem_native/src/verify.c similarity index 100% rename from examples/monolithic_build/mlkem/src/verify.c rename to examples/custom_backend/mlkem_native/src/verify.c diff --git a/examples/monolithic_build/mlkem/src/verify.h b/examples/custom_backend/mlkem_native/src/verify.h similarity index 100% rename from examples/monolithic_build/mlkem/src/verify.h rename to examples/custom_backend/mlkem_native/src/verify.h diff --git a/examples/monolithic_build/mlkem/src/zetas.inc b/examples/custom_backend/mlkem_native/src/zetas.inc similarity index 100% rename from examples/monolithic_build/mlkem/src/zetas.inc rename to examples/custom_backend/mlkem_native/src/zetas.inc diff --git a/examples/monolithic_build/Makefile b/examples/monolithic_build/Makefile index b9dd6fe157..4461010702 100644 --- a/examples/monolithic_build/Makefile +++ b/examples/monolithic_build/Makefile @@ -52,9 +52,9 @@ Q ?= @ # Here, we use just a single monolithic compilation unit to include # multiple instances of mlkem-native. -MLK_SOURCE=mlkem/mlkem_native.c +MLK_SOURCE=mlkem_native/mlkem_native.c -INC=-Imlkem/ -I./ +INC=-Imlkem_native # Part B: # @@ -92,38 +92,38 @@ LIB1024_FULL=$(BUILD_DIR)/$(LIB1024) $(LIB512_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_512.h\"" $(INC) $^ -o $(BUILD_DIR)/mlkem_native512.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=512 $(INC) $^ -o $(BUILD_DIR)/mlkem_native512.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native512.o $(Q)strip -S $@ $(LIB768_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_768.h\"" $(INC) $^ -o $(BUILD_DIR)/mlkem_native768.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=768 $(INC) $^ -o $(BUILD_DIR)/mlkem_native768.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native768.o $(Q)strip -S $@ $(LIB1024_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_1024.h\"" $(INC) $^ -o $(BUILD_DIR)/mlkem_native1024.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) $^ -o $(BUILD_DIR)/mlkem_native1024.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native1024.o $(Q)strip -S $@ $(BIN512_FULL): $(APP_SOURCE) $(LIB512_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=512 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=512 $(INC) $^ -o $@ $(BIN768_FULL): $(APP_SOURCE) $(LIB768_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=768 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=768 $(INC) $^ -o $@ $(BIN1024_FULL): $(APP_SOURCE) $(LIB1024_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=1024 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) $^ -o $@ all: build diff --git a/examples/monolithic_build/README.md b/examples/monolithic_build/README.md index 1519ccbbc6..fa44a3548c 100644 --- a/examples/monolithic_build/README.md +++ b/examples/monolithic_build/README.md @@ -1,17 +1,50 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Single-level mlkem-native in a single compilation unit +# Monolithic Build (C Backend) -This directory contains a minimal example for how to build a single instance of mlkem-native in a single compilation -unit. Only the C-backend is exercised. +This directory contains a minimal example for building mlkem-native for a single +parameter set of ML-KEM as a single compilation unit using the auto-generated +`mlkem_native.c` file. -The auto-generated source file [mlkem_native.c](mlkem/mlkem_native.c) includes all mlkem-native C source -files. Moreover, it clears all `#define`s clauses set by mlkem-native at the end, and is hence amenable to multiple -inclusion in another compilation unit. It exposes the API [../../mlkem/mlkem_native.h](mlkem/mlkem_native.h). +## Use Case + +Use this approach when: +- You want the simplest possible build integration (one `.c` file) +- You're using only C (no native backends) +- You need only one ML-KEM parameter set (512, 768, or 1024) + +## Components + +1. Source tree [mlkem_native/*](mlkem_native), including top-level compilation unit + [mlkem_native.c](mlkem_native/mlkem_native.c) (gathering all C sources) + and the mlkem-native API [mlkem_native.h](mlkem_native/mlkem_native.h). +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Your application source code + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_PARAMETER_SET`: Security level (default 768) +- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mlkem`) +- `MLK_CONFIG_INTERNAL_API_QUALIFIER=static`: Makes internal functions static for single-CU builds + +The auto-generated `mlkem_native.c`: +- Includes all mlkem-native C source files +- Clears all internal `#define`s at the end, allowing multiple inclusion + +## Notes + +- The monolithic `.c` file is auto-generated by `scripts/autogen` +- Internal functions become `static`, enabling better compiler optimization ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/monolithic_build/main.c b/examples/monolithic_build/main.c index cc52623c96..845eec55f2 100644 --- a/examples/monolithic_build/main.c +++ b/examples/monolithic_build/main.c @@ -14,7 +14,6 @@ * * The parameter set is configured on the command line */ -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem #include #include "test_only_rng/notrandombytes.h" @@ -35,27 +34,27 @@ static int test_keys_mlkem(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) -#if MLK_CONFIG_API_PARAMETER_SET == 512 +#if MLK_CONFIG_PARAMETER_SET == 512 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}; -#elif MLK_CONFIG_API_PARAMETER_SET == 768 +#elif MLK_CONFIG_PARAMETER_SET == 768 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}; -#elif MLK_CONFIG_API_PARAMETER_SET == 1024 +#elif MLK_CONFIG_PARAMETER_SET == 1024 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_API_PARAMETER_SET == 1024 */ +#endif /* MLK_CONFIG_PARAMETER_SET == 1024 */ #endif /* !MLK_CONFIG_KEYGEN_PCT */ - uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]; - uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]; - uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)]; + uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)]; + uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)]; + uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_PARAMETER_SET)]; uint8_t key_a[MLKEM_BYTES]; uint8_t key_b[MLKEM_BYTES]; @@ -93,7 +92,7 @@ static int test_keys_mlkem(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-%d] OK\n", MLK_CONFIG_API_PARAMETER_SET); + printf("[MLKEM-%d] OK\n", MLK_CONFIG_PARAMETER_SET); return 0; } diff --git a/examples/monolithic_build/mlkem/src/config.h b/examples/monolithic_build/mlkem/src/config.h deleted file mode 120000 index 565d9cd744..0000000000 --- a/examples/monolithic_build/mlkem/src/config.h +++ /dev/null @@ -1 +0,0 @@ -../../../../mlkem/src/config.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem/mlkem_native.c b/examples/monolithic_build/mlkem_native/mlkem_native.c similarity index 100% rename from examples/monolithic_build/mlkem/mlkem_native.c rename to examples/monolithic_build/mlkem_native/mlkem_native.c diff --git a/examples/monolithic_build/mlkem_native/mlkem_native.h b/examples/monolithic_build/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/monolithic_build/config_768.h b/examples/monolithic_build/mlkem_native/mlkem_native_config.h similarity index 87% rename from examples/monolithic_build/config_768.h rename to examples/monolithic_build/mlkem_native/mlkem_native_config.h index 24115ca5b4..3a2a7fe762 100644 --- a/examples/monolithic_build/config_768.h +++ b/examples/monolithic_build/mlkem_native/mlkem_native_config.h @@ -25,11 +25,10 @@ */ /* - * Test configuration: Monolithic build config for ML-KEM-768 + * Test configuration: Monolithic build config * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_INTERNAL_API_QUALIFIER */ @@ -46,10 +45,18 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 768 +#ifndef MLK_CONFIG_PARAMETER_SET +#define MLK_CONFIG_PARAMETER_SET \ + 768 /* Change this for different security strengths */ +#endif /****************************************************************************** * Name: MLK_CONFIG_FILE @@ -75,17 +82,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX mlkem +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -105,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -126,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -297,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -323,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -378,7 +473,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -401,7 +496,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -421,21 +516,6 @@ *****************************************************************************/ #define MLK_CONFIG_INTERNAL_API_QUALIFIER static -/****************************************************************************** - * 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 * @@ -485,24 +565,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -532,7 +594,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -564,6 +626,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/monolithic_build/mlkem_native/src/cbmc.h b/examples/monolithic_build/mlkem_native/src/cbmc.h new file mode 120000 index 0000000000..ceb4b4328a --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/cbmc.h @@ -0,0 +1 @@ +../../../../mlkem/src/cbmc.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/common.h b/examples/monolithic_build/mlkem_native/src/common.h new file mode 120000 index 0000000000..b91b8da93c --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/common.h @@ -0,0 +1 @@ +../../../../mlkem/src/common.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/compress.c b/examples/monolithic_build/mlkem_native/src/compress.c new file mode 120000 index 0000000000..7a268bba40 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/compress.c @@ -0,0 +1 @@ +../../../../mlkem/src/compress.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/compress.h b/examples/monolithic_build/mlkem_native/src/compress.h new file mode 120000 index 0000000000..bbdf7a8d06 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/compress.h @@ -0,0 +1 @@ +../../../../mlkem/src/compress.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/debug.c b/examples/monolithic_build/mlkem_native/src/debug.c new file mode 120000 index 0000000000..92b15d4531 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/debug.c @@ -0,0 +1 @@ +../../../../mlkem/src/debug.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/debug.h b/examples/monolithic_build/mlkem_native/src/debug.h new file mode 120000 index 0000000000..3e25c792f4 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/debug.h @@ -0,0 +1 @@ +../../../../mlkem/src/debug.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/fips202.c b/examples/monolithic_build/mlkem_native/src/fips202/fips202.c new file mode 120000 index 0000000000..ac5576da90 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/fips202.c @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/fips202.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/fips202.h b/examples/monolithic_build/mlkem_native/src/fips202/fips202.h new file mode 120000 index 0000000000..d7e822989c --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/fips202.h @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/fips202.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.c b/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.c new file mode 120000 index 0000000000..08b2e9cb2b --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.c @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/fips202x4.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.h b/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.h new file mode 120000 index 0000000000..b3ddcab49b --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/fips202x4.h @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/fips202x4.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.c b/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.c new file mode 120000 index 0000000000..9db3768d2f --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.c @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/keccakf1600.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.h b/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.h new file mode 120000 index 0000000000..a481cc2a79 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/fips202/keccakf1600.h @@ -0,0 +1 @@ +../../../../../mlkem/src/fips202/keccakf1600.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/indcpa.c b/examples/monolithic_build/mlkem_native/src/indcpa.c new file mode 120000 index 0000000000..2a2fd88bae --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/indcpa.c @@ -0,0 +1 @@ +../../../../mlkem/src/indcpa.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/indcpa.h b/examples/monolithic_build/mlkem_native/src/indcpa.h new file mode 120000 index 0000000000..a32974db47 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/indcpa.h @@ -0,0 +1 @@ +../../../../mlkem/src/indcpa.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/kem.c b/examples/monolithic_build/mlkem_native/src/kem.c new file mode 120000 index 0000000000..89d895756e --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/kem.c @@ -0,0 +1 @@ +../../../../mlkem/src/kem.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/kem.h b/examples/monolithic_build/mlkem_native/src/kem.h new file mode 120000 index 0000000000..76983fddef --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/kem.h @@ -0,0 +1 @@ +../../../../mlkem/src/kem.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/params.h b/examples/monolithic_build/mlkem_native/src/params.h new file mode 120000 index 0000000000..28e1dccb35 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/params.h @@ -0,0 +1 @@ +../../../../mlkem/src/params.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/poly.c b/examples/monolithic_build/mlkem_native/src/poly.c new file mode 120000 index 0000000000..acdfae407e --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/poly.c @@ -0,0 +1 @@ +../../../../mlkem/src/poly.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/poly.h b/examples/monolithic_build/mlkem_native/src/poly.h new file mode 120000 index 0000000000..befaf0b277 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/poly.h @@ -0,0 +1 @@ +../../../../mlkem/src/poly.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/poly_k.c b/examples/monolithic_build/mlkem_native/src/poly_k.c new file mode 120000 index 0000000000..0ed1ffb5c6 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/poly_k.c @@ -0,0 +1 @@ +../../../../mlkem/src/poly_k.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/poly_k.h b/examples/monolithic_build/mlkem_native/src/poly_k.h new file mode 120000 index 0000000000..9af042866f --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/poly_k.h @@ -0,0 +1 @@ +../../../../mlkem/src/poly_k.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/randombytes.h b/examples/monolithic_build/mlkem_native/src/randombytes.h new file mode 120000 index 0000000000..bf94296ea7 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/randombytes.h @@ -0,0 +1 @@ +../../../../mlkem/src/randombytes.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/sampling.c b/examples/monolithic_build/mlkem_native/src/sampling.c new file mode 120000 index 0000000000..d913314bb1 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/sampling.c @@ -0,0 +1 @@ +../../../../mlkem/src/sampling.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/sampling.h b/examples/monolithic_build/mlkem_native/src/sampling.h new file mode 120000 index 0000000000..fe3dc77fb2 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/sampling.h @@ -0,0 +1 @@ +../../../../mlkem/src/sampling.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/symmetric.h b/examples/monolithic_build/mlkem_native/src/symmetric.h new file mode 120000 index 0000000000..a4f831f0a7 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/symmetric.h @@ -0,0 +1 @@ +../../../../mlkem/src/symmetric.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/sys.h b/examples/monolithic_build/mlkem_native/src/sys.h new file mode 120000 index 0000000000..91ac039c07 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/sys.h @@ -0,0 +1 @@ +../../../../mlkem/src/sys.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/verify.c b/examples/monolithic_build/mlkem_native/src/verify.c new file mode 120000 index 0000000000..fc6244bbcf --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/verify.c @@ -0,0 +1 @@ +../../../../mlkem/src/verify.c \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/verify.h b/examples/monolithic_build/mlkem_native/src/verify.h new file mode 120000 index 0000000000..a389b96c3e --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/verify.h @@ -0,0 +1 @@ +../../../../mlkem/src/verify.h \ No newline at end of file diff --git a/examples/monolithic_build/mlkem_native/src/zetas.inc b/examples/monolithic_build/mlkem_native/src/zetas.inc new file mode 120000 index 0000000000..2640464883 --- /dev/null +++ b/examples/monolithic_build/mlkem_native/src/zetas.inc @@ -0,0 +1 @@ +../../../../mlkem/src/zetas.inc \ No newline at end of file diff --git a/examples/monolithic_build_multilevel/Makefile b/examples/monolithic_build_multilevel/Makefile index 4f74d371c1..0fe35bcf9c 100644 --- a/examples/monolithic_build_multilevel/Makefile +++ b/examples/monolithic_build_multilevel/Makefile @@ -57,7 +57,7 @@ endif MLK_SOURCE=mlkem_native_all.c -INC=-Imlkem/ -I./ +INC=-Imlkem_native # Part B: # diff --git a/examples/monolithic_build_multilevel/README.md b/examples/monolithic_build_multilevel/README.md index b571b4a946..7c9fac1d1b 100644 --- a/examples/monolithic_build_multilevel/README.md +++ b/examples/monolithic_build_multilevel/README.md @@ -1,38 +1,55 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Multi-level mlkem-native in a single compilation unit +# Monolithic Multi-Level Build (C Backend) -This directory contains a minimal example for how to build multiple instances of mlkem-native in a single compilation -unit. Only the C-backend is exercised. +This directory contains a minimal example for building all three ML-KEM security levels in a single +compilation unit, with shared code deduplicated. -The auto-generated source file [mlkem_native.c](mlkem/mlkem_native.c) includes all mlkem-native C source -files. Moreover, it clears all `#define`s clauses set by mlkem-native at the end, and is hence amenable to multiple -inclusion in another compilation unit. +## Use Case -The manually written source file [mlkem_native_all.c](mlkem_native_all.c) includes -[mlkem_native.c](mlkem/mlkem_native.c) three times, each time using the fixed config -[multilevel_config.h](multilevel_config.h), but changing the security level (specified -by `MLK_CONFIG_PARAMETER_SET`) every time. -```C -#define MLK_CONFIG_FILE "multilevel_config.h" +Use this approach when: +- You need all ML-KEM security levels in one application +- You want the simplest possible multi-level integration (one `.c` file) +- You're using only C (no native backend) + +## Components + +An application using mlkem-native as a monolithic multi-level build needs: + +1. Source tree [mlkem_native/*](mlkem_native), including top-level compilation unit + [mlkem_native.c](mlkem_native/mlkem_native.c) (gathering all C sources) + and the mlkem-native API [mlkem_native.h](mlkem_native/mlkem_native.h). +2. Manually provided wrapper file [mlkem_native_all.c](mlkem_native_all.c), + including `mlkem_native.c` three times. +3. Manually provided header file [mlkem_native_all.h](mlkem_native_all.h), + including `mlkem_native.h` three times) +4. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +5. Your application source code + +## Configuration -/* Three instances of mlkem-native for all security levels */ +The configuration file [multilevel_config.h](mlkem_native/multilevel_config.h) sets: +- `MLK_CONFIG_MULTILEVEL_BUILD`: Enables multi-level mode +- `MLK_CONFIG_NAMESPACE_PREFIX=mlkem`: Base prefix +- `MLK_CONFIG_INTERNAL_API_QUALIFIER=static`: Makes internal functions static -/* Include level-independent code */ +The wrapper [mlkem_native_all.c](mlkem_native_all.c) includes `mlkem_native.c` three times: +```c +#define MLK_CONFIG_FILE "multilevel_config.h" + +/* Include level-independent code with first level */ #define MLK_CONFIG_MULTILEVEL_WITH_SHARED -/* Keep level-independent headers at the end of monobuild file */ #define MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS #define MLK_CONFIG_PARAMETER_SET 512 #include "mlkem_native.c" #undef MLK_CONFIG_PARAMETER_SET #undef MLK_CONFIG_MULTILEVEL_WITH_SHARED -/* Exclude level-independent code */ +/* Exclude level-independent code for subsequent levels */ #define MLK_CONFIG_MULTILEVEL_NO_SHARED #define MLK_CONFIG_PARAMETER_SET 768 #include "mlkem_native.c" #undef MLK_CONFIG_PARAMETER_SET -/* `#undef` all headers at the and of the monobuild file */ #undef MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS #define MLK_CONFIG_PARAMETER_SET 1024 @@ -40,48 +57,40 @@ by `MLK_CONFIG_PARAMETER_SET`) every time. #undef MLK_CONFIG_PARAMETER_SET ``` -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 -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. - -To make the monolithic multi-level build accessible from the application source [main.c](main.c), we provide -[mlkem_native_all.h](mlkem_native_all.h), which includes [mlkem_native.h](../../mlkem/mlkem_native.h) once per -configuration. Note that we don't refer to the configuration using `MLK_CONFIG_FILE`, but by setting -`MLK_CONFIG_API_XXX` explicitly. Otherwise, [mlkem_native.h](../../mlkem/mlkem_native.h) would include the confg, which -would lead to name-clashes upon multiple use. +The header [mlkem_native_all.h](mlkem_native_all.h) exposes all APIs: +```c +#define MLK_CONFIG_NO_SUPERCOP -```C -#define MLK_CONFIG_API_NO_SUPERCOP - -/* API for MLKEM-512 */ -#define MLK_CONFIG_API_PARAMETER_SET 512 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 +#define MLK_CONFIG_PARAMETER_SET 512 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H -/* API for MLKEM-768 */ -#define MLK_CONFIG_API_PARAMETER_SET 768 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 +#define MLK_CONFIG_PARAMETER_SET 768 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H -/* API for MLKEM-1024 */ -#define MLK_CONFIG_API_PARAMETER_SET 1024 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 +#define MLK_CONFIG_PARAMETER_SET 1024 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H ``` +## Notes + +- `MLK_CONFIG_MULTILEVEL_WITH_SHARED` must be set for exactly ONE level +- `MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS` prevents cleanup of shared headers between inclusions +- `MLK_CONFIG_NO_SUPERCOP` is required to avoid conflicting `CRYPTO_*` macro definitions + ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/monolithic_build_multilevel/mlkem b/examples/monolithic_build_multilevel/mlkem deleted file mode 120000 index 5f59b0a84f..0000000000 --- a/examples/monolithic_build_multilevel/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../mlkem \ No newline at end of file diff --git a/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.c b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.c new file mode 120000 index 0000000000..2afd79e7dc --- /dev/null +++ b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.c @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.c \ No newline at end of file diff --git a/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.h b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/monolithic_build_multilevel/multilevel_config.h b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h similarity index 88% rename from examples/monolithic_build_multilevel/multilevel_config.h rename to examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h index 0647d3b2ef..8a18f30b69 100644 --- a/examples/monolithic_build_multilevel/multilevel_config.h +++ b/examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h @@ -27,8 +27,9 @@ /* * Test configuration: Multilevel monolithic build config * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_MULTILEVEL_BUILD * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_INTERNAL_API_QUALIFIER */ @@ -45,6 +46,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -77,17 +83,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX mlkem +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_MULTILEVEL_BUILD + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -325,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -380,7 +474,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -403,7 +497,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -423,21 +517,6 @@ *****************************************************************************/ #define MLK_CONFIG_INTERNAL_API_QUALIFIER static -/****************************************************************************** - * 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 * @@ -487,24 +566,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -534,7 +595,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -566,6 +627,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/monolithic_build_multilevel/mlkem_native/src b/examples/monolithic_build_multilevel/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/monolithic_build_multilevel/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/monolithic_build_multilevel/mlkem_native_all.c b/examples/monolithic_build_multilevel/mlkem_native_all.c index 0120de24e0..4d2e4a1c0e 100644 --- a/examples/monolithic_build_multilevel/mlkem_native_all.c +++ b/examples/monolithic_build_multilevel/mlkem_native_all.c @@ -11,8 +11,6 @@ * with kem.h and mlkem_native_all.h above. */ #define MLK_CHECK_APIS -#define MLK_CONFIG_FILE "multilevel_config.h" - /* Three instances of mlkem-native for all security levels */ /* Include level-independent code */ diff --git a/examples/monolithic_build_multilevel/mlkem_native_all.h b/examples/monolithic_build_multilevel/mlkem_native_all.h index 70a59f1d36..fea0efc0c9 100644 --- a/examples/monolithic_build_multilevel/mlkem_native_all.h +++ b/examples/monolithic_build_multilevel/mlkem_native_all.h @@ -6,31 +6,24 @@ #if !defined(MLK_ALL_H) #define MLK_ALL_H -#define MLK_CONFIG_API_NO_SUPERCOP +#define MLK_CONFIG_NO_SUPERCOP /* API for MLKEM-512 */ -#define MLK_CONFIG_API_PARAMETER_SET 512 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem512 +#define MLK_CONFIG_PARAMETER_SET 512 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H /* API for MLKEM-768 */ -#define MLK_CONFIG_API_PARAMETER_SET 768 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem768 +#define MLK_CONFIG_PARAMETER_SET 768 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H /* API for MLKEM-1024 */ -#define MLK_CONFIG_API_PARAMETER_SET 1024 -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem1024 +#define MLK_CONFIG_PARAMETER_SET 1024 #include -#undef MLK_CONFIG_API_PARAMETER_SET -#undef MLK_CONFIG_API_NAMESPACE_PREFIX -#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H #endif /* !MLK_ALL_H */ diff --git a/examples/monolithic_build_multilevel_native/Makefile b/examples/monolithic_build_multilevel_native/Makefile index e30e2ef763..6b2ce3f643 100644 --- a/examples/monolithic_build_multilevel_native/Makefile +++ b/examples/monolithic_build_multilevel_native/Makefile @@ -55,9 +55,9 @@ endif # # Here, the monolithic C file for mlkem-native is directly included in main.c, # However, we still need to incldue the monolithic assembly file. -MLK_SOURCE_ASM = mlkem/mlkem_native.S +MLK_SOURCE_ASM = mlkem_native/mlkem_native.S -INC=-Imlkem/ -Imlkem/src -I./ +INC=-Imlkem_native/ -I./ # Part B: # @@ -83,8 +83,7 @@ BIN=test_binary # Configuration adjustments # -ASMFLAGS = -DMLK_CONFIG_FILE=\"multilevel_config.h\" -ASMFLAGS += -DMLK_CONFIG_MULTILEVEL_WITH_SHARED +ASMFLAGS = -DMLK_CONFIG_MULTILEVEL_WITH_SHARED BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN) diff --git a/examples/monolithic_build_multilevel_native/README.md b/examples/monolithic_build_multilevel_native/README.md index 737e30ef8c..fbc44b59ce 100644 --- a/examples/monolithic_build_multilevel_native/README.md +++ b/examples/monolithic_build_multilevel_native/README.md @@ -1,38 +1,53 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Multi-level mlkem-native in a single compilation unit, with native code +# Monolithic Multi-Level Build (Native Backend) -This directory contains a minimal example for how to build multiple instances of mlkem-native in a single compilation -unit, while additionally linking assembly sources from native code. +This directory contains a minimal example for building all three ML-KEM security levels in a single +compilation unit with native assembly backends, with shared code deduplicated. -The auto-generated source file [mlkem_native.c](mlkem/mlkem_native.c) includes all mlkem-native C source -files. Moreover, it clears all `#define`s clauses set by mlkem-native at the end, and is hence amenable to multiple -inclusion in another compilation unit. +## Use Case -The manually written source file [mlkem_native_all.c](mlkem_native_all.c) includes -[mlkem_native.c](mlkem/mlkem_native.c) three times, each time using the fixed config -[multilevel_config.h](multilevel_config.h), but changing the security level (specified -by `MLK_CONFIG_PARAMETER_SET`) every time. For each inclusion, it sets `MLK_CONFIG_FILE` -appropriately first, and then includes the monobuild: -```C -/* Three instances of mlkem-native for all security levels */ +Use this approach when: +- You need all ML-KEM security levels in one application +- You want optimal performance via native assembly +- You want the simplest possible multi-level native integration +## Components + +1. Source tree [mlkem_native/*](mlkem_native), including top-level compilation unit + [mlkem_native.c](mlkem_native/mlkem_native.c) (gathering all C sources), + [mlkem_native.S](mlkem_native/mlkem_native.S) (gathering all assembly sources), + and the mlkem-native API [mlkem_native.h](mlkem_native/mlkem_native.h). +2. Manually provided wrapper file [mlkem_native_all.c](mlkem_native_all.c), + including `mlkem_native.c` three times (in this example, we don't use a + wrapper header since we directly include `mlkem_native_all.c` into `main.c`). +3. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +4. Your application source code + +## Configuration + +The configuration file [multilevel_config.h](multilevel_config.h) sets: +- `MLK_CONFIG_MULTILEVEL_BUILD`: Enables multi-level mode +- `MLK_CONFIG_NAMESPACE_PREFIX=mlkem`: Base prefix +- `MLK_CONFIG_USE_NATIVE_BACKEND_ARITH`: Enables native arithmetic backend +- `MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202`: Enables native FIPS-202 backend + +The wrapper [mlkem_native_all.c](mlkem_native_all.c) includes `mlkem_native.c` three times: +```c #define MLK_CONFIG_FILE "multilevel_config.h" -/* Include level-independent code */ +/* Include level-independent code with first level */ #define MLK_CONFIG_MULTILEVEL_WITH_SHARED 1 -/* Keep level-independent headers at the end of monobuild file */ #define MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS #define MLK_CONFIG_PARAMETER_SET 512 #include "mlkem_native.c" #undef MLK_CONFIG_MULTILEVEL_WITH_SHARED #undef MLK_CONFIG_PARAMETER_SET -/* Exclude level-independent code */ +/* Exclude level-independent code for subsequent levels */ #define MLK_CONFIG_MULTILEVEL_NO_SHARED #define MLK_CONFIG_PARAMETER_SET 768 #include "mlkem_native.c" -/* `#undef` all headers at the and of the monobuild file */ #undef MLK_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS #undef MLK_CONFIG_PARAMETER_SET @@ -41,25 +56,29 @@ appropriately first, and then includes the monobuild: #undef MLK_CONFIG_PARAMETER_SET ``` -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 -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. - -Since we embed [mlkem_native_all.c](mlkem_native_all.c) directly into the application source [main.c](main.c), we don't -need a header for function declarations. However, we still import [mlkem_native.h](../../mlkem/mlkem_native.h) once -with `MLK_CONFIG_API_CONSTANTS_ONLY`, for definitions of the sizes of the key material. Excerpt from [main.c](main.c): - +The application [main.c](main.c) embeds the wrapper and imports constants: ```c #include "mlkem_native_all.c" -#define MLK_CONFIG_API_CONSTANTS_ONLY +#define MLK_CONFIG_CONSTANTS_ONLY #include ``` +## Notes + +- Both `mlkem_native_all.c` and `mlkem_native.S` must be compiled and linked +- `MLK_CONFIG_MULTILEVEL_WITH_SHARED` must be set for exactly ONE level +- `MLK_CONFIG_CONSTANTS_ONLY` imports size constants without function declarations +- Native backends are auto-selected based on target architecture + ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/monolithic_build_multilevel_native/main.c b/examples/monolithic_build_multilevel_native/main.c index 9f4c280087..d71a3fa32e 100644 --- a/examples/monolithic_build_multilevel_native/main.c +++ b/examples/monolithic_build_multilevel_native/main.c @@ -9,7 +9,7 @@ #include "mlkem_native_all.c" -#define MLK_CONFIG_API_CONSTANTS_ONLY +#define MLK_CONFIG_CONSTANTS_ONLY #include #include "test_only_rng/notrandombytes.h" diff --git a/examples/monolithic_build_multilevel_native/mlkem b/examples/monolithic_build_multilevel_native/mlkem deleted file mode 120000 index 5f59b0a84f..0000000000 --- a/examples/monolithic_build_multilevel_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../mlkem \ No newline at end of file diff --git a/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.S b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.S new file mode 120000 index 0000000000..9bb5ab1011 --- /dev/null +++ b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.S @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.S \ No newline at end of file diff --git a/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.c b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.c new file mode 120000 index 0000000000..2afd79e7dc --- /dev/null +++ b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.c @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.c \ No newline at end of file diff --git a/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.h b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/monolithic_build_multilevel_native/multilevel_config.h b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h similarity index 88% rename from examples/monolithic_build_multilevel_native/multilevel_config.h rename to examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h index f56dfa339f..82e4722d41 100644 --- a/examples/monolithic_build_multilevel_native/multilevel_config.h +++ b/examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h @@ -27,8 +27,9 @@ /* * Test configuration: Multilevel monolithic build config with native backends * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_MULTILEVEL_BUILD * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_USE_NATIVE_BACKEND_ARITH * - MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 @@ -49,6 +50,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -81,17 +87,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX mlkem +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_MULTILEVEL_BUILD + +/****************************************************************************** + * 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 static + +/****************************************************************************** + * Name: MLK_CONFIG_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -111,6 +203,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -132,6 +225,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -331,7 +425,7 @@ #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include -#include "sys.h" +#include "src/sys.h" #include "test_only_rng/notrandombytes.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { @@ -387,7 +481,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -410,7 +504,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -430,21 +524,6 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ #define MLK_CONFIG_INTERNAL_API_QUALIFIER static -/****************************************************************************** - * 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 static - /****************************************************************************** * Name: MLK_CONFIG_CT_TESTING_ENABLED * @@ -494,24 +573,6 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -541,7 +602,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -573,6 +634,8 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/monolithic_build_multilevel_native/mlkem_native/src b/examples/monolithic_build_multilevel_native/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/monolithic_build_multilevel_native/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/monolithic_build_multilevel_native/mlkem_native_all.c b/examples/monolithic_build_multilevel_native/mlkem_native_all.c index 2b66fddb1a..83121b430f 100644 --- a/examples/monolithic_build_multilevel_native/mlkem_native_all.c +++ b/examples/monolithic_build_multilevel_native/mlkem_native_all.c @@ -5,8 +5,6 @@ /* Three instances of mlkem-native for all security levels */ -#define MLK_CONFIG_FILE "multilevel_config.h" - /* Include level-independent code */ #define MLK_CONFIG_MULTILEVEL_WITH_SHARED 1 /* Keep level-independent headers at the end of monobuild file */ diff --git a/examples/monolithic_build_native/Makefile b/examples/monolithic_build_native/Makefile index 16d604e420..6435ed8e0f 100644 --- a/examples/monolithic_build_native/Makefile +++ b/examples/monolithic_build_native/Makefile @@ -57,9 +57,9 @@ Q ?= @ # # Here, we use just a single C and assembly unit. -MLK_SOURCE=mlkem/mlkem_native.c mlkem/mlkem_native.S +MLK_SOURCE=mlkem_native/mlkem_native.c mlkem_native/mlkem_native.S -INC=-Imlkem/ -I./ +INC=-Imlkem_native/ # Part B: # @@ -97,41 +97,41 @@ LIB1024_FULL=$(BUILD_DIR)/$(LIB1024) $(LIB512_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_512.h\"" $(INC) mlkem/mlkem_native.c -o $(BUILD_DIR)/mlkem_native512.c.o - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_512.h\"" $(INC) mlkem/mlkem_native.S -o $(BUILD_DIR)/mlkem_native512.S.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=512 $(INC) mlkem_native/mlkem_native.c -o $(BUILD_DIR)/mlkem_native512.c.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=512 $(INC) mlkem_native/mlkem_native.S -o $(BUILD_DIR)/mlkem_native512.S.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native512.c.o $(BUILD_DIR)/mlkem_native512.S.o $(Q)strip -S $@ $(LIB768_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_768.h\"" $(INC) mlkem/mlkem_native.c -o $(BUILD_DIR)/mlkem_native768.c.o - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_768.h\"" $(INC) mlkem/mlkem_native.S -o $(BUILD_DIR)/mlkem_native768.S.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=768 $(INC) mlkem_native/mlkem_native.c -o $(BUILD_DIR)/mlkem_native768.c.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=768 $(INC) mlkem_native/mlkem_native.S -o $(BUILD_DIR)/mlkem_native768.S.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native768.c.o $(BUILD_DIR)/mlkem_native768.S.o $(Q)strip -S $@ $(LIB1024_FULL): $(MLK_SOURCE) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_1024.h\"" $(INC) mlkem/mlkem_native.c -o $(BUILD_DIR)/mlkem_native1024.c.o - $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_FILE="\"config_1024.h\"" $(INC) mlkem/mlkem_native.S -o $(BUILD_DIR)/mlkem_native1024.S.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) mlkem_native/mlkem_native.c -o $(BUILD_DIR)/mlkem_native1024.c.o + $(Q)$(CC) -c $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) mlkem_native/mlkem_native.S -o $(BUILD_DIR)/mlkem_native1024.S.o $(Q)$(AR) rcs $@ $(BUILD_DIR)/mlkem_native1024.c.o $(BUILD_DIR)/mlkem_native1024.S.o $(Q)strip -S $@ $(BIN512_FULL): $(APP_SOURCE) $(LIB512_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=512 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=512 $(INC) $^ -o $@ $(BIN768_FULL): $(APP_SOURCE) $(LIB768_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=768 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=768 $(INC) $^ -o $@ $(BIN1024_FULL): $(APP_SOURCE) $(LIB1024_FULL) $(Q)echo "$@" $(Q)[ -d $(@) ] || mkdir -p $(@D) - $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_API_PARAMETER_SET=1024 $(INC) $^ -o $@ + $(Q)$(CC) $(CFLAGS) -DMLK_CONFIG_PARAMETER_SET=1024 $(INC) $^ -o $@ all: build diff --git a/examples/monolithic_build_native/README.md b/examples/monolithic_build_native/README.md index 4aa0747e84..acde0bf53f 100644 --- a/examples/monolithic_build_native/README.md +++ b/examples/monolithic_build_native/README.md @@ -1,17 +1,47 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Single-level mlkem-native in a single compilation unit, with native code +# Monolithic Build (Native Backend) -This directory contains a minimal example for how to build a single instance of mlkem-native in a single compilation -unit, including the native backends. +This directory contains a minimal example for building mlkem-native as a single compilation unit +with native assembly backends, using the auto-generated `mlkem_native.c` and `mlkem_native.S` files. -The auto-generated source file [mlkem_native.c](mlkem/mlkem_native.c) includes all mlkem-native C source -files. Similarly, [mlkem_native.S](mlkem/mlkem_native.S) includes all assembly files. -It exposes the API [mlkem/mlkem_native.h](mlkem/mlkem_native.h). +## Use Case + +Use this approach when: +- You need only one ML-KEM parameter set (512, 768, or 1024) +- You want simple build integration with optimal performance + +## Components + +1. Source tree [mlkem_native/*](mlkem_native), including top-level compilation unit + [mlkem_native.c](mlkem_native/mlkem_native.c) (gathering all C sources), + [mlkem_native.S](mlkem_native/mlkem_native.S) (gathering all assembly sources), + and the mlkem-native API [mlkem_native.h](mlkem_native/mlkem_native.h). +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Your application source code + +## Configuration + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_PARAMETER_SET`: Security level (default 768) +- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mlkem`) +- `MLK_CONFIG_USE_NATIVE_BACKEND_ARITH`: Enables native arithmetic backend +- `MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202`: Enables native FIPS-202 backend + +## Notes + +- Both `mlkem_native.c` and `mlkem_native.S` must be compiled and linked +- Native backends are auto-selected based on target architecture +- On unsupported platforms, the C backend is used automatically ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build the example +make run # Run the example +``` + +## Warning -**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation -outside of testing. +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/monolithic_build_native/config_1024.h b/examples/monolithic_build_native/config_1024.h deleted file mode 100644 index a95e6e2d8b..0000000000 --- a/examples/monolithic_build_native/config_1024.h +++ /dev/null @@ -1,588 +0,0 @@ -/* - * 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 - * - * - [FIPS203] - * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard - * National Institute of Standards and Technology - * https://csrc.nist.gov/pubs/fips/203/final - */ - -/* - * WARNING: This file is auto-generated from scripts/autogen - * in the mlkem-native repository. - * Do not modify it directly. - */ - -/* - * Test configuration: Monolithic build config for ML-KEM-1024 (native backends - * disabled) - * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET - * - MLK_CONFIG_NAMESPACE_PREFIX - * - MLK_CONFIG_INTERNAL_API_QUALIFIER - */ - - -#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. - * - *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 1024 - -/****************************************************************************** - * Name: MLK_CONFIG_FILE - * - * Description: If defined, this is a header that will be included instead - * of the 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. - * - *****************************************************************************/ -/* No need to set this -- we _are_ already in a custom config */ -/* #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. - * - *****************************************************************************/ -#define MLK_CONFIG_NAMESPACE_PREFIX mlkem - -/****************************************************************************** - * 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 @[FIPS203, 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_CAPABILITY_FUNC - * - * Description: mlkem-native backends may rely on specific hardware features. - * Those backends will only be included in an mlkem-native build - * if support for the respective features is enabled at - * compile-time. However, when building for a heteroneous set - * of CPUs to run the resulting binary/library on, feature - * detection at _runtime_ is needed to decided whether a backend - * can be used or not. - * - * Set this option and define `mlk_sys_check_capability` if you - * want to use a custom method to dispatch between implementations. - * - * If this option is not set, mlkem-native uses compile-time - * feature detection only to decide which backend to use. - * - * If you compile mlkem-native on a system with different - * capabilities than the system that the resulting binary/library - * will be run on, you must use this option. - * - *****************************************************************************/ -/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC - static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) - __contract__( - ensures(return_value == 0 || return_value == 1) - ) - { - ... your implementation ... - } -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 static - -/****************************************************************************** - * 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_NO_ASM_VALUE_BARRIER - * - * Description: If this option is set, mlkem-native will be built without - * use of native code or inline assembly for value barriers. - * - * By default, inline assembly (if available) is used to implement - * value barriers. - * Without inline assembly, mlkem-native will use a global volatile - * 'opt blocker' instead; see verify.h. - * - *****************************************************************************/ -/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ - -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - -/****************************************************************************** - * 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 -*/ - -/****************************************************************************** - * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY - * - * Description: Set this to use a FIPS202 implementation with global state - * that supports only one active Keccak computation at a time - * (e.g. some hardware accelerators). - * - * If this option is set, batched Keccak operations are - * disabled for rejection sampling during matrix generation. - * Instead, matrix entries will be generated one at a time. - * - * This allows offloading Keccak computations to a hardware - * accelerator that holds only a single Keccak state locally, - * rather than requiring support for batched (4x) Keccak states. - * - * NOTE: Depending on the target CPU, disabling batched Keccak - * may reduce performance when using software FIPS202 - * implementations. Only enable this when you have to. - * - *****************************************************************************/ -/* #define MLK_CONFIG_SERIAL_FIPS202_ONLY */ - -/************************* 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/monolithic_build_native/config_512.h b/examples/monolithic_build_native/config_512.h deleted file mode 100644 index a98f43cac0..0000000000 --- a/examples/monolithic_build_native/config_512.h +++ /dev/null @@ -1,588 +0,0 @@ -/* - * 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 - * - * - [FIPS203] - * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard - * National Institute of Standards and Technology - * https://csrc.nist.gov/pubs/fips/203/final - */ - -/* - * WARNING: This file is auto-generated from scripts/autogen - * in the mlkem-native repository. - * Do not modify it directly. - */ - -/* - * Test configuration: Monolithic build config for ML-KEM-512 (native backends - * disabled) - * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET - * - MLK_CONFIG_NAMESPACE_PREFIX - * - MLK_CONFIG_INTERNAL_API_QUALIFIER - */ - - -#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. - * - *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 512 - -/****************************************************************************** - * Name: MLK_CONFIG_FILE - * - * Description: If defined, this is a header that will be included instead - * of the 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. - * - *****************************************************************************/ -/* No need to set this -- we _are_ already in a custom config */ -/* #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. - * - *****************************************************************************/ -#define MLK_CONFIG_NAMESPACE_PREFIX mlkem - -/****************************************************************************** - * 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 @[FIPS203, 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_CAPABILITY_FUNC - * - * Description: mlkem-native backends may rely on specific hardware features. - * Those backends will only be included in an mlkem-native build - * if support for the respective features is enabled at - * compile-time. However, when building for a heteroneous set - * of CPUs to run the resulting binary/library on, feature - * detection at _runtime_ is needed to decided whether a backend - * can be used or not. - * - * Set this option and define `mlk_sys_check_capability` if you - * want to use a custom method to dispatch between implementations. - * - * If this option is not set, mlkem-native uses compile-time - * feature detection only to decide which backend to use. - * - * If you compile mlkem-native on a system with different - * capabilities than the system that the resulting binary/library - * will be run on, you must use this option. - * - *****************************************************************************/ -/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC - static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) - __contract__( - ensures(return_value == 0 || return_value == 1) - ) - { - ... your implementation ... - } -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 static - -/****************************************************************************** - * 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_NO_ASM_VALUE_BARRIER - * - * Description: If this option is set, mlkem-native will be built without - * use of native code or inline assembly for value barriers. - * - * By default, inline assembly (if available) is used to implement - * value barriers. - * Without inline assembly, mlkem-native will use a global volatile - * 'opt blocker' instead; see verify.h. - * - *****************************************************************************/ -/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ - -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - -/****************************************************************************** - * 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 -*/ - -/****************************************************************************** - * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY - * - * Description: Set this to use a FIPS202 implementation with global state - * that supports only one active Keccak computation at a time - * (e.g. some hardware accelerators). - * - * If this option is set, batched Keccak operations are - * disabled for rejection sampling during matrix generation. - * Instead, matrix entries will be generated one at a time. - * - * This allows offloading Keccak computations to a hardware - * accelerator that holds only a single Keccak state locally, - * rather than requiring support for batched (4x) Keccak states. - * - * NOTE: Depending on the target CPU, disabling batched Keccak - * may reduce performance when using software FIPS202 - * implementations. Only enable this when you have to. - * - *****************************************************************************/ -/* #define MLK_CONFIG_SERIAL_FIPS202_ONLY */ - -/************************* 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/monolithic_build_native/config_768.h b/examples/monolithic_build_native/config_768.h deleted file mode 100644 index 2ea6a199a9..0000000000 --- a/examples/monolithic_build_native/config_768.h +++ /dev/null @@ -1,588 +0,0 @@ -/* - * 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 - * - * - [FIPS203] - * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard - * National Institute of Standards and Technology - * https://csrc.nist.gov/pubs/fips/203/final - */ - -/* - * WARNING: This file is auto-generated from scripts/autogen - * in the mlkem-native repository. - * Do not modify it directly. - */ - -/* - * Test configuration: Monolithic build config for ML-KEM-768 (native backends - * disabled) - * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET - * - MLK_CONFIG_NAMESPACE_PREFIX - * - MLK_CONFIG_INTERNAL_API_QUALIFIER - */ - - -#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. - * - *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 768 - -/****************************************************************************** - * Name: MLK_CONFIG_FILE - * - * Description: If defined, this is a header that will be included instead - * of the 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. - * - *****************************************************************************/ -/* No need to set this -- we _are_ already in a custom config */ -/* #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. - * - *****************************************************************************/ -#define MLK_CONFIG_NAMESPACE_PREFIX mlkem - -/****************************************************************************** - * 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 @[FIPS203, 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_CAPABILITY_FUNC - * - * Description: mlkem-native backends may rely on specific hardware features. - * Those backends will only be included in an mlkem-native build - * if support for the respective features is enabled at - * compile-time. However, when building for a heteroneous set - * of CPUs to run the resulting binary/library on, feature - * detection at _runtime_ is needed to decided whether a backend - * can be used or not. - * - * Set this option and define `mlk_sys_check_capability` if you - * want to use a custom method to dispatch between implementations. - * - * If this option is not set, mlkem-native uses compile-time - * feature detection only to decide which backend to use. - * - * If you compile mlkem-native on a system with different - * capabilities than the system that the resulting binary/library - * will be run on, you must use this option. - * - *****************************************************************************/ -/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC - static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) - __contract__( - ensures(return_value == 0 || return_value == 1) - ) - { - ... your implementation ... - } -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 "sys.h" - static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) - { - ... your implementation ... - } - #endif -*/ - -/****************************************************************************** - * 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 static - -/****************************************************************************** - * 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_NO_ASM_VALUE_BARRIER - * - * Description: If this option is set, mlkem-native will be built without - * use of native code or inline assembly for value barriers. - * - * By default, inline assembly (if available) is used to implement - * value barriers. - * Without inline assembly, mlkem-native will use a global volatile - * 'opt blocker' instead; see verify.h. - * - *****************************************************************************/ -/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ - -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - -/****************************************************************************** - * 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 -*/ - -/****************************************************************************** - * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY - * - * Description: Set this to use a FIPS202 implementation with global state - * that supports only one active Keccak computation at a time - * (e.g. some hardware accelerators). - * - * If this option is set, batched Keccak operations are - * disabled for rejection sampling during matrix generation. - * Instead, matrix entries will be generated one at a time. - * - * This allows offloading Keccak computations to a hardware - * accelerator that holds only a single Keccak state locally, - * rather than requiring support for batched (4x) Keccak states. - * - * NOTE: Depending on the target CPU, disabling batched Keccak - * may reduce performance when using software FIPS202 - * implementations. Only enable this when you have to. - * - *****************************************************************************/ -/* #define MLK_CONFIG_SERIAL_FIPS202_ONLY */ - -/************************* 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/monolithic_build_native/main.c b/examples/monolithic_build_native/main.c index cc52623c96..527aa4ccab 100644 --- a/examples/monolithic_build_native/main.c +++ b/examples/monolithic_build_native/main.c @@ -14,7 +14,7 @@ * * The parameter set is configured on the command line */ -#define MLK_CONFIG_API_NAMESPACE_PREFIX mlkem +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem #include #include "test_only_rng/notrandombytes.h" @@ -35,27 +35,27 @@ static int test_keys_mlkem(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) -#if MLK_CONFIG_API_PARAMETER_SET == 512 +#if MLK_CONFIG_PARAMETER_SET == 512 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}; -#elif MLK_CONFIG_API_PARAMETER_SET == 768 +#elif MLK_CONFIG_PARAMETER_SET == 768 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}; -#elif MLK_CONFIG_API_PARAMETER_SET == 1024 +#elif MLK_CONFIG_PARAMETER_SET == 1024 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_API_PARAMETER_SET == 1024 */ +#endif /* MLK_CONFIG_PARAMETER_SET == 1024 */ #endif /* !MLK_CONFIG_KEYGEN_PCT */ - uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]; - uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]; - uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)]; + uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_PARAMETER_SET)]; + uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET)]; + uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_PARAMETER_SET)]; uint8_t key_a[MLKEM_BYTES]; uint8_t key_b[MLKEM_BYTES]; @@ -93,7 +93,7 @@ static int test_keys_mlkem(void) "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); #endif - printf("[MLKEM-%d] OK\n", MLK_CONFIG_API_PARAMETER_SET); + printf("[MLKEM-%d] OK\n", MLK_CONFIG_PARAMETER_SET); return 0; } diff --git a/examples/monolithic_build_native/mlkem b/examples/monolithic_build_native/mlkem deleted file mode 120000 index 5f59b0a84f..0000000000 --- a/examples/monolithic_build_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../mlkem \ No newline at end of file diff --git a/examples/monolithic_build_native/mlkem_native/mlkem_native.S b/examples/monolithic_build_native/mlkem_native/mlkem_native.S new file mode 120000 index 0000000000..9bb5ab1011 --- /dev/null +++ b/examples/monolithic_build_native/mlkem_native/mlkem_native.S @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.S \ No newline at end of file diff --git a/examples/monolithic_build_native/mlkem_native/mlkem_native.c b/examples/monolithic_build_native/mlkem_native/mlkem_native.c new file mode 120000 index 0000000000..2afd79e7dc --- /dev/null +++ b/examples/monolithic_build_native/mlkem_native/mlkem_native.c @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.c \ No newline at end of file diff --git a/examples/monolithic_build_native/mlkem_native/mlkem_native.h b/examples/monolithic_build_native/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/monolithic_build_native/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/monolithic_build/config_1024.h b/examples/monolithic_build_native/mlkem_native/mlkem_native_config.h similarity index 87% rename from examples/monolithic_build/config_1024.h rename to examples/monolithic_build_native/mlkem_native/mlkem_native_config.h index 0c6b62efef..b8699a6d66 100644 --- a/examples/monolithic_build/config_1024.h +++ b/examples/monolithic_build_native/mlkem_native/mlkem_native_config.h @@ -25,11 +25,10 @@ */ /* - * Test configuration: Monolithic build config for ML-KEM-1024 + * Test configuration: Monolithic build config (native backends disabled) * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_NAMESPACE_PREFIX * - MLK_CONFIG_INTERNAL_API_QUALIFIER */ @@ -46,10 +45,18 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 1024 +#ifndef MLK_CONFIG_PARAMETER_SET +#define MLK_CONFIG_PARAMETER_SET \ + 768 /* Change this for different security strengths */ +#endif /****************************************************************************** * Name: MLK_CONFIG_FILE @@ -75,17 +82,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX mlkem +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -105,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -126,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -297,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -323,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -378,7 +473,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -401,7 +496,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -421,21 +516,6 @@ *****************************************************************************/ #define MLK_CONFIG_INTERNAL_API_QUALIFIER static -/****************************************************************************** - * 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 * @@ -485,24 +565,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -532,7 +594,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -564,6 +626,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/monolithic_build_native/mlkem_native/src b/examples/monolithic_build_native/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/monolithic_build_native/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/multilevel_build/Makefile b/examples/multilevel_build/Makefile index 2f231942b9..c44775ca90 100644 --- a/examples/multilevel_build/Makefile +++ b/examples/multilevel_build/Makefile @@ -26,7 +26,7 @@ CFLAGS := \ -Wno-unused-command-line-argument \ -O3 \ -fomit-frame-pointer \ - -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem \ + -I mlkem_native \ -std=c99 \ -pedantic \ -MMD \ @@ -55,10 +55,10 @@ endif # Alternatively, you can compile the 'monobuild' source file mlkem_native.c. # See examples/monolithic_build for that. MLK_SOURCE_ALL := $(wildcard \ - mlkem_native/mlkem/src/*.c \ - mlkem_native/mlkem/src/**/*.c \ - mlkem_native/mlkem/src/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/*.c) + mlkem_native/src/*.c \ + mlkem_native/src/**/*.c \ + mlkem_native/src/**/**/*.c \ + mlkem_native/src/**/**/**/*.c) MLK_SOURCE:=$(foreach S,$(MLK_SOURCE_ALL),\ $(if $(findstring /native/,$S),,$S)) @@ -73,7 +73,7 @@ MLKEM1024_OBJS=$(patsubst %,$(MLKEM1024_DIR)/%.o,$(MLK_SOURCE)) $(MLKEM512_OBJS): $(MLKEM512_DIR)/%.c.o: %.c $(Q)[ -d $(@D) ] || mkdir -p $(@D) - $(Q)$(CC) -DMLK_CONFIG_MULTILEVEL_WITH_SHARED -DMLK_CONFIG_PARAMETER_SET=512 $(CFLAGS) -c $^ -o $@ + $(Q)$(CC) -DMLK_CONFIG_MULTILEVEL_WITH_SHARED -DMLK_CONFIG_PARAMETER_SET=512 $(CFLAGS) -c $^ -o $@ $(MLKEM768_OBJS): $(MLKEM768_DIR)/%.c.o: %.c $(Q)[ -d $(@D) ] || mkdir -p $(@D) diff --git a/examples/multilevel_build/README.md b/examples/multilevel_build/README.md index 25fb3d1c14..6a21a26b94 100644 --- a/examples/multilevel_build/README.md +++ b/examples/multilevel_build/README.md @@ -1,17 +1,50 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Multi-level build +# Multi-Level Build (C Backend) -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 -of mlkem-native is used. +This directory contains a minimal example for building mlkem-native with support for all three security levels +(ML-KEM-512, ML-KEM-768, ML-KEM-1024), with level-independent code shared to reduce binary size. -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 MLKEM-768 and MLKEM-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. +## Use Case + +Use this approach when: +- You need multiple ML-KEM security levels in the same application +- You want to minimize code duplication across levels +- You want to build the mlkem-native C files separately, not as a single compilation unit. +- You're only using C (no native backends) + +## Components + +1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202) +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Your application source code + +## Configuration + +The library is built 3 times into separate directories (`build/mlkem512`, `build/mlkem768`, `build/mlkem1024`). + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_MULTILEVEL_BUILD`: Enables multi-level build mode +- `MLK_CONFIG_NAMESPACE_PREFIX=mlkem`: Base prefix; level suffix added automatically + +Build-time flags passed via CFLAGS: +- `MLK_CONFIG_PARAMETER_SET=512/768/1024`: Selects the security level +- `MLK_CONFIG_MULTILEVEL_WITH_SHARED`: Set for ONE build (e.g., 512) to include shared code +- `MLK_CONFIG_MULTILEVEL_NO_SHARED`: Set for OTHER builds to exclude shared code + +The resulting API functions are namespaced as: +- `mlkem512_keypair()`, `mlkem512_enc()`, `mlkem512_dec()` +- `mlkem768_keypair()`, `mlkem768_enc()`, `mlkem768_dec()` +- `mlkem1024_keypair()`, `mlkem1024_enc()`, `mlkem1024_dec()` ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build all three security levels +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/multilevel_build/mlkem_native/mlkem b/examples/multilevel_build/mlkem_native/mlkem deleted file mode 120000 index f4ec7bdb2d..0000000000 --- a/examples/multilevel_build/mlkem_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../../mlkem \ No newline at end of file diff --git a/examples/multilevel_build/mlkem_native/mlkem_native.c b/examples/multilevel_build/mlkem_native/mlkem_native.c new file mode 120000 index 0000000000..2afd79e7dc --- /dev/null +++ b/examples/multilevel_build/mlkem_native/mlkem_native.c @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.c \ No newline at end of file diff --git a/examples/multilevel_build/mlkem_native/mlkem_native.h b/examples/multilevel_build/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/multilevel_build/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/monolithic_build/config_512.h b/examples/multilevel_build/mlkem_native/mlkem_native_config.h similarity index 87% rename from examples/monolithic_build/config_512.h rename to examples/multilevel_build/mlkem_native/mlkem_native_config.h index 66a688cab4..374b803229 100644 --- a/examples/monolithic_build/config_512.h +++ b/examples/multilevel_build/mlkem_native/mlkem_native_config.h @@ -25,13 +25,12 @@ */ /* - * Test configuration: Monolithic build config for ML-KEM-512 + * Test configuration: Multilevel build config * - * This configuration differs from the default mlkem/src/config.h in the - * following places: - * - MLK_CONFIG_PARAMETER_SET + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_MULTILEVEL_BUILD * - MLK_CONFIG_NAMESPACE_PREFIX - * - MLK_CONFIG_INTERNAL_API_QUALIFIER */ @@ -46,10 +45,18 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ -#define MLK_CONFIG_PARAMETER_SET 512 +#ifndef MLK_CONFIG_PARAMETER_SET +#define MLK_CONFIG_PARAMETER_SET \ + 768 /* Change this for different security strengths */ +#endif /****************************************************************************** * Name: MLK_CONFIG_FILE @@ -75,17 +82,103 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * *****************************************************************************/ #define MLK_CONFIG_NAMESPACE_PREFIX mlkem +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_MULTILEVEL_BUILD + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -105,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -126,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -297,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -323,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -378,7 +473,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -401,7 +496,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -419,22 +514,7 @@ * in which case this option can be set to `static`. * *****************************************************************************/ -#define MLK_CONFIG_INTERNAL_API_QUALIFIER static - -/****************************************************************************** - * 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 */ +/* #define MLK_CONFIG_INTERNAL_API_QUALIFIER */ /****************************************************************************** * Name: MLK_CONFIG_CT_TESTING_ENABLED @@ -485,24 +565,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -532,7 +594,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -564,6 +626,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/examples/multilevel_build/mlkem_native/src b/examples/multilevel_build/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/multilevel_build/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/multilevel_build/mlkem_native_all.h b/examples/multilevel_build/mlkem_native_all.h index c7915fd454..ba63dd915e 100644 --- a/examples/multilevel_build/mlkem_native_all.h +++ b/examples/multilevel_build/mlkem_native_all.h @@ -7,27 +7,21 @@ #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 +#define MLK_CONFIG_PARAMETER_SET 512 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #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 +#define MLK_CONFIG_PARAMETER_SET 768 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #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 +#define MLK_CONFIG_PARAMETER_SET 1024 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H #endif /* !MLK_ALL_H */ diff --git a/examples/multilevel_build_native/Makefile b/examples/multilevel_build_native/Makefile index 9d7de14489..098239bdc2 100644 --- a/examples/multilevel_build_native/Makefile +++ b/examples/multilevel_build_native/Makefile @@ -26,7 +26,7 @@ CFLAGS := \ -Wno-unused-command-line-argument \ -O3 \ -fomit-frame-pointer \ - -DMLK_CONFIG_NAMESPACE_PREFIX=mlkem \ + -I mlkem_native \ -std=c99 \ -pedantic \ -MMD \ @@ -55,16 +55,16 @@ endif # Alternatively, you can compile the 'monobuild' source file mlkem_native.c. # See examples/monolithic_build for that. MLK_SOURCE := $(wildcard \ - mlkem_native/mlkem/src/*.c \ - mlkem_native/mlkem/src/**/*.c \ - mlkem_native/mlkem/src/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/*.c \ - mlkem_native/mlkem/src/**/**/**/**/*.c \ - mlkem_native/mlkem/src/*.S \ - mlkem_native/mlkem/src/**/*.S \ - mlkem_native/mlkem/src/**/**/*.S \ - mlkem_native/mlkem/src/**/**/**/*.S \ - mlkem_native/mlkem/src/**/**/**/**/*.S) + mlkem_native/src/*.c \ + mlkem_native/src/**/*.c \ + mlkem_native/src/**/**/*.c \ + mlkem_native/src/**/**/**/*.c \ + mlkem_native/src/**/**/**/**/*.c \ + mlkem_native/src/*.S \ + mlkem_native/src/**/*.S \ + mlkem_native/src/**/**/*.S \ + mlkem_native/src/**/**/**/*.S \ + mlkem_native/src/**/**/**/**/*.S) BUILD_DIR=build MLKEM512_DIR = $(BUILD_DIR)/mlkem512 @@ -78,17 +78,17 @@ MLKEM1024_OBJS=$(patsubst %,$(MLKEM1024_DIR)/%.o,$(MLK_SOURCE)) $(MLKEM512_OBJS): $(MLKEM512_DIR)/%.o: % $(Q)echo " CC $@" $(Q)[ -d $(@D) ] || mkdir -p $(@D) - $(Q)$(CC) -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 -DMLK_CONFIG_MULTILEVEL_WITH_SHARED -DMLK_CONFIG_PARAMETER_SET=512 $(CFLAGS) -c $^ -o $@ + $(Q)$(CC) -DMLK_CONFIG_MULTILEVEL_WITH_SHARED -DMLK_CONFIG_PARAMETER_SET=512 $(CFLAGS) -c $^ -o $@ $(MLKEM768_OBJS): $(MLKEM768_DIR)/%.o: % $(Q)echo " CC $@" $(Q)[ -d $(@D) ] || mkdir -p $(@D) - $(Q)$(CC) -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=768 $(CFLAGS) -c $^ -o $@ + $(Q)$(CC) -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=768 $(CFLAGS) -c $^ -o $@ $(MLKEM1024_OBJS): $(MLKEM1024_DIR)/%.o: % $(Q)echo " CC $@" $(Q)[ -d $(@D) ] || mkdir -p $(@D) - $(Q)$(CC) -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=1024 $(CFLAGS) -c $^ -o $@ + $(Q)$(CC) -DMLK_CONFIG_MULTILEVEL_NO_SHARED -DMLK_CONFIG_PARAMETER_SET=1024 $(CFLAGS) -c $^ -o $@ mlkem512_objs: $(MLKEM512_OBJS) mlkem768_objs: $(MLKEM768_OBJS) diff --git a/examples/multilevel_build_native/README.md b/examples/multilevel_build_native/README.md index 21da82d287..264c11043c 100644 --- a/examples/multilevel_build_native/README.md +++ b/examples/multilevel_build_native/README.md @@ -1,16 +1,59 @@ [//]: # (SPDX-License-Identifier: CC-BY-4.0) -# Multi-level build +# Multi-Level Build (Native Backend) -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. +This directory contains a minimal example for building mlkem-native with support for all three security levels +(ML-KEM-512, ML-KEM-768, ML-KEM-1024), using native backends for optimal performance, with level-independent +code shared to reduce binary size. -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 MLKEM-768 and MLKEM-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. +## Use Case + +Use this approach when: +- You need multiple ML-KEM security levels in the same application +- You want optimal performance via native assembly (AArch64/AVX2) +- You want to build the mlkem-native C files separately, not as a single compilation unit. +- You want to minimize code duplication across levels + +## Components + +1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src), [`mlkem/src/fips202/`](../../mlkem/src/fips202), + and [`mlkem/src/native/`](../../mlkem/src/native) +2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h) +3. Your application source code + +## Configuration + +The library is built 3 times into separate directories (`build/mlkem512`, `build/mlkem768`, `build/mlkem1024`). + +The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets: +- `MLK_CONFIG_MULTILEVEL_BUILD`: Enables multi-level build mode +- `MLK_CONFIG_NAMESPACE_PREFIX=mlkem`: Base prefix; level suffix added automatically +- `MLK_CONFIG_USE_NATIVE_BACKEND_ARITH`: Enables native arithmetic backend +- `MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202`: Enables native FIPS-202 backend + +Build-time flags passed via CFLAGS: +- `MLK_CONFIG_PARAMETER_SET=512/768/1024`: Selects the security level +- `MLK_CONFIG_MULTILEVEL_WITH_SHARED`: Set for ONE build to include shared code +- `MLK_CONFIG_MULTILEVEL_NO_SHARED`: Set for OTHER builds to exclude shared code + +The resulting API functions are namespaced as: +- `mlkem512_keypair()`, `mlkem512_enc()`, `mlkem512_dec()` +- `mlkem768_keypair()`, `mlkem768_enc()`, `mlkem768_dec()` +- `mlkem1024_keypair()`, `mlkem1024_enc()`, `mlkem1024_dec()` + +## Notes + +- Native backends are auto-selected based on the target architecture +- On unsupported platforms, the build falls back to the C backend ## Usage -Build this example with `make build`, run with `make run`. +```bash +make build # Build all three security levels +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/multilevel_build_native/mlkem_native/mlkem b/examples/multilevel_build_native/mlkem_native/mlkem deleted file mode 120000 index f4ec7bdb2d..0000000000 --- a/examples/multilevel_build_native/mlkem_native/mlkem +++ /dev/null @@ -1 +0,0 @@ -../../../mlkem \ No newline at end of file diff --git a/examples/multilevel_build_native/mlkem_native/mlkem_native.S b/examples/multilevel_build_native/mlkem_native/mlkem_native.S new file mode 120000 index 0000000000..9bb5ab1011 --- /dev/null +++ b/examples/multilevel_build_native/mlkem_native/mlkem_native.S @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.S \ No newline at end of file diff --git a/examples/multilevel_build_native/mlkem_native/mlkem_native.c b/examples/multilevel_build_native/mlkem_native/mlkem_native.c new file mode 120000 index 0000000000..2afd79e7dc --- /dev/null +++ b/examples/multilevel_build_native/mlkem_native/mlkem_native.c @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.c \ No newline at end of file diff --git a/examples/multilevel_build_native/mlkem_native/mlkem_native.h b/examples/multilevel_build_native/mlkem_native/mlkem_native.h new file mode 120000 index 0000000000..dd32c33bb2 --- /dev/null +++ b/examples/multilevel_build_native/mlkem_native/mlkem_native.h @@ -0,0 +1 @@ +../../../mlkem/mlkem_native.h \ No newline at end of file diff --git a/examples/multilevel_build_native/mlkem_native/mlkem_native_config.h b/examples/multilevel_build_native/mlkem_native/mlkem_native_config.h new file mode 100644 index 0000000000..95b55f1720 --- /dev/null +++ b/examples/multilevel_build_native/mlkem_native/mlkem_native_config.h @@ -0,0 +1,649 @@ +/* + * 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 + * + * - [FIPS203] + * FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard + * National Institute of Standards and Technology + * https://csrc.nist.gov/pubs/fips/203/final + */ + +/* + * WARNING: This file is auto-generated from scripts/autogen + * in the mlkem-native repository. + * Do not modify it directly. + */ + +/* + * Test configuration: Multilevel build config + * + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: + * - MLK_CONFIG_MULTILEVEL_BUILD + * - MLK_CONFIG_NAMESPACE_PREFIX + * - MLK_CONFIG_USE_NATIVE_BACKEND_ARITH + * - MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 + */ + + +#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 + * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * + * 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 the 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. + * + *****************************************************************************/ +/* No need to set this -- we _are_ already in a custom config */ +/* #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, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_NAMESPACE_PREFIX mlkem + +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +#define MLK_CONFIG_MULTILEVEL_BUILD + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) +/****************************************************************************** + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * 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. + * + *****************************************************************************/ +#define MLK_CONFIG_USE_NATIVE_BACKEND_ARITH + +/****************************************************************************** + * 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. + * + *****************************************************************************/ +#define MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 + +/****************************************************************************** + * 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 @[FIPS203, 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 "src/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 "src/sys.h" + static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + * + * Description: mlkem-native backends may rely on specific hardware features. + * Those backends will only be included in an mlkem-native build + * if support for the respective features is enabled at + * compile-time. However, when building for a heteroneous set + * of CPUs to run the resulting binary/library on, feature + * detection at _runtime_ is needed to decided whether a backend + * can be used or not. + * + * Set this option and define `mlk_sys_check_capability` if you + * want to use a custom method to dispatch between implementations. + * + * If this option is not set, mlkem-native uses compile-time + * feature detection only to decide which backend to use. + * + * If you compile mlkem-native on a system with different + * capabilities than the system that the resulting binary/library + * will be run on, you must use this option. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CUSTOM_CAPABILITY_FUNC + static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) + __contract__( + ensures(return_value == 0 || return_value == 1) + ) + { + ... your implementation ... + } +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * 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_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_NO_ASM_VALUE_BARRIER + * + * Description: If this option is set, mlkem-native will be built without + * use of native code or inline assembly for value barriers. + * + * By default, inline assembly (if available) is used to implement + * value barriers. + * Without inline assembly, mlkem-native will use a global volatile + * 'opt blocker' instead; see verify.h. + * + *****************************************************************************/ +/* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ + +/****************************************************************************** + * 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 "src/sys.h" + static MLK_INLINE int mlk_break_pct(void) + { + ... return 0/1 depending on whether PCT should be broken ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLK_CONFIG_SERIAL_FIPS202_ONLY + * + * Description: Set this to use a FIPS202 implementation with global state + * that supports only one active Keccak computation at a time + * (e.g. some hardware accelerators). + * + * If this option is set, batched Keccak operations are + * disabled for rejection sampling during matrix generation. + * Instead, matrix entries will be generated one at a time. + * + * This allows offloading Keccak computations to a hardware + * accelerator that holds only a single Keccak state locally, + * rather than requiring support for batched (4x) Keccak states. + * + * NOTE: Depending on the target CPU, disabling batched Keccak + * may reduce performance when using software FIPS202 + * implementations. Only enable this when you have to. + * + *****************************************************************************/ +/* #define MLK_CONFIG_SERIAL_FIPS202_ONLY */ + +/************************* Config internals ********************************/ + +#endif /* MLK_BUILD_INTERNAL */ + +/* 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_native/mlkem_native/src b/examples/multilevel_build_native/mlkem_native/src new file mode 120000 index 0000000000..9a403331c4 --- /dev/null +++ b/examples/multilevel_build_native/mlkem_native/src @@ -0,0 +1 @@ +../../../mlkem/src \ No newline at end of file diff --git a/examples/multilevel_build_native/mlkem_native_all.h b/examples/multilevel_build_native/mlkem_native_all.h index c7915fd454..ba63dd915e 100644 --- a/examples/multilevel_build_native/mlkem_native_all.h +++ b/examples/multilevel_build_native/mlkem_native_all.h @@ -7,27 +7,21 @@ #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 +#define MLK_CONFIG_PARAMETER_SET 512 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #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 +#define MLK_CONFIG_PARAMETER_SET 768 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #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 +#define MLK_CONFIG_PARAMETER_SET 1024 +#include "mlkem_native/mlkem_native.h" +#undef MLK_CONFIG_PARAMETER_SET #undef MLK_H #endif /* !MLK_ALL_H */ diff --git a/mlkem/README.md b/mlkem/README.md index 63f6c92bd2..fc96c73fb3 100644 --- a/mlkem/README.md +++ b/mlkem/README.md @@ -12,11 +12,11 @@ Alternatively, you can use the auto-geneated helper files [mlkem_native.c](mlkem ## Configuration -The build is configured by [src/config.h](src/config.h). Note in particular `MLK_CONFIG_PARAMETER_SET` and `MLK_CONFIG_NAMESPACE_PREFIX`, which set the parameter set and namespace prefix, respectively. +The build is configured by [mlkem_native_config.h](mlkem_native_config.h), or by the file pointed to by `MLK_CONFIG_FILE`. Note in particular `MLK_CONFIG_PARAMETER_SET` and `MLK_CONFIG_NAMESPACE_PREFIX`, which set the parameter set and namespace prefix, respectively. ## API -The public API is defined in [mlkem_native.h](mlkem_native.h). Before you include [mlkem_native.h](mlkem_native.h), you must set `MLK_CONFIG_API_PARAMETER_SET` and `MLK_CONFIG_API_NAMESPACE_PREFIX`, mirroring `MLK_CONFIG_PARAMETER_SET` and `MLK_CONFIG_NAMESPACE_PREFIX` that was used in the build (we hope to make this more convenient in the future). +The public API is defined in [mlkem_native.h](mlkem_native.h). ## Supporting multiple parameter sets diff --git a/mlkem/mlkem_native.S b/mlkem/mlkem_native.S index 48b117404b..dbbf22c5c5 100644 --- a/mlkem/mlkem_native.S +++ b/mlkem/mlkem_native.S @@ -60,30 +60,30 @@ #if defined(MLK_CONFIG_USE_NATIVE_BACKEND_ARITH) #if defined(MLK_SYS_AARCH64) -#include "mlkem/src/native/aarch64/src/intt.S" -#include "mlkem/src/native/aarch64/src/ntt.S" -#include "mlkem/src/native/aarch64/src/poly_mulcache_compute_asm.S" -#include "mlkem/src/native/aarch64/src/poly_reduce_asm.S" -#include "mlkem/src/native/aarch64/src/poly_tobytes_asm.S" -#include "mlkem/src/native/aarch64/src/poly_tomont_asm.S" -#include "mlkem/src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k2.S" -#include "mlkem/src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k3.S" -#include "mlkem/src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k4.S" -#include "mlkem/src/native/aarch64/src/rej_uniform_asm.S" +#include "src/native/aarch64/src/intt.S" +#include "src/native/aarch64/src/ntt.S" +#include "src/native/aarch64/src/poly_mulcache_compute_asm.S" +#include "src/native/aarch64/src/poly_reduce_asm.S" +#include "src/native/aarch64/src/poly_tobytes_asm.S" +#include "src/native/aarch64/src/poly_tomont_asm.S" +#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k2.S" +#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k3.S" +#include "src/native/aarch64/src/polyvec_basemul_acc_montgomery_cached_asm_k4.S" +#include "src/native/aarch64/src/rej_uniform_asm.S" #endif /* MLK_SYS_AARCH64 */ #if defined(MLK_SYS_X86_64) -#include "mlkem/src/native/x86_64/src/intt.S" -#include "mlkem/src/native/x86_64/src/mulcache_compute.S" -#include "mlkem/src/native/x86_64/src/ntt.S" -#include "mlkem/src/native/x86_64/src/nttfrombytes.S" -#include "mlkem/src/native/x86_64/src/ntttobytes.S" -#include "mlkem/src/native/x86_64/src/nttunpack.S" -#include "mlkem/src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k2.S" -#include "mlkem/src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k3.S" -#include "mlkem/src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k4.S" -#include "mlkem/src/native/x86_64/src/reduce.S" -#include "mlkem/src/native/x86_64/src/rej_uniform_asm.S" -#include "mlkem/src/native/x86_64/src/tomont.S" +#include "src/native/x86_64/src/intt.S" +#include "src/native/x86_64/src/mulcache_compute.S" +#include "src/native/x86_64/src/ntt.S" +#include "src/native/x86_64/src/nttfrombytes.S" +#include "src/native/x86_64/src/ntttobytes.S" +#include "src/native/x86_64/src/nttunpack.S" +#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k2.S" +#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k3.S" +#include "src/native/x86_64/src/polyvec_basemul_acc_montgomery_cached_asm_k4.S" +#include "src/native/x86_64/src/reduce.S" +#include "src/native/x86_64/src/rej_uniform_asm.S" +#include "src/native/x86_64/src/tomont.S" #endif /* MLK_SYS_X86_64 */ #if defined(MLK_SYS_RISCV64) #endif @@ -91,11 +91,11 @@ #if defined(MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202) #if defined(MLK_SYS_AARCH64) -#include "mlkem/src/fips202/native/aarch64/src/keccak_f1600_x1_scalar_asm.S" -#include "mlkem/src/fips202/native/aarch64/src/keccak_f1600_x1_v84a_asm.S" -#include "mlkem/src/fips202/native/aarch64/src/keccak_f1600_x2_v84a_asm.S" -#include "mlkem/src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_scalar_hybrid_asm.S" -#include "mlkem/src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_v84a_scalar_hybrid_asm.S" +#include "src/fips202/native/aarch64/src/keccak_f1600_x1_scalar_asm.S" +#include "src/fips202/native/aarch64/src/keccak_f1600_x1_v84a_asm.S" +#include "src/fips202/native/aarch64/src/keccak_f1600_x2_v84a_asm.S" +#include "src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_scalar_hybrid_asm.S" +#include "src/fips202/native/aarch64/src/keccak_f1600_x4_v8a_v84a_scalar_hybrid_asm.S" #endif /* MLK_SYS_AARCH64 */ #if defined(MLK_SYS_X86_64) #endif @@ -156,8 +156,15 @@ #undef MLK_API_CONCAT #undef MLK_API_CONCAT_ #undef MLK_API_CONCAT_UNDERSCORE +#undef MLK_API_LEGACY_CONFIG #undef MLK_API_MUST_CHECK_RETURN_VALUE #undef MLK_API_NAMESPACE +#undef MLK_API_QUALIFIER +#undef MLK_CONFIG_API_CONSTANTS_ONLY +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_QUALIFIER #undef MLK_H #undef crypto_kem_check_pk #undef crypto_kem_check_sk @@ -170,17 +177,15 @@ #undef MLK_ADD_PARAM_SET #undef MLK_ASM_FN_SYMBOL #undef MLK_ASM_NAMESPACE +#undef MLK_BUILD_INTERNAL #undef MLK_COMMON_H #undef MLK_CONCAT #undef MLK_CONCAT_ -#undef MLK_CONFIG_API_NAMESPACE_PREFIX -#undef MLK_CONFIG_API_PARAMETER_SET #undef MLK_EMPTY_CU #undef MLK_EXTERNAL_API #undef MLK_FIPS202X4_HEADER_FILE #undef MLK_FIPS202_HEADER_FILE #undef MLK_INTERNAL_API -#undef MLK_MULTILEVEL_BUILD #undef MLK_NAMESPACE #undef MLK_NAMESPACE_K #undef MLK_NAMESPACE_PREFIX @@ -194,7 +199,7 @@ #undef mlk_indcpa_enc #undef mlk_indcpa_keypair_derand /* mlkem/src/kem.h */ -#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_NO_SUPERCOP #undef MLK_KEM_H #undef crypto_kem_check_pk #undef crypto_kem_check_sk diff --git a/mlkem/mlkem_native.c b/mlkem/mlkem_native.c index 9100915359..bd5182665b 100644 --- a/mlkem/mlkem_native.c +++ b/mlkem/mlkem_native.c @@ -145,8 +145,15 @@ #undef MLK_API_CONCAT #undef MLK_API_CONCAT_ #undef MLK_API_CONCAT_UNDERSCORE +#undef MLK_API_LEGACY_CONFIG #undef MLK_API_MUST_CHECK_RETURN_VALUE #undef MLK_API_NAMESPACE +#undef MLK_API_QUALIFIER +#undef MLK_CONFIG_API_CONSTANTS_ONLY +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_QUALIFIER #undef MLK_H #undef crypto_kem_check_pk #undef crypto_kem_check_sk @@ -159,17 +166,15 @@ #undef MLK_ADD_PARAM_SET #undef MLK_ASM_FN_SYMBOL #undef MLK_ASM_NAMESPACE +#undef MLK_BUILD_INTERNAL #undef MLK_COMMON_H #undef MLK_CONCAT #undef MLK_CONCAT_ -#undef MLK_CONFIG_API_NAMESPACE_PREFIX -#undef MLK_CONFIG_API_PARAMETER_SET #undef MLK_EMPTY_CU #undef MLK_EXTERNAL_API #undef MLK_FIPS202X4_HEADER_FILE #undef MLK_FIPS202_HEADER_FILE #undef MLK_INTERNAL_API -#undef MLK_MULTILEVEL_BUILD #undef MLK_NAMESPACE #undef MLK_NAMESPACE_K #undef MLK_NAMESPACE_PREFIX @@ -183,7 +188,7 @@ #undef mlk_indcpa_enc #undef mlk_indcpa_keypair_derand /* mlkem/src/kem.h */ -#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_NO_SUPERCOP #undef MLK_KEM_H #undef crypto_kem_check_pk #undef crypto_kem_check_sk diff --git a/mlkem/mlkem_native.h b/mlkem/mlkem_native.h index 08e083d9d5..5d61e928a1 100644 --- a/mlkem/mlkem_native.h +++ b/mlkem/mlkem_native.h @@ -15,20 +15,30 @@ #ifndef MLK_H #define MLK_H -/****************************************************************************** - * - * Public API for mlkem-native +/* + * Public API for mlkem-native. * * This header defines the public API of a single build of mlkem-native. * - * # Examples + * Make sure the configuration file is in the include path + * (this is "mlkem_native_config.h" by default, or MLK_CONFIG_FILE if defined). + * + * # Multi-level builds + * + * This header specifies a build of mlkem-native for a fixed security level. + * If you need multiple security levels, leave the security level unspecified + * in the configuration file and include this header multiple times, setting + * MLK_CONFIG_PARAMETER_SET accordingly for each, and #undef'ing the MLK_H + * guard to allow multiple inclusions. * - * See [examples/basic], [examples/multilevel_build], and - * [examples/multilevel_build_native] for examples of how to use this header. + * # Legacy configuration (deprecated) * - * # Usage + * Instead of providing the config file used for the build, you can + * alternatively set the following configuration options prior to + * including this header. * - * To use this header, configure the following options: + * This method of configuration is deprecated. + * It will be removed in mlkem-native-v2. * * - MLK_CONFIG_API_PARAMETER_SET [required] * @@ -56,14 +66,9 @@ * MLK_CONFIG_API_PARAMETER_SET or MLK_CONFIG_API_NAMESPACE_PREFIX, * nor include a configuration. * - * # Multi-level builds + * - MLK_CONFIG_API_QUALIFIER [optional] * - * This header specifies a build of mlkem-native for a fixed security level. - * If you need multiple builds, e.g. to build a library offering multiple - * security levels, you need multiple instances of this header. - * - * NOTE: In this case, you must rename or #undef the MLK_H header guard - * prior to subsequent inclusions of this file. + * Qualifier to apply to external API. * ******************************************************************************/ @@ -106,19 +111,51 @@ /****************************** Function API **********************************/ -#if !defined(MLK_CONFIG_API_CONSTANTS_ONLY) +#define MLK_API_CONCAT_(x, y) x##y +#define MLK_API_CONCAT(x, y) MLK_API_CONCAT_(x, y) +#define MLK_API_CONCAT_UNDERSCORE(x, y) MLK_API_CONCAT(MLK_API_CONCAT(x, _), y) #if !defined(MLK_CONFIG_API_PARAMETER_SET) -#error MLK_CONFIG_API_PARAMETER_SET not defined +/* Recommended configuration via same config file as used for the build. */ + +/* For now, we derive the legacy API configuration MLK_CONFIG_API_XXX from + * the config file. In mlkem-native-v2, this will be removed and we will + * exclusively work with MLK_CONFIG_XXX. */ + +/* You need to make sure the config file is in the include path. */ +#if defined(MLK_CONFIG_FILE) +#include MLK_CONFIG_FILE +#else +#include "mlkem_native_config.h" #endif -#if !defined(MLK_CONFIG_API_NAMESPACE_PREFIX) -#error MLK_CONFIG_API_NAMESPACE_PREFIX not defined + +#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET + +#if defined(MLK_CONFIG_MULTILEVEL_BUILD) +#define MLK_CONFIG_API_NAMESPACE_PREFIX \ + MLK_API_CONCAT(MLK_CONFIG_NAMESPACE_PREFIX, MLK_CONFIG_PARAMETER_SET) +#else +#define MLK_CONFIG_API_NAMESPACE_PREFIX MLK_CONFIG_NAMESPACE_PREFIX #endif -/* Derive namespacing macro */ -#define MLK_API_CONCAT_(x, y) x##y -#define MLK_API_CONCAT(x, y) MLK_API_CONCAT_(x, y) -#define MLK_API_CONCAT_UNDERSCORE(x, y) MLK_API_CONCAT(MLK_API_CONCAT(x, _), y) +#if defined(MLK_CONFIG_NO_SUPERCOP) +#define MLK_CONFIG_API_NO_SUPERCOP +#endif + +#if defined(MLK_CONFIG_CONSTANTS_ONLY) +#define MLK_CONFIG_API_CONSTANTS_ONLY +#endif + +#if defined(MLK_CONFIG_EXTERNAL_API_QUALIFIER) +#define MLK_CONFIG_API_QUALIFIER MLK_CONFIG_EXTERNAL_API_QUALIFIER +#endif + +#else /* !MLK_CONFIG_API_PARAMETER_SET */ + +#define MLK_API_LEGACY_CONFIG + +#endif /* MLK_CONFIG_API_PARAMETER_SET */ + #define MLK_API_NAMESPACE(sym) \ MLK_API_CONCAT_UNDERSCORE(MLK_CONFIG_API_NAMESPACE_PREFIX, sym) @@ -128,6 +165,14 @@ #define MLK_API_MUST_CHECK_RETURN_VALUE #endif +#if defined(MLK_CONFIG_API_QUALIFIER) +#define MLK_API_QUALIFIER MLK_CONFIG_API_QUALIFIER +#else +#define MLK_API_QUALIFIER +#endif + +#if !defined(MLK_CONFIG_API_CONSTANTS_ONLY) + #include /************************************************* @@ -149,6 +194,7 @@ * Specification: Implements @[FIPS203, Algorithm 16, ML-KEM.KeyGen_Internal] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(keypair_derand)( uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)], @@ -173,6 +219,7 @@ int MLK_API_NAMESPACE(keypair_derand)( * Specification: Implements @[FIPS203, Algorithm 19, ML-KEM.KeyGen] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(keypair)( uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)], @@ -201,6 +248,7 @@ int MLK_API_NAMESPACE(keypair)( * Specification: Implements @[FIPS203, Algorithm 17, ML-KEM.Encaps_Internal] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(enc_derand)( uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)], @@ -229,6 +277,7 @@ int MLK_API_NAMESPACE(enc_derand)( * Specification: Implements @[FIPS203, Algorithm 20, ML-KEM.Encaps] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(enc)( uint8_t ct[MLKEM_CIPHERTEXTBYTES(MLK_CONFIG_API_PARAMETER_SET)], @@ -256,6 +305,7 @@ int MLK_API_NAMESPACE(enc)( * Specification: Implements @[FIPS203, Algorithm 21, ML-KEM.Decaps] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(dec)( uint8_t ss[MLKEM_BYTES], @@ -277,6 +327,7 @@ int MLK_API_NAMESPACE(dec)( * Specification: Implements @[FIPS203, Section 7.2, 'modulus check'] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(check_pk)( const uint8_t pk[MLKEM_PUBLICKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]); @@ -297,6 +348,7 @@ int MLK_API_NAMESPACE(check_pk)( * Specification: Implements @[FIPS203, Section 7.3, 'hash check'] * **************************************************/ +MLK_API_QUALIFIER MLK_API_MUST_CHECK_RETURN_VALUE int MLK_API_NAMESPACE(check_sk)( const uint8_t sk[MLKEM_SECRETKEYBYTES(MLK_CONFIG_API_PARAMETER_SET)]); @@ -324,11 +376,21 @@ int MLK_API_NAMESPACE(check_sk)( /* If the SUPERCOP API is not needed, we can undefine the various helper macros * above. Otherwise, they are needed for lazy evaluation of crypto_kem_xxx. */ +#if !defined(MLK_API_LEGACY_CONFIG) +#undef MLK_CONFIG_API_PARAMETER_SET +#undef MLK_CONFIG_API_NAMESPACE_PREFIX +#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_API_CONSTANTS_ONLY +#undef MLK_CONFIG_API_QUALIFIER +#endif /* !MLK_API_LEGACY_CONFIG */ + #undef MLK_API_CONCAT #undef MLK_API_CONCAT_ #undef MLK_API_CONCAT_UNDERSCORE #undef MLK_API_NAMESPACE #undef MLK_API_MUST_CHECK_RETURN_VALUE +#undef MLK_API_QUALIFIER +#undef MLK_API_LEGACY_CONFIG #endif /* MLK_CONFIG_API_NO_SUPERCOP */ #endif /* !MLK_CONFIG_API_CONSTANTS_ONLY */ diff --git a/mlkem/src/config.h b/mlkem/mlkem_native_config.h similarity index 88% rename from mlkem/src/config.h rename to mlkem/mlkem_native_config.h index 49a19361b9..8683b04b73 100644 --- a/mlkem/src/config.h +++ b/mlkem/mlkem_native_config.h @@ -29,6 +29,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -60,11 +65,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -73,6 +75,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -92,6 +183,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -113,6 +205,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -284,7 +377,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -310,7 +403,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -365,7 +458,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -388,7 +481,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -408,21 +501,6 @@ *****************************************************************************/ /* #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 * @@ -472,24 +550,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -519,7 +579,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -551,6 +611,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/mlkem/src/common.h b/mlkem/src/common.h index d03f3db7d7..d339f3fcef 100644 --- a/mlkem/src/common.h +++ b/mlkem/src/common.h @@ -5,10 +5,12 @@ #ifndef MLK_COMMON_H #define MLK_COMMON_H +#define MLK_BUILD_INTERNAL + #if defined(MLK_CONFIG_FILE) #include MLK_CONFIG_FILE #else -#include "config.h" +#include "mlkem_native_config.h" #endif #include "params.h" @@ -28,15 +30,11 @@ #define MLK_EXTERNAL_API MLK_CONFIG_EXTERNAL_API_QUALIFIER #endif -#if defined(MLK_CONFIG_MULTILEVEL_NO_SHARED) || \ - defined(MLK_CONFIG_MULTILEVEL_WITH_SHARED) -#define MLK_MULTILEVEL_BUILD -#endif - #define MLK_CONCAT_(x1, x2) x1##x2 #define MLK_CONCAT(x1, x2) MLK_CONCAT_(x1, x2) -#if defined(MLK_MULTILEVEL_BUILD) +#if (defined(MLK_CONFIG_MULTILEVEL_WITH_SHARED) || \ + defined(MLK_CONFIG_MULTILEVEL_NO_SHARED)) #define MLK_ADD_PARAM_SET(s) MLK_CONCAT(s, MLK_CONFIG_PARAMETER_SET) #else #define MLK_ADD_PARAM_SET(s) s @@ -152,20 +150,4 @@ #endif #endif /* !__ASSEMBLER__ */ -/* Just in case we want to include mlkem_native.h, set the configuration - * for that header in accordance with the configuration used here. */ - -/* Double-check that this is not conflicting with pre-existing definitions. */ -#if defined(MLK_CONFIG_API_PARAMETER_SET) || \ - defined(MLK_CONFIG_API_NAMESPACE_PREFIX) || \ - defined(MLK_CONFIG_API_NO_SUPERCOP) || \ - defined(MLK_CONFIG_API_CONSTANTS_ONLY) -#error Pre-existing MLK_CONFIG_API_XXX configuration is neither useful nor allowed during an mlkem-native build -#endif /* MLK_CONFIG_API_PARAMETER_SET || MLK_CONFIG_API_NAMESPACE_PREFIX || \ - MLK_CONFIG_API_NO_SUPERCOP || MLK_CONFIG_API_CONSTANTS_ONLY */ - -#define MLK_CONFIG_API_PARAMETER_SET MLK_CONFIG_PARAMETER_SET -#define MLK_CONFIG_API_NAMESPACE_PREFIX \ - MLK_ADD_PARAM_SET(MLK_CONFIG_NAMESPACE_PREFIX) - #endif /* !MLK_COMMON_H */ diff --git a/mlkem/src/kem.h b/mlkem/src/kem.h index 506c53f8ad..582df3ecea 100644 --- a/mlkem/src/kem.h +++ b/mlkem/src/kem.h @@ -28,9 +28,9 @@ #if defined(MLK_CHECK_APIS) /* Include to ensure consistency between internal kem.h * and external mlkem_native.h. */ -#define MLK_CONFIG_API_NO_SUPERCOP +#define MLK_CONFIG_NO_SUPERCOP #include "mlkem_native.h" -#undef MLK_CONFIG_API_NO_SUPERCOP +#undef MLK_CONFIG_NO_SUPERCOP #if MLKEM_INDCCA_SECRETKEYBYTES != \ MLKEM_SECRETKEYBYTES(MLK_CONFIG_PARAMETER_SET) diff --git a/mlkem/src/params.h b/mlkem/src/params.h index 3f81bb0e2e..04598539c4 100644 --- a/mlkem/src/params.h +++ b/mlkem/src/params.h @@ -5,12 +5,6 @@ #ifndef MLK_PARAMS_H #define MLK_PARAMS_H -#if defined(MLK_CONFIG_FILE) -#include MLK_CONFIG_FILE -#else -#include "config.h" -#endif - #if !defined(MLK_CONFIG_PARAMETER_SET) #error MLK_CONFIG_PARAMETER_SET is not defined #endif diff --git a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k2_native_aarch64/Makefile b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k2_native_aarch64/Makefile index ed271bf0e3..a0d2dc4522 100644 --- a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k2_native_aarch64/Makefile +++ b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k2_native_aarch64/Makefile @@ -12,7 +12,7 @@ PROOF_UID = polyvec_basemul_acc_montgomery_cached_k2_native_aarch64 # We need to set MLK_CHECK_APIS as otherwise mlkem/src/native/api.h won't be # included, which contains the CBMC specifications. -DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL_WITH_SHARED +DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL -DMLK_CONFIG_MULTILEVEL_WITH_SHARED INCLUDES += REMOVE_FUNCTION_BODY += diff --git a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k3_native_aarch64/Makefile b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k3_native_aarch64/Makefile index 789e7bf371..8a47a80e09 100644 --- a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k3_native_aarch64/Makefile +++ b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k3_native_aarch64/Makefile @@ -12,7 +12,7 @@ PROOF_UID = polyvec_basemul_acc_montgomery_cached_k3_native_aarch64 # We need to set MLK_CHECK_APIS as otherwise mlkem/src/native/api.h won't be # included, which contains the CBMC specifications. -DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL_WITH_SHARED +DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL -DMLK_CONFIG_MULTILEVEL_WITH_SHARED INCLUDES += REMOVE_FUNCTION_BODY += diff --git a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k4_native_aarch64/Makefile b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k4_native_aarch64/Makefile index fc80f39cae..99e2ec4847 100644 --- a/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k4_native_aarch64/Makefile +++ b/proofs/cbmc/polyvec_basemul_acc_montgomery_cached_k4_native_aarch64/Makefile @@ -12,7 +12,7 @@ PROOF_UID = polyvec_basemul_acc_montgomery_cached_k4_native_aarch64 # We need to set MLK_CHECK_APIS as otherwise mlkem/src/native/api.h won't be # included, which contains the CBMC specifications. -DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL_WITH_SHARED +DEFINES += -DMLK_CONFIG_USE_NATIVE_BACKEND_ARITH -DMLK_CONFIG_ARITH_BACKEND_FILE="\"$(SRCDIR)/mlkem/src/native/aarch64/meta.h\"" -DMLK_CHECK_APIS -DMLK_CONFIG_MULTILEVEL -DMLK_CONFIG_MULTILEVEL_WITH_SHARED INCLUDES += REMOVE_FUNCTION_BODY += diff --git a/scripts/autogen b/scripts/autogen index 7bcae9af4d..c6d86c671f 100755 --- a/scripts/autogen +++ b/scripts/autogen @@ -1588,7 +1588,7 @@ def k_specific(c): def k_generic(c): - return not k_specific(c) and c != "mlkem/src/config.h" + return not k_specific(c) and c != "mlkem/mlkem_native_config.h" def gen_macro_undefs(extra_notes=None): @@ -1768,7 +1768,7 @@ def gen_monolithic_source_file(): def gen_monolithic_asm_file(): def gen(): - asm_sources = get_asm_source_files(main_only=True) + asm_sources = get_asm_source_files(main_only=True, strip_mlkem=True) yield from gen_header() yield "/******************************************************************************" yield " *" @@ -1865,7 +1865,7 @@ def gen_monolithic_asm_file(): def get_config_options(): - content = read_file("mlkem/src/config.h") + content = read_file("mlkem/mlkem_native_config.h") config_pattern = r"Name:\s*(MLK_CONFIG_\w+)" configs = re.findall(config_pattern, content) @@ -1881,6 +1881,7 @@ def get_config_options(): "MLKEM_DEBUG", # TODO: Rename? "MLK_BREAK_PCT", # Use in PCT breakage test] "MLK_CHECK_APIS", + "MLK_CONFIG_XXX", "MLK_CONFIG_API_XXX", "MLK_USE_NATIVE_XXX", ] @@ -2145,6 +2146,10 @@ def update_via_simpasm( outfile = infile outfile_full = os.path.join(outdir, outfile) + if cflags is None: + cflags = "" + cflags += " -Imlkem" + # Check if we need to use a cross-compiler if "aarch64" in infile_full: source_arch = "aarch64" @@ -2219,7 +2224,7 @@ def gen_hol_light_asm_file(job): f"{indir}/{infile}", "proofs/hol_light/" + arm_or_x86 + "/mlkem", outfile=outfile, - cflags=cflags, + cflags=cflags + " -Imlkem", preserve_header=False, ) @@ -2524,7 +2529,10 @@ def adjust_header_guard_for_filename(content, header_file): status_update("header guards", header_file) content = content.split("\n") - exceptions = {"mlkem/mlkem_native.h": "MLK_H"} + exceptions = { + "mlkem/mlkem_native.h": "MLK_H", + "mlkem/mlkem_native_config.h": "MLK_CONFIG_H", + } # Use full filename as the header guard, with '/' and '.' replaced by '_' guard_name = ( @@ -2980,8 +2988,6 @@ def get_oqs_shared_sources(backend): for f in os.listdir(f"{mlkem_dir}/native") if os.path.isfile(f"{mlkem_dir}/native/{f}") ] - # We use a custom config - sources.remove("mlkem/src/config.h") # Add FIPS202 glue code sources += [ "integration/liboqs/fips202_glue.h", @@ -3198,7 +3204,7 @@ def gen_test_config(config_path, config_spec, default_config_content): header.append(f" * Test configuration: {config_spec['description']}") header.append(" *") header.append( - " * This configuration differs from the default mlkem/src/config.h in the following places:" + " * This configuration differs from the default mlkem/mlkem_native_config.h in the following places:" ) def spec_has_value(opt_value): @@ -3285,7 +3291,7 @@ def gen_test_configs(): metadata = yaml.safe_load(read_file("test/configs.yml")) # Load default config - default_config = read_file("mlkem/src/config.h") + default_config = read_file("mlkem/mlkem_native_config.h") # Generate each test config for config_spec in metadata["configs"]: diff --git a/scripts/lint b/scripts/lint index 205b9e3f92..018d863f05 100755 --- a/scripts/lint +++ b/scripts/lint @@ -157,7 +157,7 @@ check-spdx() success=false fi done - for file in $(git ls-files -- "*.[chsS]" "*.py" "*.mk" "*.yml" "**/Makefile*" ":/!proofs/cbmc/*.py" ":/!examples/bring_your_own_fips202/custom_fips202/tiny_sha3/*" ":/!examples/custom_backend/mlkem_native/mlkem/src/fips202/native/custom/src/*"); do + for file in $(git ls-files -- "*.[chsS]" "*.py" "*.mk" "*.yml" "**/Makefile*" ":/!proofs/cbmc/*.py" ":/!examples/bring_your_own_fips202/custom_fips202/tiny_sha3/*" ":/!examples/custom_backend/mlkem_native/src/fips202/native/custom/src/*"); do # Ignore symlinks if [[ ! -L $file && $(grep "Copyright (c) The mlkem-native project authors" $file | wc -l) == 0 ]]; then gh_error "$file" "${line:-1}" "Missing copyright header error" "$file is missing copyright header" diff --git a/test/break_pct_config.h b/test/break_pct_config.h index 90737e6331..3f3b8add3e 100644 --- a/test/break_pct_config.h +++ b/test/break_pct_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration for PCT breakage testing * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_KEYGEN_PCT * - MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -381,7 +474,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -404,7 +497,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -424,21 +517,6 @@ *****************************************************************************/ /* #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 * @@ -488,24 +566,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -571,6 +631,8 @@ static MLK_INLINE int mlk_break_pct(void) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/configs.yml b/test/configs.yml index 0f940b83ae..b497a63871 100644 --- a/test/configs.yml +++ b/test/configs.yml @@ -282,71 +282,53 @@ configs: # Example configs - - path: examples/monolithic_build/config_512.h - description: "Monolithic build config for ML-KEM-512" + - path: examples/monolithic_build/mlkem_native/mlkem_native_config.h + description: "Monolithic build config" defines: - MLK_CONFIG_PARAMETER_SET: 512 MLK_CONFIG_NAMESPACE_PREFIX: mlkem MLK_CONFIG_INTERNAL_API_QUALIFIER: static MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/monolithic_build/config_768.h - description: "Monolithic build config for ML-KEM-768" + - path: examples/monolithic_build_native/mlkem_native/mlkem_native_config.h + description: "Monolithic build config (native backends disabled)" defines: - MLK_CONFIG_PARAMETER_SET: 768 MLK_CONFIG_NAMESPACE_PREFIX: mlkem MLK_CONFIG_INTERNAL_API_QUALIFIER: static MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/monolithic_build/config_1024.h - description: "Monolithic build config for ML-KEM-1024" - defines: - MLK_CONFIG_PARAMETER_SET: 1024 - MLK_CONFIG_NAMESPACE_PREFIX: mlkem - MLK_CONFIG_INTERNAL_API_QUALIFIER: static - MLK_CONFIG_FILE: - comment: "/* No need to set this -- we _are_ already in a custom config */" - - - path: examples/monolithic_build_native/config_512.h - description: "Monolithic build config for ML-KEM-512 (native backends disabled)" - defines: - MLK_CONFIG_PARAMETER_SET: 512 - MLK_CONFIG_NAMESPACE_PREFIX: mlkem - MLK_CONFIG_INTERNAL_API_QUALIFIER: static - MLK_CONFIG_FILE: - comment: "/* No need to set this -- we _are_ already in a custom config */" - - - path: examples/monolithic_build_native/config_768.h - description: "Monolithic build config for ML-KEM-768 (native backends disabled)" + - path: examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h + description: "Multilevel monolithic build config" defines: - MLK_CONFIG_PARAMETER_SET: 768 + MLK_CONFIG_MULTILEVEL_BUILD: true MLK_CONFIG_NAMESPACE_PREFIX: mlkem MLK_CONFIG_INTERNAL_API_QUALIFIER: static MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/monolithic_build_native/config_1024.h - description: "Monolithic build config for ML-KEM-1024 (native backends disabled)" + - path: examples/multilevel_build/mlkem_native/mlkem_native_config.h + description: "Multilevel build config" defines: - MLK_CONFIG_PARAMETER_SET: 1024 + MLK_CONFIG_MULTILEVEL_BUILD: true MLK_CONFIG_NAMESPACE_PREFIX: mlkem - MLK_CONFIG_INTERNAL_API_QUALIFIER: static MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/monolithic_build_multilevel/multilevel_config.h - description: "Multilevel monolithic build config" + - path: examples/multilevel_build_native/mlkem_native/mlkem_native_config.h + description: "Multilevel build config" defines: + MLK_CONFIG_MULTILEVEL_BUILD: true MLK_CONFIG_NAMESPACE_PREFIX: mlkem - MLK_CONFIG_INTERNAL_API_QUALIFIER: static + MLK_CONFIG_USE_NATIVE_BACKEND_ARITH: true + MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202: true MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/monolithic_build_multilevel_native/multilevel_config.h + - path: examples/monolithic_build_multilevel_native/mlkem_native/mlkem_native_config.h description: "Multilevel monolithic build config with native backends" defines: + MLK_CONFIG_MULTILEVEL_BUILD: true MLK_CONFIG_NAMESPACE_PREFIX: mlkem MLK_CONFIG_USE_NATIVE_BACKEND_ARITH: true MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202: true @@ -365,7 +347,7 @@ configs: #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" #include "test_only_rng/notrandombytes.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { @@ -373,7 +355,7 @@ configs: } #endif /* !__ASSEMBLER__ */ - - path: examples/custom_backend/mlkem_native/custom_config.h + - path: examples/custom_backend/mlkem_native/mlkem_native_config.h description: "Custom backend config with tiny SHA3" defines: MLK_CONFIG_PARAMETER_SET: @@ -387,9 +369,29 @@ configs: MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" - - path: examples/basic_deterministic/mlkem_native/custom_no_randomized_config.h - description: "Config without randomized API" + - path: examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h + description: "Configuration for custom FIPS202 implementation" + defines: + MLK_CONFIG_NAMESPACE_PREFIX: mlkem + MLK_CONFIG_FIPS202_CUSTOM_HEADER: "\"../custom_fips202/fips202.h\"" + MLK_CONFIG_FIPS202X4_CUSTOM_HEADER: "\"../custom_fips202/fips202x4.h\"" + MLK_CONFIG_FILE: + comment: "/* No need to set this -- we _are_ already in a custom config */" + + - path: examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h + description: "Configuration for custom serial FIPS202 implementation" defines: + MLK_CONFIG_NAMESPACE_PREFIX: mlkem + MLK_CONFIG_SERIAL_FIPS202_ONLY: true + MLK_CONFIG_FIPS202_CUSTOM_HEADER: "\"../custom_fips202/fips202.h\"" + MLK_CONFIG_FIPS202X4_CUSTOM_HEADER: "\"../custom_fips202/fips202x4.h\"" + MLK_CONFIG_FILE: + comment: "/* No need to set this -- we _are_ already in a custom config */" + + - path: examples/basic_deterministic/mlkem_native/mlkem_native_config.h + description: "Configuration for deterministic-only build of mlkem-native" + defines: + MLK_CONFIG_NAMESPACE_PREFIX: mlkem MLK_CONFIG_NO_RANDOMIZED_API: true MLK_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" diff --git a/test/custom_memcpy_config.h b/test/custom_memcpy_config.h index 6fb22ce776..8714019287 100644 --- a/test/custom_memcpy_config.h +++ b/test/custom_memcpy_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with custom memcpy * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_MEMCPY */ @@ -44,6 +44,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -75,11 +80,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -88,6 +90,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -325,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -411,7 +504,7 @@ static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -431,21 +524,6 @@ static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) *****************************************************************************/ /* #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 * @@ -495,24 +573,6 @@ static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -542,7 +602,7 @@ static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -574,6 +634,8 @@ static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_memset_config.h b/test/custom_memset_config.h index 95ef4af7d7..07ac537cd0 100644 --- a/test/custom_memset_config.h +++ b/test/custom_memset_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with custom memset * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_MEMSET */ @@ -44,6 +44,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -75,11 +80,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -88,6 +90,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -325,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -380,7 +473,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -430,21 +523,6 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #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 * @@ -494,24 +572,6 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -541,7 +601,7 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -573,6 +633,8 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_native_capability_config_0.h b/test/custom_native_capability_config_0.h index 56392480a9..4d78b4c27e 100644 --- a/test/custom_native_capability_config_0.h +++ b/test/custom_native_capability_config_0.h @@ -28,8 +28,8 @@ * Test configuration: Test configuration with custom capability function * returning 0 * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_CAPABILITY_FUNC */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -384,7 +477,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -407,7 +500,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -427,21 +520,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #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 * @@ -491,24 +569,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -538,7 +598,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -570,6 +630,8 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_native_capability_config_1.h b/test/custom_native_capability_config_1.h index 85a95e5edb..59df235ba8 100644 --- a/test/custom_native_capability_config_1.h +++ b/test/custom_native_capability_config_1.h @@ -28,8 +28,8 @@ * Test configuration: Test configuration with custom capability function * returning 1 * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_CAPABILITY_FUNC */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -383,7 +476,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -406,7 +499,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -426,21 +519,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #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 * @@ -490,24 +568,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -537,7 +597,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -569,6 +629,8 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_native_capability_config_CPUID_AVX2.h b/test/custom_native_capability_config_CPUID_AVX2.h index 88aef818b7..013e3ddfcf 100644 --- a/test/custom_native_capability_config_CPUID_AVX2.h +++ b/test/custom_native_capability_config_CPUID_AVX2.h @@ -28,8 +28,8 @@ * Test configuration: Test configuration with CPUID-based AVX2 capability * detection * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_CAPABILITY_FUNC */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -415,7 +508,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -438,7 +531,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -458,21 +551,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #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 * @@ -522,24 +600,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -569,7 +629,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -601,6 +661,8 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_native_capability_config_ID_AA64PFR1_EL1.h b/test/custom_native_capability_config_ID_AA64PFR1_EL1.h index 8d16cd9d2a..4df7adca4b 100644 --- a/test/custom_native_capability_config_ID_AA64PFR1_EL1.h +++ b/test/custom_native_capability_config_ID_AA64PFR1_EL1.h @@ -28,8 +28,8 @@ * Test configuration: Test configuration with ARM system register capability * detection * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_CAPABILITY_FUNC */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -402,7 +495,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -425,7 +518,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -445,21 +538,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #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 * @@ -509,24 +587,6 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -556,7 +616,7 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -588,6 +648,8 @@ static MLK_INLINE int mlk_sys_check_capability(mlk_sys_cap cap) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_randombytes_config.h b/test/custom_randombytes_config.h index df55865c36..bb43712195 100644 --- a/test/custom_randombytes_config.h +++ b/test/custom_randombytes_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with custom randombytes * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_RANDOMBYTES */ @@ -44,6 +44,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -75,11 +80,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -88,6 +90,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -381,7 +474,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -404,7 +497,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -424,21 +517,6 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #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 * @@ -488,24 +566,6 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -535,7 +595,7 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -567,6 +627,8 @@ static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_stdlib_config.h b/test/custom_stdlib_config.h index df49d950ad..ba2094c168 100644 --- a/test/custom_stdlib_config.h +++ b/test/custom_stdlib_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with custom stdlib functions * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_MEMCPY * - MLK_CONFIG_CUSTOM_MEMSET */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -300,7 +393,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -326,7 +419,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -439,21 +532,6 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #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 * @@ -503,24 +581,6 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -550,7 +610,7 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -582,6 +642,8 @@ static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/custom_zeroize_config.h b/test/custom_zeroize_config.h index 0d90887de3..91f67eeeb6 100644 --- a/test/custom_zeroize_config.h +++ b/test/custom_zeroize_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with custom zeroize * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_CUSTOM_ZEROIZE */ @@ -44,6 +44,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -75,11 +80,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -88,6 +90,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -326,7 +419,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -381,7 +474,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -404,7 +497,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -424,21 +517,6 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #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 * @@ -488,24 +566,6 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -535,7 +595,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -567,6 +627,8 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/mk/components.mk b/test/mk/components.mk index d03ab9656e..e75644f400 100644 --- a/test/mk/components.mk +++ b/test/mk/components.mk @@ -34,7 +34,7 @@ MLKEM1024_UNIT_OBJS = $(call MAKE_OBJS,$(MLKEM1024_DIR)/unit,$(SOURCES) $(FIPS20 $(MLKEM1024_UNIT_OBJS): CFLAGS += -DMLK_CONFIG_PARAMETER_SET=1024 -DMLK_STATIC_TESTABLE= -Wno-missing-prototypes - +CFLAGS += -Imlkem $(BUILD_DIR)/libmlkem512.a: $(MLKEM512_OBJS) $(BUILD_DIR)/libmlkem768.a: $(MLKEM768_OBJS) diff --git a/test/no_asm_config.h b/test/no_asm_config.h index 42cc204481..cb7cc1c6f7 100644 --- a/test/no_asm_config.h +++ b/test/no_asm_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with no assembly code * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_NO_ASM * - MLK_CONFIG_CUSTOM_ZEROIZE */ @@ -45,6 +45,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -76,11 +81,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -89,6 +91,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -108,6 +199,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -129,6 +221,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -327,7 +420,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -382,7 +475,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -405,7 +498,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -425,21 +518,6 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #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 * @@ -489,24 +567,6 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -536,7 +596,7 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -568,6 +628,8 @@ static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define diff --git a/test/serial_fips202_config.h b/test/serial_fips202_config.h index 8bac43e5a2..f0f27b1d2a 100644 --- a/test/serial_fips202_config.h +++ b/test/serial_fips202_config.h @@ -27,8 +27,8 @@ /* * Test configuration: Test configuration with serial FIPS202 only * - * This configuration differs from the default mlkem/src/config.h in the - * following places: + * This configuration differs from the default mlkem/mlkem_native_config.h in + * the following places: * - MLK_CONFIG_SERIAL_FIPS202_ONLY */ @@ -44,6 +44,11 @@ * - MLK_CONFIG_PARAMETER_SET=768 corresponds to ML-KEM-768 * - MLK_CONFIG_PARAMETER_SET=1024 corresponds to ML-KEM-1024 * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLK_CONFIG_MULTILEVEL_BUILD. + * See MLK_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * * This can also be set using CFLAGS. * *****************************************************************************/ @@ -75,11 +80,8 @@ * * 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). + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (512/768/1024). * * This can also be set using CFLAGS. * @@ -88,6 +90,95 @@ #define MLK_CONFIG_NAMESPACE_PREFIX MLK_DEFAULT_NAMESPACE_PREFIX #endif +/****************************************************************************** + * Name: MLK_CONFIG_MULTILEVEL_BUILD + * + * Description: Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLK_CONFIG_MULTILEVEL_BUILD */ + +/****************************************************************************** + * 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_NO_RANDOMIZED_API + * + * Description: If this option is set, mlkem-native will be built without the + * randomized API functions (crypto_kem_keypair and + * crypto_kem_enc). + * This allows users to build mlkem-native without providing a + * randombytes() implementation if they only need the + * deterministic API + * (crypto_kem_keypair_derand, crypto_kem_enc_derand, + * crypto_kem_dec). + * + * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires crypto_kem_enc(). + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLK_CONFIG_NO_SUPERCOP + * + * Description: By default, mlkem_native.h exposes the mlkem-native API in the + * SUPERCOP naming convention (crypto_kem_xxx). If you don't need + * this, set MLK_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLK_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLK_CONFIG_CONSTANTS_ONLY + * + * Description: If you only need the size constants (MLKEM_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLK_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mlkem_native.h, not + * the implementation. + * + *****************************************************************************/ +/* #define MLK_CONFIG_CONSTANTS_ONLY */ + +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mlkem_native.h. + * + *****************************************************************************/ + +#if defined(MLK_BUILD_INTERNAL) /****************************************************************************** * Name: MLK_CONFIG_MULTILEVEL_WITH_SHARED * @@ -107,6 +198,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -128,6 +220,7 @@ * 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. + * MLK_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -299,7 +392,7 @@ /* #define MLK_CONFIG_CUSTOM_ZEROIZE #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_zeroize(void *ptr, size_t len) { ... your implementation ... @@ -325,7 +418,7 @@ /* #define MLK_CONFIG_CUSTOM_RANDOMBYTES #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len) { ... your implementation ... @@ -380,7 +473,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMCPY #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) { ... your implementation ... @@ -403,7 +496,7 @@ /* #define MLK_CONFIG_CUSTOM_MEMSET #if !defined(__ASSEMBLER__) #include - #include "sys.h" + #include "src/sys.h" static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) { ... your implementation ... @@ -423,21 +516,6 @@ *****************************************************************************/ /* #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 * @@ -487,24 +565,6 @@ *****************************************************************************/ /* #define MLk_CONFIG_NO_ASM_VALUE_BARRIER */ -/****************************************************************************** - * Name: MLK_CONFIG_NO_RANDOMIZED_API - * - * Description: If this option is set, mlkem-native will be built without the - * randomized API functions (crypto_kem_keypair and - * crypto_kem_enc). - * This allows users to build mlkem-native without providing a - * randombytes() implementation if they only need the - * deterministic API - * (crypto_kem_keypair_derand, crypto_kem_enc_derand, - * crypto_kem_dec). - * - * NOTE: This option is incompatible with MLK_CONFIG_KEYGEN_PCT - * as the current PCT implementation requires crypto_kem_enc(). - * - *****************************************************************************/ -/* #define MLK_CONFIG_NO_RANDOMIZED_API */ - /****************************************************************************** * Name: MLK_CONFIG_KEYGEN_PCT * @@ -534,7 +594,7 @@ *****************************************************************************/ /* #define MLK_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) - #include "sys.h" + #include "src/sys.h" static MLK_INLINE int mlk_break_pct(void) { ... return 0/1 depending on whether PCT should be broken ... @@ -566,6 +626,8 @@ /************************* Config internals ********************************/ +#endif /* MLK_BUILD_INTERNAL */ + /* Default namespace * * Don't change this. If you need a different namespace, re-define