Add examples/basic

Adds ML-DSA signature demonstration for all parameter sets. Including:
- deterministic KAT verification using SURF PRNG
- integration into scripts/tests with TEST_TYPES.BASIC

Signed-off-by: Jake Massimo <[email protected]>

Author: jakemas

BIBLIOGRAPHY.md

@@ -233,6 +233,8 @@ source code and documentation.
   - Daniel J. Bernstein
 * URL: https://cr.yp.to/papers.html#surf
 * Referenced from:
+  - [examples/basic/test_only_rng/notrandombytes.c](examples/basic/test_only_rng/notrandombytes.c)
+  - [examples/basic/test_only_rng/notrandombytes.h](examples/basic/test_only_rng/notrandombytes.h)
   - [test/notrandombytes/notrandombytes.c](test/notrandombytes/notrandombytes.c)
   - [test/notrandombytes/notrandombytes.h](test/notrandombytes/notrandombytes.h)
 

examples/basic/.gitignore

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+build

examples/basic/Makefile

@@ -0,0 +1,107 @@
+# (SPDX-License-Identifier: CC-BY-4.0)
+
+.PHONY: build run clean size
+.DEFAULT_GOAL := all
+
+# Append cross-prefix for cross compilation
+# Remove or ignore for native builds
+CC  ?= gcc
+SIZE ?= size
+# When called from the root Makefile, CROSS_PREFIX has already been added here
+ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
+CC  := $(CROSS_PREFIX)$(CC)
+endif
+
+ifeq (,$(findstring $(CROSS_PREFIX),$(SIZE)))
+SIZE  := $(CROSS_PREFIX)$(SIZE)
+endif
+
+# Part A:
+#
+# mldsa-native source and header files
+#
+# If you are not concerned about minimizing for a specific backend,
+# you can just include _all_ source files into your build.
+MLD_SOURCE=$(wildcard                    \
+	../../mldsa/*.c                      \
+	../../mldsa/**/*.c                   \
+	../../mldsa/**/**/*.c                \
+	../../mldsa/**/**/**/*.c)
+
+# Part B:
+#
+# Random number generator
+#
+# !!! WARNING !!!
+#
+# The randombytes() implementation used here is for TESTING ONLY.
+# You MUST NOT use this implementation outside of testing.
+#
+# !!! WARNING !!!
+RNG_SOURCE=$(wildcard test_only_rng/*.c)
+
+# Part C:
+#
+# Your application source code
+APP_SOURCE=$(wildcard *.c)
+
+ALL_SOURCE=$(MLD_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
+
+BUILD_DIR=build
+BIN=test_binary
+
+CFLAGS := \
+	-Wall \
+	-Wextra \
+	-Werror \
+	-Wmissing-prototypes \
+	-Wshadow \
+	-Werror \
+	-Wpointer-arith \
+	-Wredundant-decls \
+	-Wno-long-long \
+	-Wno-unknown-pragmas \
+	-Wno-unused-command-line-argument \
+	-fomit-frame-pointer \
+	-std=c99 \
+	-pedantic \
+	-MMD \
+	-O3 \
+	$(CFLAGS)
+
+# Use the default namespace prefix from config.h
+# CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa
+
+BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44
+BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65
+BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87
+BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87)
+
+$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44
+$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65
+$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87
+
+$(BINARIES_FULL): $(ALL_SOURCE)
+	echo "$@"
+	mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) $^ -o $@
+
+all: build size
+
+build: $(BINARIES_FULL)
+
+run: $(BINARIES_FULL)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87)
+
+size: build
+	@echo "=== Size info for $(BINARY_NAME_FULL_44) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_44)
+	@echo "=== Size info for $(BINARY_NAME_FULL_65) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_65)
+	@echo "=== Size info for $(BINARY_NAME_FULL_87) ==="
+	@$(SIZE) $(BINARY_NAME_FULL_87)
+
+clean:
+	rm -rf $(BUILD_DIR)

examples/basic/README.md

@@ -0,0 +1,40 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Building mldsa-native
+
+This directory contains a minimal example for how to build mldsa-native.
+
+## Components
+
+An application using mldsa-native as-is needs to include the following components:
+
+1. mldsa-native source tree, including [`mldsa/`](../../mldsa) and [`mldsa/fips202/`](../../mldsa/fips202).
+2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/randombytes.h).
+3. The application source code
+
+**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
+outside of testing.
+
+## Usage
+
+Build this example with `make build`, run with `make run`.
+
+## What this example demonstrates
+
+This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
+
+1. **Key Generation**: Generate a public/private key pair
+2. **Signing**: Sign a message with a private key and optional context
+3. **Signature Verification**: Verify a signature using the public key
+4. **Signed Messages**: Create and open signed messages (signature + message combined)
+
+The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
+
+## Parameter Sets
+
+ML-DSA supports three parameter sets:
+- **ML-DSA-44**
+- **ML-DSA-65**
+- **ML-DSA-87**
+
+The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.