Skip to content

Commit 03a184c

Browse files
hanno-beckerhanno-becker
authored
Merge pull request #557 from pq-code-package/byofips-example
Add bring_your_own_fips202 example
2 parents 94311a7 + e39af6a commit 03a184c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+1327
-50
lines changed

‎BIBLIOGRAPHY.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ source code and documentation.
3434
- National Institute of Standards and Technology
3535
* URL: https://csrc.nist.gov/pubs/fips/202/final
3636
* Referenced from:
37+
- [FIPS202.md](FIPS202.md)
3738
- [README.md](README.md)
3839

3940
### `FIPS204`
@@ -243,9 +244,22 @@ source code and documentation.
243244
* Referenced from:
244245
- [examples/basic/test_only_rng/notrandombytes.c](examples/basic/test_only_rng/notrandombytes.c)
245246
- [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
247+
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202/test_only_rng/notrandombytes.c)
248+
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202/test_only_rng/notrandombytes.h)
246249
- [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
247250
- [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
248251

252+
### `tiny_sha3`
253+
254+
* tiny_sha3
255+
* Author(s):
256+
- Markku-Juhani O. Saarinen
257+
* URL: https://github.com/mjosaarinen/tiny_sha3
258+
* Referenced from:
259+
- [FIPS202.md](FIPS202.md)
260+
- [README.md](README.md)
261+
- [examples/bring_your_own_fips202/README.md](examples/bring_your_own_fips202/README.md)
262+
249263
### `tweetfips`
250264

251265
* 'tweetfips202' FIPS202 implementation

‎BIBLIOGRAPHY.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,11 @@
106106
- Schwabe, Peter
107107
url: https://keccak.team/2015/tweetfips202.html
108108

109+
- id: tiny_sha3
110+
name: tiny_sha3
111+
author: Saarinen, Markku-Juhani O.
112+
url: https://github.com/mjosaarinen/tiny_sha3
113+
109114
- id: libmceliece
110115
name: libmceliece implementation of Classic McEliece
111116
author:

‎FIPS202.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
[//]: # (SPDX-License-Identifier: CC-BY-4.0)
2+
3+
# Replacing FIPS-202
4+
5+
If your library has a FIPS-202[^FIPS202] implementation, you can use it instead of the one shipped with mldsa-native.
6+
7+
1. Replace `mldsa/fips202/*` by your own FIPS-202 implementation.
8+
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
9+
functionalities specified therein:
10+
* Structure definitions for `mld_shake128ctx`, `mld_shake256ctx`, `mld_shake128x4ctx`, and `mld_shake256x4ctx`
11+
* `mld_shake128_init()`: Initialize a SHAKE-128 context
12+
* `mld_shake128_absorb()`: Absorb data into a SHAKE-128 context (can be called multiple times)
13+
* `mld_shake128_finalize()`: Finalize the absorb phase of a SHAKE-128 context
14+
* `mld_shake128_squeeze()`: Squeeze data from a SHAKE-128 context (can be called multiple times)
15+
* `mld_shake128_release()`: Release and securely zero a SHAKE-128 context after use
16+
* `mld_shake256_init()`: Initialize a SHAKE-256 context
17+
* `mld_shake256_absorb()`: Absorb data into a SHAKE-256 context (can be called multiple times)
18+
* `mld_shake256_finalize()`: Finalize the absorb phase of a SHAKE-256 context
19+
* `mld_shake256_squeeze()`: Squeeze data from a SHAKE-256 context (can be called multiple times)
20+
* `mld_shake256_release()`: Release and securely zero a SHAKE-256 context after use
21+
* `mld_shake256()`: One-shot SHAKE-256 operation
22+
* `mld_shake128x4_init()`: Initialize a 4x-batched SHAKE-128 context
23+
* `mld_shake128x4_absorb_once()`: Initialize and absorb into a 4x-batched SHAKE-128 context in one step
24+
* `mld_shake128x4_squeezeblocks()`: Squeeze blocks from a 4x-batched SHAKE-128 context
25+
* `mld_shake128x4_release()`: Release a 4x-batched SHAKE-128 context after use
26+
* `mld_shake256x4_init()`: Initialize a 4x-batched SHAKE-256 context
27+
* `mld_shake256x4_absorb_once()`: Initialize and absorb into a 4x-batched SHAKE-256 context in one step
28+
* `mld_shake256x4_squeezeblocks()`: Squeeze blocks from a 4x-batched SHAKE-256 context
29+
* `mld_shake256x4_release()`: Release a 4x-batched SHAKE-256 context after use
30+
31+
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
32+
definitions may differ from those shipped with mldsa-native.
33+
34+
## Example
35+
36+
See [`examples/bring_your_own_fips202/`](examples/bring_your_own_fips202/) for an example how to use a custom FIPS-202
37+
implementation with tiny_sha3[^tiny_sha3].
38+
39+
<!--- bibliography --->
40+
[^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)
41+
[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,11 @@ offers backends for C, AArch64, and x86_64 - if you'd like contribute new backen
6262

6363
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.
6464

65-
### Will I be able to bring my own FIPS-202?
65+
### Can I bring my own FIPS-202?
6666

6767
mldsa-native relies on and comes with an implementation of FIPS-202[^FIPS202]. If your library has its own FIPS-202 implementation, you
68-
can use it instead of the one shipped with mldsa-native.
68+
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)
69+
for an example using tiny_sha3[^tiny_sha3].
6970

7071
### Will I need to use the assembly backends?
7172

@@ -124,3 +125,4 @@ through the [PQCA Discord](https://discord.com/invite/xyVnwzfg5R).
124125
[^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)
125126
[^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)
126127
[^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)
128+
[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

‎examples/basic/Makefile‎

Lines changed: 53 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,65 @@
1-
# (SPDX-License-Identifier: CC-BY-4.0)
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
24

3-
.PHONY: build run clean size
5+
.PHONY: build run clean
46
.DEFAULT_GOAL := all
57

6-
# Append cross-prefix for cross compilation
7-
# Remove or ignore for native builds
88
CC ?= gcc
9-
SIZE ?= size
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
1043
# When called from the root Makefile, CROSS_PREFIX has already been added here
1144
ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
1245
CC := $(CROSS_PREFIX)$(CC)
1346
endif
1447

15-
ifeq (,$(findstring $(CROSS_PREFIX),$(SIZE)))
16-
SIZE := $(CROSS_PREFIX)$(SIZE)
17-
endif
18-
1948
# Part A:
2049
#
2150
# mldsa-native source and header files
2251
#
2352
# If you are not concerned about minimizing for a specific backend,
2453
# you can just include _all_ source files into your build.
25-
MLD_SOURCE=$(wildcard \
26-
../../mldsa/*.c \
27-
../../mldsa/**/*.c \
28-
../../mldsa/**/**/*.c \
29-
../../mldsa/**/**/**/*.c)
54+
#
55+
# In this example, we compile the individual mldsa-native source files directly.
56+
# Alternatively, you can compile the 'monobuild' source file mldsa_native.c.
57+
# See examples/monolithic_build for that.
58+
MLD_SOURCE=$(wildcard \
59+
mldsa_native/mldsa/*.c \
60+
mldsa_native/mldsa/**/*.c \
61+
mldsa_native/mldsa/**/**/*.c \
62+
mldsa_native/mldsa/**/**/**/*.c)
3063

3164
# Part B:
3265
#
@@ -50,29 +83,12 @@ ALL_SOURCE=$(MLD_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
5083
BUILD_DIR=build
5184
BIN=test_binary
5285

53-
CFLAGS := \
54-
-Wall \
55-
-Wextra \
56-
-Werror \
57-
-Wmissing-prototypes \
58-
-Wshadow \
59-
-Werror \
60-
-Wpointer-arith \
61-
-Wredundant-decls \
62-
-Wconversion \
63-
-Wsign-conversion \
64-
-Wno-long-long \
65-
-Wno-unknown-pragmas \
66-
-Wno-unused-command-line-argument \
67-
-fomit-frame-pointer \
68-
-std=c99 \
69-
-pedantic \
70-
-MMD \
71-
-O3 \
72-
$(CFLAGS)
86+
#
87+
# Configuration adjustments
88+
#
7389

74-
# Use the default namespace prefix from config.h
75-
# CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
90+
# Pick prefix
91+
CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
7692

7793
BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
7894
BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
@@ -88,7 +104,7 @@ $(BINARIES_FULL): $(ALL_SOURCE)
88104
mkdir -p $(BUILD_DIR)
89105
$(CC) $(CFLAGS) $^ -o $@
90106

91-
all: build size
107+
all: build
92108

93109
build: $(BINARIES_FULL)
94110

@@ -97,13 +113,5 @@ run: $(BINARIES_FULL)
97113
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
98114
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
99115

100-
size: build
101-
@echo "=== Size info for $(BINARY_NAME_FULL_44) ==="
102-
@$(SIZE) $(BINARY_NAME_FULL_44)
103-
@echo "=== Size info for $(BINARY_NAME_FULL_65) ==="
104-
@$(SIZE) $(BINARY_NAME_FULL_65)
105-
@echo "=== Size info for $(BINARY_NAME_FULL_87) ==="
106-
@$(SIZE) $(BINARY_NAME_FULL_87)
107-
108116
clean:
109117
rm -rf $(BUILD_DIR)

‎examples/basic/auto.mk‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../test/mk/auto.mk

‎examples/basic/mldsa_native/mldsa‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../mldsa

‎examples/bring_your_own_fips202/.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/Makefile‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
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 where to find the header for the custom FIPS202
94+
# The structure names and function signatures exposed in those headers must
95+
# match those from the standard FIPS202 implementation. See FIPS202.md.
96+
CFLAGS += -DMLD_CONFIG_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\""
97+
CFLAGS += -DMLD_CONFIG_FIPS202X4_CUSTOM_HEADER="\"../custom_fips202/fips202x4.h\""
98+
99+
BUILD_DIR=build
100+
BIN=test_binary
101+
102+
BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
103+
BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
104+
BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
105+
BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
106+
107+
$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
108+
$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
109+
$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
110+
111+
$(BINARIES_FULL): $(ALL_SOURCE)
112+
echo "$@"
113+
mkdir -p $(BUILD_DIR)
114+
$(CC) $(CFLAGS) $(INC) $^ -o $@
115+
116+
all: build
117+
118+
build: $(BINARIES_FULL)
119+
120+
run: $(BINARIES_FULL)
121+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
122+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
123+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
124+
125+
clean:
126+
rm -rf $(BUILD_DIR)

0 commit comments

Comments
 (0)