Skip to content

Commit 47831f0

Browse files
mkannwischermkannwischer
authored
Merge pull request #533 from pq-code-package/basic-example
Add examples/basic for mldsa-native as code package
2 parents 4d3a9ec + 7c4cad8 commit 47831f0

File tree

9 files changed

+1331
-2
lines changed

9 files changed

+1331
-2
lines changed

‎BIBLIOGRAPHY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,8 @@ source code and documentation.
233233
- Daniel J. Bernstein
234234
* URL: https://cr.yp.to/papers.html#surf
235235
* Referenced from:
236+
- [examples/basic/test_only_rng/notrandombytes.c](examples/basic/test_only_rng/notrandombytes.c)
237+
- [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
236238
- [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
237239
- [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
238240

‎examples/basic/.gitignore‎

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

‎examples/basic/Makefile‎

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

‎examples/basic/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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.
6+
7+
## Components
8+
9+
An application using mldsa-native as-is needs to include the following components:
10+
11+
1. mldsa-native source tree, including [`mldsa/`](../../mldsa) and [`mldsa/fips202/`](../../mldsa/fips202).
12+
2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/randombytes.h).
13+
3. The application source code
14+
15+
**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
16+
outside of testing.
17+
18+
## Usage
19+
20+
Build this example with `make build`, run with `make run`.
21+
22+
## What this example demonstrates
23+
24+
This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
25+
26+
1. **Key Generation**: Generate a public/private key pair
27+
2. **Signing**: Sign a message with a private key and optional context
28+
3. **Signature Verification**: Verify a signature using the public key
29+
4. **Signed Messages**: Create and open signed messages (signature + message combined)
30+
31+
The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
32+
33+
## Parameter Sets
34+
35+
ML-DSA supports three parameter sets:
36+
- **ML-DSA-44**
37+
- **ML-DSA-65**
38+
- **ML-DSA-87**
39+
40+
The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.

0 commit comments

Comments
 (0)