Add bring_your_own_fips202 example

This adds an example demonstrating how mldsa-native can be used with a custom
FIPS202 implementation.
We use https://github.com/mjosaarinen/tiny_sha3 for demonstration.

The example closely follows
https://github.com/pq-code-package/mlkem-native/tree/main/examples/bring_your_own_fips202

Resolves #556

Signed-off-by: Matthias J. Kannwischer <[email protected]>

Author: mkannwischer

BIBLIOGRAPHY.md

@@ -34,6 +34,7 @@ source code and documentation.
   - National Institute of Standards and Technology
 * URL: https://csrc.nist.gov/pubs/fips/202/final
 * Referenced from:
+  - [FIPS202.md](FIPS202.md)
   - [README.md](README.md)
 
 ### `FIPS204`
@@ -243,9 +244,22 @@ source code and documentation.
 * Referenced from:
   - [examples/basic/test_only_rng/notrandombytes.c](examples/basic/test_only_rng/notrandombytes.c)
   - [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)
   - [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
   - [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
 
+### `tiny_sha3`
+
+* tiny_sha3
+* Author(s):
+  - Markku-Juhani O. Saarinen
+* URL: https://github.com/mjosaarinen/tiny_sha3
+* Referenced from:
+  - [FIPS202.md](FIPS202.md)
+  - [README.md](README.md)
+  - [examples/bring_your_own_fips202/README.md](examples/bring_your_own_fips202/README.md)
+
 ### `tweetfips`
 
 * 'tweetfips202' FIPS202 implementation

BIBLIOGRAPHY.yml

@@ -106,6 +106,11 @@
   - Schwabe, Peter
   url: https://keccak.team/2015/tweetfips202.html
 
+- id: tiny_sha3
+  name: tiny_sha3
+  author: Saarinen, Markku-Juhani O.
+  url: https://github.com/mjosaarinen/tiny_sha3
+
 - id: libmceliece
   name: libmceliece implementation of Classic McEliece
   author:

FIPS202.md

@@ -0,0 +1,41 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Replacing FIPS-202
+
+If your library has a FIPS-202[^FIPS202] implementation, you can use it instead of the one shipped with mldsa-native.
+
+1. Replace `mldsa/fips202/*` by your own FIPS-202 implementation.
+2. Provide replacements for the headers [`mldsa/fips202/fips202.h`](mldsa/fips202/fips202.h) and [`mldsa/fips202/fips202x4.h`](mldsa/fips202/fips202x4.h) and the
+functionalities specified therein:
+  * Structure definitions for `mld_shake128ctx`, `mld_shake256ctx`, `mld_shake128x4ctx`, and `mld_shake256x4ctx`
+  * `mld_shake128_init()`: Initialize a SHAKE-128 context
+  * `mld_shake128_absorb()`: Absorb data into a SHAKE-128 context (can be called multiple times)
+  * `mld_shake128_finalize()`: Finalize the absorb phase of a SHAKE-128 context
+  * `mld_shake128_squeeze()`: Squeeze data from a SHAKE-128 context (can be called multiple times)
+  * `mld_shake128_release()`: Release and securely zero a SHAKE-128 context after use
+  * `mld_shake256_init()`: Initialize a SHAKE-256 context
+  * `mld_shake256_absorb()`: Absorb data into a SHAKE-256 context (can be called multiple times)
+  * `mld_shake256_finalize()`: Finalize the absorb phase of a SHAKE-256 context
+  * `mld_shake256_squeeze()`: Squeeze data from a SHAKE-256 context (can be called multiple times)
+  * `mld_shake256_release()`: Release and securely zero a SHAKE-256 context after use
+  * `mld_shake256()`: One-shot SHAKE-256 operation
+  * `mld_shake128x4_init()`: Initialize a 4x-batched SHAKE-128 context
+  * `mld_shake128x4_absorb_once()`: Initialize and absorb into a 4x-batched SHAKE-128 context in one step
+  * `mld_shake128x4_squeezeblocks()`: Squeeze blocks from a 4x-batched SHAKE-128 context
+  * `mld_shake128x4_release()`: Release a 4x-batched SHAKE-128 context after use
+  * `mld_shake256x4_init()`: Initialize a 4x-batched SHAKE-256 context
+  * `mld_shake256x4_absorb_once()`: Initialize and absorb into a 4x-batched SHAKE-256 context in one step
+  * `mld_shake256x4_squeezeblocks()`: Squeeze blocks from a 4x-batched SHAKE-256 context
+  * `mld_shake256x4_release()`: Release a 4x-batched SHAKE-256 context after use
+
+See [`mldsa/fips202/fips202.h`](mldsa/fips202/fips202.h) and [`mldsa/fips202/fips202x4.h`](mldsa/fips202/fips202x4.h) for more details. Note that the structure
+definitions may differ from those shipped with mldsa-native.
+
+## Example
+
+See [`examples/bring_your_own_fips202/`](examples/bring_your_own_fips202/) for an example how to use a custom FIPS-202
+implementation with tiny_sha3[^tiny_sha3].
+
+<!--- bibliography --->
+[^FIPS202]: National Institute of Standards and Technology: FIPS202 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions, [https://csrc.nist.gov/pubs/fips/202/final](https://csrc.nist.gov/pubs/fips/202/final)
+[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

README.md

@@ -62,10 +62,11 @@ offers backends for C, AArch64, and x86_64 - if you'd like contribute new backen
 
 Once mldsa-native reaches production readiness, you will be able to import [mldsa](mldsa) into your project's source tree and build using your preferred build system. The build system provided in this repository is for development purposes only.
 
-### Will I be able to bring my own FIPS-202?
+### Can I bring my own FIPS-202?
 
 mldsa-native relies on and comes with an implementation of FIPS-202[^FIPS202]. If your library has its own FIPS-202 implementation, you
-can use it instead of the one shipped with mldsa-native.
+can use it instead of the one shipped with mldsa-native. See [FIPS202.md](FIPS202.md), and [examples/bring_your_own_fips202](examples/bring_your_own_fips202)
+for an example using tiny_sha3[^tiny_sha3].
 
 ### Will I need to use the assembly backends?
 
@@ -124,3 +125,4 @@ through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R).
 [^NIST_FAQ]: National Institute of Standards and Technology: Post-Quantum Cryptography FAQs, [https://csrc.nist.gov/Projects/post-quantum-cryptography/faqs#Rdc7](https://csrc.nist.gov/Projects/post-quantum-cryptography/faqs#Rdc7)
 [^NIST_FIPS204_SEC6]: National Institute of Standards and Technology: FIPS 204 Section 6 Guidance, [https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf](https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf)
 [^REF]: Bai, Ducas, Kiltz, Lepoint, Lyubashevsky, Schwabe, Seiler, Stehlé: CRYSTALS-Dilithium reference implementation, [https://github.com/pq-crystals/dilithium/tree/master/ref](https://github.com/pq-crystals/dilithium/tree/master/ref)
+[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

examples/basic/Makefile

@@ -1,4 +1,5 @@
-# (SPDX-License-Identifier: CC-BY-4.0)
+# Copyright (c) The mldsa-native project authors
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
 
 .PHONY: build run clean size
 .DEFAULT_GOAL := all

examples/bring_your_own_fips202/.gitignore

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

examples/bring_your_own_fips202/Makefile

@@ -0,0 +1,116 @@
+# Copyright (c) The mldsa-native project authors
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+.PHONY: build run clean size
+.DEFAULT_GOAL := all
+
+# Append cross-prefix for cross compilation
+# Remove or ignore for native builds
+CC  ?= gcc
+SIZE ?= size
+# When called from the root Makefile, CROSS_PREFIX has already been added here
+ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
+CC  := $(CROSS_PREFIX)$(CC)
+endif
+
+ifeq (,$(findstring $(CROSS_PREFIX),$(SIZE)))
+SIZE  := $(CROSS_PREFIX)$(SIZE)
+endif
+
+# Part A:
+#
+# mldsa-native source and header files
+# Note: We exclude the fips202/ directory since we're providing our own
+MLD_SOURCE=$(wildcard              \
+	../../mldsa/*.c                \
+	../../mldsa/native/**/*.c      \
+	../../mldsa/native/**/**/*.c)
+
+INC=-I../../mldsa/ -Icustom_fips202/
+
+# Part B:
+#
+# Custom FIPS-202 implementation
+#
+# At present, this must be located in a directory named "fips202".
+# This limitation will be lifted in the future.
+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)
+
+BUILD_DIR=build
+BIN=test_binary
+
+CFLAGS := \
+	-Wall \
+	-Wextra \
+	-Werror \
+	-Wmissing-prototypes \
+	-Wshadow \
+	-Wpointer-arith \
+	-Wredundant-decls \
+	-Wconversion \
+	-Wsign-conversion \
+	-Wno-long-long \
+	-Wno-unknown-pragmas \
+	-Wno-unused-command-line-argument \
+	-fomit-frame-pointer \
+	-std=c99 \
+	-pedantic \
+	-MMD \
+	-O3 \
+	$(CFLAGS)
+CFLAGS += -DMLD_CONFIG_FIPS202_CUSTOM_HEADER="\"fips202.h\""
+CFLAGS += -DMLD_CONFIG_FIPS202X4_CUSTOM_HEADER="\"fips202x4.h\""
+CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
+
+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 size
+
+build: $(BINARIES_FULL)
+
+run: $(BINARIES_FULL)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
+
+size: build
+	@echo "=== Size info for $(BINARY_NAME_FULL_44) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_44)
+	@echo "=== Size info for $(BINARY_NAME_FULL_65) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_65)
+	@echo "=== Size info for $(BINARY_NAME_FULL_87) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_87)
+
+clean:
+	rm -rf $(BUILD_DIR)

examples/bring_your_own_fips202/README.md

@@ -0,0 +1,40 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Bring your own FIPS-202
+
+This directory contains a minimal example for how to use mldsa-native as a code package, with a custom FIPS-202
+implementation. We use tiny_sha3[^tiny_sha3] as an example.
+
+## 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/`](../../mldsa)
+2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/randombytes.h).
+3. A custom FIPS-202 with `fips202.h` and `fips202x4.h` headers compatible with
+   [`mldsa/fips202/fips202.h`](../../mldsa/fips202/fips202.h) and [`mldsa/fips202/fips202x4.h`](../../mldsa/fips202/fips202x4.h).
+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`.
+
+## Custom FIPS-202 Implementation
+
+This example uses tiny_sha3 as the underlying Keccak/SHA3 implementation. The wrapper headers in `custom_fips202/`
+adapt the tiny_sha3 API to match the API expected by mldsa-native.
+
+Note that the `fips202x4.h` implementation provided here is a simple serial implementation that does not provide
+any performance benefits from parallelization. For production use, consider using an optimized parallel implementation.
+
+## Verification
+
+This example uses the same test vectors as the basic example (via a symlink to `expected_signatures.h`) and verifies
+that the custom FIPS-202 implementation produces identical results to the default implementation. This ensures that
+the wrapper is correctly implementing the required API.
+
+<!--- bibliography --->
+[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)