Skip to content

Commit 705e6d9

Browse files
mkannwischermkannwischer
committed
Add example for serial-only FIPS202 with global state
This commit adds 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, the example demonstrates the use of the serial-only FIPS202 configuration `MLD_CONFIG_SERIAL_FIPS202_ONLY`. Port of pq-code-package/mlkem-native#1237 Signed-off-by: Matthias J. Kannwischer <[email protected]>
1 parent 63a9895 commit 705e6d9

File tree

12 files changed

+718
-2
lines changed

12 files changed

+718
-2
lines changed

‎BIBLIOGRAPHY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,8 @@ source code and documentation.
248248
- [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
249249
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202/test_only_rng/notrandombytes.c)
250250
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202/test_only_rng/notrandombytes.h)
251+
- [examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c)
252+
- [examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.h)
251253
- [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
252254
- [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
253255

@@ -261,6 +263,8 @@ source code and documentation.
261263
- [FIPS202.md](FIPS202.md)
262264
- [README.md](README.md)
263265
- [examples/bring_your_own_fips202/README.md](examples/bring_your_own_fips202/README.md)
266+
- [examples/bring_your_own_fips202_static/README.md](examples/bring_your_own_fips202_static/README.md)
267+
- [examples/bring_your_own_fips202_static/custom_fips202/README.md](examples/bring_your_own_fips202_static/custom_fips202/README.md)
264268

265269
### `tweetfips`
266270

‎examples/bring_your_own_fips202_static/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
2+
3+
build/
4+
*.d

‎examples/bring_your_own_fips202_static/Makefile‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Copyright (c) The mlkem-native project authors
2+
# Copyright (c) The mldsa-native project authors
3+
# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
4+
5+
.PHONY: build run clean
6+
.DEFAULT_GOAL := all
7+
8+
CC ?= gcc
9+
10+
# Adjust CFLAGS if needed
11+
CFLAGS := \
12+
-Wall \
13+
-Wextra \
14+
-Werror=unused-result \
15+
-Wpedantic \
16+
-Werror \
17+
-Wmissing-prototypes \
18+
-Wshadow \
19+
-Wpointer-arith \
20+
-Wredundant-decls \
21+
-Wconversion \
22+
-Wsign-conversion \
23+
-Wno-long-long \
24+
-Wno-unknown-pragmas \
25+
-Wno-unused-command-line-argument \
26+
-O3 \
27+
-fomit-frame-pointer \
28+
-std=c99 \
29+
-pedantic \
30+
-MMD \
31+
$(CFLAGS)
32+
33+
# If you want to use the native backends, the compiler needs to know about
34+
# the target architecture. Here, we import the default host detection from
35+
# mldsa-native's tests, but you can write your own or specialize accordingly.
36+
AUTO ?= 1
37+
include auto.mk
38+
39+
# The following only concerns the cross-compilation tests.
40+
# You can likely ignore the following for your application.
41+
#
42+
# Append cross-prefix for cross compilation
43+
# When called from the root Makefile, CROSS_PREFIX has already been added here
44+
ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
45+
CC := $(CROSS_PREFIX)$(CC)
46+
endif
47+
48+
# Part A:
49+
#
50+
# mldsa-native source and header files
51+
#
52+
# In this example, we compile the individual mldsa-native source files directly.
53+
# Alternatively, you can compile the 'monobuild' source file mldsa_native.c.
54+
# See examples/monolithic_build for that.
55+
MLD_SOURCE=$(wildcard \
56+
mldsa_native/*.c \
57+
mldsa_native/**/*.c \
58+
mldsa_native/**/**/*.c \
59+
mldsa_native/**/**/**/*.c)
60+
61+
INC=-Imldsa_native/
62+
63+
# Part B:
64+
#
65+
# Custom FIPS-202 implementation
66+
FIPS202_SOURCE=custom_fips202/tiny_sha3/sha3.c
67+
68+
# Part C:
69+
#
70+
# Random number generator
71+
#
72+
# !!! WARNING !!!
73+
#
74+
# The randombytes() implementation used here is for TESTING ONLY.
75+
# You MUST NOT use this implementation outside of testing.
76+
#
77+
# !!! WARNING !!!
78+
RNG_SOURCE=$(wildcard test_only_rng/*.c)
79+
80+
# Part D:
81+
#
82+
# Your application source code
83+
APP_SOURCE=$(wildcard *.c)
84+
85+
ALL_SOURCE=$(MLD_SOURCE) $(FIPS202_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
86+
87+
#
88+
# Configuration adjustments
89+
#
90+
91+
# Pick prefix
92+
CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
93+
# Tell mldsa-native to use serial-FIPS202 only
94+
CFLAGS += -DMLD_CONFIG_SERIAL_FIPS202_ONLY
95+
# Tell mldsa-native where to find the header for the custom FIPS202
96+
CFLAGS += -DMLD_CONFIG_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\""
97+
98+
BUILD_DIR=build
99+
BIN=test_binary
100+
101+
BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
102+
BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
103+
BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
104+
BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
105+
106+
$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
107+
$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
108+
$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
109+
110+
$(BINARIES_FULL): $(ALL_SOURCE)
111+
echo "$@"
112+
mkdir -p $(BUILD_DIR)
113+
$(CC) $(CFLAGS) $(INC) $^ -o $@
114+
115+
all: build
116+
117+
build: $(BINARIES_FULL)
118+
119+
run: $(BINARIES_FULL)
120+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
121+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
122+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
123+
124+
clean:
125+
rm -rf $(BUILD_DIR)

‎examples/bring_your_own_fips202_static/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[//]: # (SPDX-License-Identifier: CC-BY-4.0)
2+
3+
# Bring your own FIPS-202 (Static State Variant)
4+
5+
This directory contains a minimal example for how to use mldsa-native with external FIPS-202
6+
HW/SW-implementations that use a single global state (for example, some hardware accelerators).
7+
Specifically, this example demonstrates the use of the serial-only FIPS-202 configuration
8+
`MLD_CONFIG_SERIAL_FIPS202_ONLY`.
9+
10+
**WARNING:** This example is EXPECTED TO PRODUCE INCORRECT RESULTS because ML-DSA requires
11+
multiple independent FIPS-202 contexts to be active simultaneously. This example demonstrates
12+
what happens when only a single global state is available.
13+
14+
## Components
15+
16+
An application using mldsa-native with a custom FIPS-202 implementation needs the following:
17+
18+
1. Arithmetic part of the mldsa-native source tree: [`mldsa/`](../../mldsa)
19+
2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/randombytes.h).
20+
3. A custom FIPS-202 with `fips202.h` header compatible with [`mldsa/fips202/fips202.h`](../../mldsa/fips202/fips202.h).
21+
With `MLD_CONFIG_SERIAL_FIPS202_ONLY`, the FIPS-202x4 parallel API is not used.
22+
4. The application source code
23+
24+
**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
25+
outside of testing.
26+
27+
## Usage
28+
29+
Build this example with `make build`, run with `make run`.
30+
31+
You should see verification failures, which is the expected behavior demonstrating that a single
32+
global FIPS-202 state is insufficient for ML-DSA.
33+
34+
<!--- bibliography --->
35+
[^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/custom_fips202/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
2+
3+
# Custom FIPS-202 Implementation (Static Global State)
4+
5+
This directory contains a custom FIPS-202 implementation that wraps `tiny_sha3`[^tiny_sha3]
6+
using a **single global static state** for all operations.
7+
8+
## Purpose
9+
10+
This example demonstrates how mldsa-native can integrate with FIPS-202 implementations
11+
that maintain a single global state, such as:
12+
- Hardware accelerators with a single Keccak engine
13+
- Embedded systems with limited memory
14+
- Libraries that don't support multiple independent contexts
15+
16+
## How It Works
17+
18+
Instead of storing the Keccak state in each context structure, this implementation:
19+
20+
1. Uses a **static global state** for SHA-3/SHAKE operations
21+
2. Provides **dummy context structures** that are ignored by the API functions
22+
3. Includes **state machine assertions** to verify correct API usage
23+
## Configuration
24+
25+
Enable this mode with:
26+
```c
27+
#define MLD_CONFIG_FIPS202_CUSTOM_HEADER "\"fips202.h\""
28+
#define MLD_CONFIG_SERIAL_FIPS202_ONLY
29+
```
30+
31+
The `MLD_CONFIG_SERIAL_FIPS202_ONLY` flag tells mldsa-native to avoid
32+
using the parallel x4 API.
33+
34+
## Files
35+
36+
- `fips202.h` - Custom FIPS-202 wrapper with static global state
37+
- `tiny_sha3/` - Symlink to the tiny_sha3 implementation
38+
- `README.md` - This file
39+
40+
[^tiny_sha3]: https://github.com/mjosaarinen/tiny_sha3
41+
42+
<!--- bibliography --->
43+
[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

0 commit comments

Comments
 (0)