Skip to content

Commit 5ed8c3d

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 5268a5c commit 5ed8c3d

File tree

12 files changed

+710
-2
lines changed

12 files changed

+710
-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: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Copyright (c) The mldsa-native project authors
2+
# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
3+
4+
.PHONY: build run clean size
5+
.DEFAULT_GOAL := all
6+
7+
# Append cross-prefix for cross compilation
8+
# Remove or ignore for native builds
9+
CC ?= gcc
10+
SIZE ?= size
11+
# When called from the root Makefile, CROSS_PREFIX has already been added here
12+
ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
13+
CC := $(CROSS_PREFIX)$(CC)
14+
endif
15+
16+
ifeq (,$(findstring $(CROSS_PREFIX),$(SIZE)))
17+
SIZE := $(CROSS_PREFIX)$(SIZE)
18+
endif
19+
20+
# Part A:
21+
#
22+
# mldsa-native source and header files
23+
MLD_SOURCE=$(wildcard \
24+
../../mldsa/*.c \
25+
../../mldsa/native/**/*.c \
26+
../../mldsa/native/**/**/*.c)
27+
28+
INC=-I../../mldsa/ -Icustom_fips202/
29+
30+
# Part B:
31+
#
32+
# Custom FIPS-202 implementation
33+
FIPS202_SOURCE=custom_fips202/tiny_sha3/sha3.c
34+
35+
# Part C:
36+
#
37+
# Random number generator
38+
#
39+
# !!! WARNING !!!
40+
#
41+
# The randombytes() implementation used here is for TESTING ONLY.
42+
# You MUST NOT use this implementation outside of testing.
43+
#
44+
# !!! WARNING !!!
45+
RNG_SOURCE=$(wildcard test_only_rng/*.c)
46+
47+
# Part D:
48+
#
49+
# Your application source code
50+
APP_SOURCE=$(wildcard *.c)
51+
52+
ALL_SOURCE=$(MLD_SOURCE) $(FIPS202_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
53+
54+
BUILD_DIR=build
55+
BIN=test_binary
56+
57+
CFLAGS := \
58+
-Wall \
59+
-Wextra \
60+
-Werror \
61+
-Wmissing-prototypes \
62+
-Wshadow \
63+
-Wpointer-arith \
64+
-Wredundant-decls \
65+
-Wconversion \
66+
-Wno-long-long \
67+
-Wno-unknown-pragmas \
68+
-Wno-unused-command-line-argument \
69+
-fomit-frame-pointer \
70+
-std=c99 \
71+
-pedantic \
72+
-MMD \
73+
-O3 \
74+
$(CFLAGS)
75+
CFLAGS += -DMLD_CONFIG_FIPS202_CUSTOM_HEADER="\"fips202.h\""
76+
CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
77+
CFLAGS += -DMLD_CONFIG_SERIAL_FIPS202_ONLY
78+
79+
BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
80+
BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
81+
BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
82+
BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
83+
84+
$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
85+
$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
86+
$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
87+
88+
$(BINARIES_FULL): $(ALL_SOURCE)
89+
echo "$@"
90+
mkdir -p $(BUILD_DIR)
91+
$(CC) $(CFLAGS) $(INC) $^ -o $@
92+
93+
all: build size
94+
95+
build: $(BINARIES_FULL)
96+
97+
run: $(BINARIES_FULL)
98+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
99+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
100+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
101+
102+
size: build
103+
@echo "=== Size info for binaries $(BINARY_NAME_FULL_44) ==="
104+
@$(SIZE) $(BINARY_NAME_FULL_44)
105+
@echo "=== Size info for binaries $(BINARY_NAME_FULL_65) ==="
106+
@$(SIZE) $(BINARY_NAME_FULL_65)
107+
@echo "=== Size info for binaries $(BINARY_NAME_FULL_87) ==="
108+
@$(SIZE) $(BINARY_NAME_FULL_87)
109+
110+
clean:
111+
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)