Add MLD_CONFIG_SERIAL_FIPS202_ONLY option

.github/actions/config-variations/action.yml

@@ -7,7 +7,7 @@ inputs:
     description: 'GitHub token'
     required: true
   tests:
-    description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, custom-zeroize, no-asm, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib'
+    description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, custom-zeroize, no-asm, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib, serial-fips202'
     required: false
     default: 'all'
   opt:
@@ -123,3 +123,16 @@ runs:
         acvp: true
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
+    - name: "Serial FIPS202 (no batched Keccak)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'serial-fips202') }}
+      uses: ./.github/actions/multi-functest
+      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"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        opt: ${{ inputs.opt }}
+        examples: false # Some examples use a custom config themselves

BIBLIOGRAPHY.md

@@ -30,6 +30,7 @@ source code and documentation.
   - [test/custom_stdlib_config.h](test/custom_stdlib_config.h)
   - [test/custom_zeroize_config.h](test/custom_zeroize_config.h)
   - [test/no_asm_config.h](test/no_asm_config.h)
+  - [test/serial_fips202_config.h](test/serial_fips202_config.h)
 
 ### `FIPS202`
 
@@ -72,6 +73,7 @@ source code and documentation.
   - [test/custom_stdlib_config.h](test/custom_stdlib_config.h)
   - [test/custom_zeroize_config.h](test/custom_zeroize_config.h)
   - [test/no_asm_config.h](test/no_asm_config.h)
+  - [test/serial_fips202_config.h](test/serial_fips202_config.h)
 
 ### `HYBRID`
 
