Port: 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='-DMLD_CONFIG_FILE=\"../../test/break_pct_config.h\"' make func -j4
+        CFLAGS='-Itest -DMLD_CONFIG_FILE=\"break_pct_config.h\"' make func -j4
         # PCT breakage is done at runtime via MLD_BREAK_PCT
         make run_func                 # Should be OK
         MLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_zeroize_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_1.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_native_capability_config_0.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_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 -DMLD_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 -DMLD_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 -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/no_asm_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/serial_fips202_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_randombytes_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_memcpy_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_memset_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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 -DMLD_CONFIG_FILE=\\\\\\\"../../test/custom_stdlib_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_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

@@ -23,20 +23,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/mldsa_native/custom_no_randomized_config.h](examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h)
-  - [examples/custom_backend/mldsa_native/custom_config.h](examples/custom_backend/mldsa_native/custom_config.h)
-  - [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
-  - [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
-  - [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.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_44.h](examples/monolithic_build_native/config_44.h)
-  - [examples/monolithic_build_native/config_65.h](examples/monolithic_build_native/config_65.h)
-  - [examples/monolithic_build_native/config_87.h](examples/monolithic_build_native/config_87.h)
+  - [examples/basic_deterministic/mldsa_native/mldsa_native_config.h](examples/basic_deterministic/mldsa_native/mldsa_native_config.h)
+  - [examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h)
+  - [examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h)
+  - [examples/custom_backend/mldsa_native/mldsa_native_config.h](examples/custom_backend/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build/mldsa_native/mldsa_native_config.h](examples/monolithic_build/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h](examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_native/mldsa_native/mldsa_native_config.h)
+  - [examples/multilevel_build/mldsa_native/mldsa_native_config.h](examples/multilevel_build/mldsa_native/mldsa_native_config.h)
+  - [examples/multilevel_build_native/mldsa_native/mldsa_native_config.h](examples/multilevel_build_native/mldsa_native/mldsa_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)
-  - [mldsa/src/config.h](mldsa/src/config.h)
+  - [mldsa/mldsa_native_config.h](mldsa/mldsa_native_config.h)
   - [mldsa/src/sign.c](mldsa/src/sign.c)
   - [test/break_pct_config.h](test/break_pct_config.h)
   - [test/custom_memcpy_config.h](test/custom_memcpy_config.h)
@@ -69,18 +69,18 @@ source code and documentation.
 * URL: https://csrc.nist.gov/pubs/fips/204/final
 * Referenced from:
   - [README.md](README.md)
-  - [examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h](examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h)
-  - [examples/custom_backend/mldsa_native/custom_config.h](examples/custom_backend/mldsa_native/custom_config.h)
-  - [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
-  - [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
-  - [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.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_44.h](examples/monolithic_build_native/config_44.h)
-  - [examples/monolithic_build_native/config_65.h](examples/monolithic_build_native/config_65.h)
-  - [examples/monolithic_build_native/config_87.h](examples/monolithic_build_native/config_87.h)
+  - [examples/basic_deterministic/mldsa_native/mldsa_native_config.h](examples/basic_deterministic/mldsa_native/mldsa_native_config.h)
+  - [examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h)
+  - [examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h)
+  - [examples/custom_backend/mldsa_native/mldsa_native_config.h](examples/custom_backend/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build/mldsa_native/mldsa_native_config.h](examples/monolithic_build/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h](examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h)
+  - [examples/monolithic_build_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_native/mldsa_native/mldsa_native_config.h)
+  - [examples/multilevel_build/mldsa_native/mldsa_native_config.h](examples/multilevel_build/mldsa_native/mldsa_native_config.h)
+  - [examples/multilevel_build_native/mldsa_native/mldsa_native_config.h](examples/multilevel_build_native/mldsa_native/mldsa_native_config.h)
   - [mldsa/mldsa_native.h](mldsa/mldsa_native.h)
-  - [mldsa/src/config.h](mldsa/src/config.h)
+  - [mldsa/mldsa_native_config.h](mldsa/mldsa_native_config.h)
   - [mldsa/src/ct.h](mldsa/src/ct.h)
   - [mldsa/src/fips202/fips202.c](mldsa/src/fips202/fips202.c)
   - [mldsa/src/fips202/fips202x4.c](mldsa/src/fips202/fips202x4.c)

examples/README.md

@@ -0,0 +1,54 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Usage examples
+
+This directory contains minimal examples demonstrating how you can use mldsa-native.
+
+## Basic
+
+See [basic](basic) for a basic example of how to build a single instance of mldsa-native.
+
+## Basic_deterministic
+
+See [basic_deterministic](basic_deterministic) for a basic example of how to build a single instance of mldsa-native without `randombytes()` implementation. This allows users to build mldsa-native using only the deterministic API when randomized functions are not required.
+## Multi-level build (C only)
+
+See [multilevel_build](multilevel_build) for an example of how to build one instance of mldsa-native per security level,
+in such a way that level-independent code is shared.
+
+## Multi-level build (with native code)
+
+See [multilevel_build_native](multilevel_build_native) for an example of how to build one instance of mldsa-native per
+security level, in such a way that level-independent code is shared, and leveraging the native backends.
+
+## Custom FIPS202 implementation
+
+See [bring_your_own_fips202](bring_your_own_fips202) for an example of how to use mldsa-native with your own FIPS-202
+implementation.
+
+## Custom FIPS202 implementation (static state variant)
+
+See [bring_your_own_fips202_static](bring_your_own_fips202_static) for an example of how to use mldsa-native with a
+custom FIPS-202 implementation using a static state. This variant demonstrates the serial-only FIPS-202 configuration
+(`MLD_CONFIG_SERIAL_FIPS202_ONLY`).
+
+## Custom config + custom FIPS-202 backend
+
+See [custom_backend](custom_backend) for an example of how to use mldsa-native with a custom configuration file and a
+custom FIPS-202 backend.
+
+## Monobuild (C only)
+
+See [monolithic_build](monolithic_build) for an example of how to build mldsa-native (with C backend) from a single
+auto-generated compilation unit.
+
+## Multi-level monobuild (C only)
+
+See [monolithic_build_multilevel](monolithic_build_multilevel) for an example of how to build all security levels of
+mldsa-native (with C backend) inside a single compilation unit, sharing the level-independent code.
+
+## Multi-level monobuild (with native code)
+
+See [monolithic_build_multilevel_native](monolithic_build_multilevel_native) for an example of how to build all security
+levels of mldsa-native inside a single compilation unit, sharing the level-independent code, while also linking in assembly
+from the native backends.

examples/basic/Makefile

@@ -55,13 +55,13 @@ endif
 # In this example, we compile the individual mldsa-native source files directly.
 # Alternatively, you can compile the 'monobuild' source file mldsa_native.c.
 # See examples/monolithic_build for that.
-MLD_SOURCE=$(wildcard					\
-	mldsa_native/mldsa/src/*.c				\
-	mldsa_native/mldsa/src/**/*.c			\
-	mldsa_native/mldsa/src/**/**/*.c		\
-	mldsa_native/mldsa/src/**/**/**/*.c)
+MLD_SOURCE=$(wildcard				\
+	mldsa_native/src/*.c			\
+	mldsa_native/src/**/*.c			\
+	mldsa_native/src/**/**/*.c		\
+	mldsa_native/src/**/**/**/*.c)
 
-INC=-Imldsa_native/mldsa/
+INC=-Imldsa_native
 
 # Part B:
 #

examples/basic/README.md

@@ -1,40 +1,38 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Building mldsa-native
+# Basic build
 
-This directory contains a minimal example for how to build mldsa-native.
+This directory contains a minimal example for how to build mldsa-native for a single security level.
 
-## Components
-
-An application using mldsa-native as-is needs to include the following components:
-
-1. mldsa-native source tree, including [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202).
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
-3. The application source code
+## Use Case
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+Use this approach when:
+- You need only one ML-DSA parameter set (44, 65, or 87)
+- You want to build the mldsa-native C files separately, not as a single compilation unit.
+- You're using C only, no native backends.
 
-## Usage
+## Components
 
-Build this example with `make build`, run with `make run`.
+1. mldsa-native source tree: [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202)
+2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h)
+3. Your application source code
 
-## What this example demonstrates
+## Configuration
 
-This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_PARAMETER_SET`: Security level (44, 65, or 87). Default is 65.
+- `MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mldsa` in this example.
 
-1. **Key Generation**: Generate a public/private key pair
-2. **Signing**: Sign a message with a private key and optional context
-3. **Signature Verification**: Verify a signature using the public key
-4. **Signed Messages**: Create and open signed messages (signature + message combined)
+To change the security level, modify `MLD_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS.
 
-The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
+## Usage
 
-## Parameter Sets
+```bash
+make build   # Build the example
+make run     # Run the example
+```
 
-ML-DSA supports three parameter sets:
-- **ML-DSA-44**
-- **ML-DSA-65**
-- **ML-DSA-87**
+## Warning
 
-The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.
+The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
+You MUST provide a cryptographically secure RNG for production use.