Skip to content

Commit a1202a6

Browse files
willieyzmkannwischer
willieyz
authored and
mkannwischer
committed
Example: Custom Backend
- This commit add custom backend example, for this example, we add the arithmetic part but skip the arithmetic backend (remove `native` folder), since we decide to disable it. - This commit add a pseudo random number generator, implementing randombytes.h(reference from tests/test_only_rng). - WARNING: The randombytes() implementation used here is for TESTING ONLY. You MUST NOT use this implementation outside of testing. - This commit add custom backend fips202, we use tiny_sha3 here - This commit add `main.c` and `expected_signatures.h` to custom_backend, generate `custom_config.h` from `configs.yml`, also add auto.mk and Makefile. - Add custom_backend to `tests` and `lint` scripts - Add `Readme.md` to custom_backend, reference from mlkem-native Signed-off-by: willieyz <willie.zhao@chelpis.com>
1 parent 1915e47 commit a1202a6

Some content is hidden

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

52 files changed

+2193
-2
lines changed

‎BIBLIOGRAPHY.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ source code and documentation.
2424
* URL: https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements
2525
* Referenced from:
2626
- [examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h](examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h)
27+
- [examples/custom_backend/mldsa_native/custom_config.h](examples/custom_backend/mldsa_native/custom_config.h)
2728
- [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
2829
- [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
2930
- [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.h)
@@ -69,6 +70,7 @@ source code and documentation.
6970
* Referenced from:
7071
- [README.md](README.md)
7172
- [examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h](examples/basic_deterministic/mldsa_native/custom_no_randomized_config.h)
73+
- [examples/custom_backend/mldsa_native/custom_config.h](examples/custom_backend/mldsa_native/custom_config.h)
7274
- [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
7375
- [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
7476
- [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.h)
@@ -363,6 +365,7 @@ source code and documentation.
363365
- [examples/bring_your_own_fips202/README.md](examples/bring_your_own_fips202/README.md)
364366
- [examples/bring_your_own_fips202_static/README.md](examples/bring_your_own_fips202_static/README.md)
365367
- [examples/bring_your_own_fips202_static/custom_fips202/README.md](examples/bring_your_own_fips202_static/custom_fips202/README.md)
368+
- [examples/custom_backend/README.md](examples/custom_backend/README.md)
366369

367370
### `tweetfips`
368371

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,3 +223,4 @@ clean:
223223
-make clean -C examples/monolithic_build_multilevel >/dev/null
224224
-make clean -C examples/monolithic_build_native >/dev/null
225225
-make clean -C examples/monolithic_build_multilevel_native >/dev/null
226+
-make clean -C examples/custom_backend >/dev/null

‎examples/custom_backend/Makefile‎

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

‎examples/custom_backend/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[//]: # (SPDX-License-Identifier: CC-BY-4.0)
2+
3+
# Using a custom configuration and FIPS-202 backend
4+
5+
This directory contains a minimal example for how to use mldsa-native as a code package, with a custom FIPS-202
6+
backend and a custom configuration. We use [^tiny_sha3] as an example.
7+
8+
## Components
9+
10+
An application using mldsa-native with a custom FIPS-202 backend and custom configuration needs the following:
11+
12+
1. Arithmetic part of the mldsa-native source tree: [`mldsa/src/`](../../mldsa/src). In this example, we disable arithmetic
13+
backends, hence it is safe to remove the entire `native` subfolder.
14+
2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h). **WARNING:** The
15+
`randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation outside of testing.
16+
3. FIPS-202 part of the mldsa-native source tree, [`fips202/`](../../mldsa/src/fips202). If you only want to use your backend,
17+
you can remove all existing backends; that's what this example does.
18+
4. A custom FIPS-202 backend. In this example, the backend file is
19+
[custom.h](mldsa_native/mldsa/src/fips202/native/custom/custom.h), wrapping
20+
[sha3.c](mldsa_native/mldsa/src/fips202/native/custom/src/sha3.c) and setting `MLD_USE_FIPS202_X1_NATIVE` to indicate that we
21+
replace 1-fold Keccak-F1600.
22+
5. Either modify the existing [config.h](mldsa_native/mldsa/src/config.h), or register a new config. In this example, we add
23+
a new config [custom_config.h](mldsa_native/custom_config.h) and register it from the command line for
24+
`-DMLD_CONFIG_FILE="custom_config.h"` -- no further changes to the build are needed. For the sake of
25+
demonstration, we set a custom namespace. We set `MLD_CONFIG_FIPS202_BACKEND_FILE` to point to our custom FIPS-202
26+
backend, but leave `MLD_CONFIG_USE_NATIVE_BACKEND_ARITH` undefined to indicate that we wish to use the C backend.
27+
28+
## Note
29+
30+
The tiny_sha3 code uses a byte-reversed presentation of the Keccakf1600 state for big-endian targets. Since
31+
mldsa-native's FIPS202 frontend assumes a standard presentation, the corresponding byte-reversal in
32+
[sha3.c](mldsa_native/mldsa/src/fips202/native/custom/src/sha3.c) is removed.
33+
34+
## Usage
35+
36+
Build this example with `make build`, run with `make run`.
37+
38+
<!--- bibliography --->
39+
[^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

‎examples/custom_backend/auto.mk‎

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

0 commit comments

Comments
 (0)