Use a single configuration file for internal and external headers

.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

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)

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
 

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.

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"
 

examples/basic/mlkem_native/mlkem_native_config.h

@@ -0,0 +1 @@
+../../../mlkem/mlkem_native_config.h

examples/basic/mlkem_native/src

@@ -0,0 +1 @@
+../../../mlkem/src

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

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
+```

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 */
 

examples/basic_deterministic/mlkem_native/mlkem_native.h

@@ -0,0 +1 @@
+../../../mlkem/mlkem_native.h