@@ -310,6 +312,8 @@ source code and documentation.
   - [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
   - [examples/bring_your_own_fips202/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202/test_only_rng/notrandombytes.c)
   - [examples/bring_your_own_fips202/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202/test_only_rng/notrandombytes.h)
+  - [examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c)
+  - [examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.h)
   - [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
   - [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
 
@@ -323,6 +327,8 @@ source code and documentation.
   - [FIPS202.md](FIPS202.md)
   - [README.md](README.md)
   - [examples/bring_your_own_fips202/README.md](examples/bring_your_own_fips202/README.md)
+  - [examples/bring_your_own_fips202_static/README.md](examples/bring_your_own_fips202_static/README.md)
+  - [examples/bring_your_own_fips202_static/custom_fips202/README.md](examples/bring_your_own_fips202_static/custom_fips202/README.md)
 
 ### `tweetfips`
 

examples/bring_your_own_fips202_static/.gitignore

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+build/
+*.d

examples/bring_your_own_fips202_static/Makefile

@@ -0,0 +1,125 @@
+# Copyright (c) The mlkem-native project authors
+# Copyright (c) The mldsa-native project authors
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+.PHONY: build run clean
+.DEFAULT_GOAL := all
+
+CC  ?= gcc
+
+# Adjust CFLAGS if needed
+CFLAGS := \
+	-Wall \
+	-Wextra \
+	-Werror=unused-result \
+	-Wpedantic \
+	-Werror \
+	-Wmissing-prototypes \
+	-Wshadow \
+	-Wpointer-arith \
+	-Wredundant-decls \
+	-Wconversion \
+	-Wsign-conversion \
+	-Wno-long-long \
+	-Wno-unknown-pragmas \
+	-Wno-unused-command-line-argument \
+	-O3 \
+	-fomit-frame-pointer \
+	-std=c99 \
+	-pedantic \
+	-MMD \
+	$(CFLAGS)
+
+# If you want to use the native backends, the compiler needs to know about
+# the target architecture. Here, we import the default host detection from
+# mldsa-native's tests, but you can write your own or specialize accordingly.
+AUTO ?= 1
+include auto.mk
+
+# The following only concerns the cross-compilation tests.
+# You can likely ignore the following for your application.
+#
+# Append cross-prefix for cross compilation
+# When called from the root Makefile, CROSS_PREFIX has already been added here
+ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
+CC  := $(CROSS_PREFIX)$(CC)
+endif
+
+# Part A:
+#
+# mldsa-native source and header files
+#
+# 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/*.c \
+	mldsa_native/**/*.c \
+	mldsa_native/**/**/*.c \
+	mldsa_native/**/**/**/*.c)
+
+INC=-Imldsa_native/
+
+# Part B:
+#
+# Custom FIPS-202 implementation
+FIPS202_SOURCE=custom_fips202/tiny_sha3/sha3.c
+
+# Part C:
+#
+# Random number generator
+#
+# !!! WARNING !!!
+#
+# The randombytes() implementation used here is for TESTING ONLY.
+# You MUST NOT use this implementation outside of testing.
+#
+# !!! WARNING !!!
+RNG_SOURCE=$(wildcard test_only_rng/*.c)
+
+# Part D:
+#
+# Your application source code
+APP_SOURCE=$(wildcard *.c)
+
+ALL_SOURCE=$(MLD_SOURCE) $(FIPS202_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
+
+#
+# Configuration adjustments
+#
+
+# Pick prefix
+CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
+# Tell mldsa-native to use serial-FIPS202 only
+CFLAGS += -DMLD_CONFIG_SERIAL_FIPS202_ONLY
+# Tell mldsa-native where to find the header for the custom FIPS202
+CFLAGS += -DMLD_CONFIG_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\""
+
+BUILD_DIR=build
+BIN=test_binary
+
+BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
+BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
+BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
+BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
+
+$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
+$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
+$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
+
+$(BINARIES_FULL): $(ALL_SOURCE)
+	echo "$@"
+	mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@
+
+all: build
+
+build: $(BINARIES_FULL)
+
+run: $(BINARIES_FULL)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
+
+clean:
+	rm -rf $(BUILD_DIR)

examples/bring_your_own_fips202_static/README.md

@@ -0,0 +1,35 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Bring your own FIPS-202 (Static State Variant)
+
+This directory contains a minimal example for how to use mldsa-native with external FIPS-202
+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
+`MLD_CONFIG_SERIAL_FIPS202_ONLY`.
+
+**WARNING:** This example is EXPECTED TO PRODUCE INCORRECT RESULTS because ML-DSA requires
+multiple independent FIPS-202 contexts to be active simultaneously. This example demonstrates
+what happens when only a single global state is available.
+
+## Components
+
+An application using mldsa-native with a custom FIPS-202 implementation needs the following:
+
+1. Arithmetic part of the mldsa-native source tree: [`mldsa/src/`](../../mldsa/src)
+2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
+3. A custom FIPS-202 with `fips202.h` header compatible with [`mldsa/fips202/fips202.h`](../../mldsa/src/fips202/fips202.h).
+   With `MLD_CONFIG_SERIAL_FIPS202_ONLY`, the FIPS-202x4 parallel API is not used.
+4. The application source code
+
+**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
+outside of testing.
+
+## Usage
+
+Build this example with `make build`, run with `make run`.
+
+You should see verification failures, which is the expected behavior demonstrating that a single
+global FIPS-202 state is insufficient for ML-DSA.
+
+<!--- bibliography --->
+[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

examples/bring_your_own_fips202_static/auto.mk

@@ -0,0 +1 @@
+../../test/mk/auto.mk

examples/bring_your_own_fips202_static/custom_fips202/README.md

@@ -0,0 +1,43 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+# Custom FIPS-202 Implementation (Static Global State)
+
+This directory contains a custom FIPS-202 implementation that wraps `tiny_sha3`[^tiny_sha3]
+using a **single global static state** for all operations.
+
+## Purpose
+
+This example demonstrates how mldsa-native can integrate with FIPS-202 implementations
+that maintain a single global state, such as:
+- Hardware accelerators with a single Keccak engine
+- Embedded systems with limited memory
+- Libraries that don't support multiple independent contexts
+
+## How It Works
+
+Instead of storing the Keccak state in each context structure, this implementation:
+
+1. Uses a **static global state** for SHA-3/SHAKE operations
+2. Provides **dummy context structures** that are ignored by the API functions
+3. Includes **state machine assertions** to verify correct API usage
+## Configuration
+
+Enable this mode with:
+```c
+#define MLD_CONFIG_FIPS202_CUSTOM_HEADER "\"fips202.h\""
+#define MLD_CONFIG_SERIAL_FIPS202_ONLY
+```
+
+The `MLD_CONFIG_SERIAL_FIPS202_ONLY` flag tells mldsa-native to avoid
+using the parallel x4 API.
+
+## Files
+
+- `fips202.h` - Custom FIPS-202 wrapper with static global state
+- `tiny_sha3/` - Symlink to the tiny_sha3 implementation
+- `README.md` - This file
+
+[^tiny_sha3]: https://github.com/mjosaarinen/tiny_sha3
+
+<!--- bibliography --->
+[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)