Skip to content

Commit d7dda7b

Browse files
L-seriesL-series
committed
randombytes: add example to test failure
This commit introduces a new example build which is meant to test the failure mode to the randombytes API. The randombytes_force_failure(n) function ensures that the nth call to randombytes will fail. Signed-off-by: Andreas Hatziiliou <[email protected]>
1 parent b3d90d8 commit d7dda7b

File tree

9 files changed

+1425
-0
lines changed

9 files changed

+1425
-0
lines changed

‎BIBLIOGRAPHY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -344,6 +344,8 @@ source code and documentation.
344344
* Referenced from:
345345
- [examples/basic/test_only_rng/notrandombytes.c](examples/basic/test_only_rng/notrandombytes.c)
346346
- [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
347+
- [examples/basic_rng_failure/test_only_rng/notrandombytes.c](examples/basic_rng_failure/test_only_rng/notrandombytes.c)
348+
- [examples/basic_rng_failure/test_only_rng/notrandombytes.h](examples/basic_rng_failure/test_only_rng/notrandombytes.h)
347349
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202/test_only_rng/notrandombytes.c)
348350
- [examples/bring_your_own_fips202/test_only_rng/notrandombytes.h](examples/bring_your_own_fips202/test_only_rng/notrandombytes.h)
349351
- [examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c](examples/bring_your_own_fips202_static/test_only_rng/notrandombytes.c)

‎examples/basic_rng_failure/Makefile‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
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+
# If you are not concerned about minimizing for a specific backend,
53+
# you can just include _all_ source files into your build.
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/src/*.c \
60+
mldsa_native/mldsa/src/**/*.c \
61+
mldsa_native/mldsa/src/**/**/*.c \
62+
mldsa_native/mldsa/src/**/**/**/*.c)
63+
64+
INC=-Imldsa_native/mldsa/
65+
66+
# Part B:
67+
#
68+
# Random number generator
69+
#
70+
# !!! WARNING !!!
71+
#
72+
# The randombytes() implementation used here is for TESTING ONLY.
73+
# You MUST NOT use this implementation outside of testing.
74+
#
75+
# !!! WARNING !!!
76+
RNG_SOURCE=$(wildcard test_only_rng/*.c)
77+
78+
# Part C:
79+
#
80+
# Your application source code
81+
APP_SOURCE=$(wildcard *.c)
82+
83+
ALL_SOURCE=$(MLD_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
84+
85+
BUILD_DIR=build
86+
BIN=test_binary
87+
88+
#
89+
# Configuration adjustments
90+
#
91+
92+
# Pick prefix
93+
CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
94+
95+
BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
96+
BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
97+
BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
98+
BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
99+
100+
$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
101+
$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
102+
$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
103+
104+
$(BINARIES_FULL): $(ALL_SOURCE)
105+
echo "$@"
106+
mkdir -p $(BUILD_DIR)
107+
$(CC) $(CFLAGS) $(INC) $^ -o $@
108+
109+
all: build
110+
111+
build: $(BINARIES_FULL)
112+
113+
run: $(BINARIES_FULL)
114+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
115+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
116+
$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
117+
118+
clean:
119+
rm -rf $(BUILD_DIR)

‎examples/basic_rng_failure/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
[//]: # (SPDX-License-Identifier: CC-BY-4.0)
2+
3+
# Building mldsa-native
4+
5+
This directory contains a minimal example for how to build mldsa-native and
6+
intentionally force failures in the `randombytes` provider so that you can
7+
exercise the library’s error paths.
8+
9+
## Components
10+
11+
An application using mldsa-native as-is needs to include the following components:
12+
13+
1. mldsa-native source tree, including [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202).
14+
2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
15+
3. The application source code
16+
17+
**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
18+
outside of testing. In this example it is also designed so tests can force
19+
it to fail after a configurable number of calls.
20+
21+
## Usage
22+
23+
Build this example with `make build`, run with `make run`.
24+
25+
The test binary executes three scenarios for each security level:
26+
27+
1. Force the first `randombytes` invocation (during key generation) to fail and
28+
check that `crypto_sign_keypair`.
29+
2. Allow key generation, then fail the second `randombytes` invocation (during
30+
signing) and confirm `crypto_sign_signature`.
31+
3. Disable failure injection (negative index) and exercise the full
32+
sign/verify flow, ensuring the expected deterministic signature is produced.
33+
34+
## What this example demonstrates
35+
36+
This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
37+
38+
1. **Key Generation**: Generate a public/private key pair
39+
2. **Signing**: Sign a message with a private key and optional context
40+
3. **Signature Verification**: Verify a signature using the public key
41+
4. **Signed Messages**: Create and open signed messages (signature + message combined)
42+
43+
The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
44+
45+
## Parameter Sets
46+
47+
ML-DSA supports three parameter sets:
48+
- **ML-DSA-44**
49+
- **ML-DSA-65**
50+
- **ML-DSA-87**
51+
52+
The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.

‎examples/basic_rng_failure/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)