Expand and unify example READMEs

Signed-off-by: Matthias J. Kannwischer <matthias@kannwischer.eu>

Author: mkannwischer

examples/README.md

@@ -0,0 +1,54 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Usage examples
+
+This directory contains minimal examples demonstrating how you can use mldsa-native.
+
+## Basic
+
+See [basic](basic) for a basic example of how to build a single instance of mldsa-native.
+
+## Basic_deterministic
+
+See [basic_deterministic](basic_deterministic) for a basic example of how to build a single instance of mldsa-native without `randombytes()` implementation. This allows users to build mldsa-native using only the deterministic API when randomized functions are not required.
+## Multi-level build (C only)
+
+See [multilevel_build](multilevel_build) for an example of how to build one instance of mldsa-native per security level,
+in such a way that level-independent code is shared.
+
+## Multi-level build (with native code)
+
+See [multilevel_build_native](multilevel_build_native) for an example of how to build one instance of mldsa-native per
+security level, in such a way that level-independent code is shared, and leveraging the native backends.
+
+## Custom FIPS202 implementation
+
+See [bring_your_own_fips202](bring_your_own_fips202) for an example of how to use mldsa-native with your own FIPS-202
+implementation.
+
+## Custom FIPS202 implementation (static state variant)
+
+See [bring_your_own_fips202_static](bring_your_own_fips202_static) for an example of how to use mldsa-native with a
+custom FIPS-202 implementation using a static state. This variant demonstrates the serial-only FIPS-202 configuration
+(`MLD_CONFIG_SERIAL_FIPS202_ONLY`).
+
+## Custom config + custom FIPS-202 backend
+
+See [custom_backend](custom_backend) for an example of how to use mldsa-native with a custom configuration file and a
+custom FIPS-202 backend.
+
+## Monobuild (C only)
+
+See [monolithic_build](monolithic_build) for an example of how to build mldsa-native (with C backend) from a single
+auto-generated compilation unit.
+
+## Multi-level monobuild (C only)
+
+See [monolithic_build_multilevel](monolithic_build_multilevel) for an example of how to build all security levels of
+mldsa-native (with C backend) inside a single compilation unit, sharing the level-independent code.
+
+## Multi-level monobuild (with native code)
+
+See [monolithic_build_multilevel_native](monolithic_build_multilevel_native) for an example of how to build all security
+levels of mldsa-native inside a single compilation unit, sharing the level-independent code, while also linking in assembly
+from the native backends.

examples/basic/README.md

@@ -1,40 +1,38 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Building mldsa-native
+# Basic build
 
-This directory contains a minimal example for how to build mldsa-native.
+This directory contains a minimal example for how to build mldsa-native for a single security level.
 
-## Components
-
-An application using mldsa-native as-is needs to include the following components:
-
-1. mldsa-native source tree, including [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202).
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
-3. The application source code
+## Use Case
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+Use this approach when:
+- You need only one ML-DSA parameter set (44, 65, or 87)
+- You want to build the mldsa-native C files separately, not as a single compilation unit.
+- You're using C only, no native backends.
 
-## Usage
+## Components
 
-Build this example with `make build`, run with `make run`.
+1. mldsa-native source tree: [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202)
+2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h)
+3. Your application source code
 
-## What this example demonstrates
+## Configuration
 
-This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_PARAMETER_SET`: Security level (44, 65, or 87). Default is 65.
+- `MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mldsa` in this example.
 
-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)
+To change the security level, modify `MLD_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS.
 
-The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
+## Usage
 
-## Parameter Sets
+```bash
+make build   # Build the example
+make run     # Run the example
+```
 
-ML-DSA supports three parameter sets:
-- **ML-DSA-44**
-- **ML-DSA-65**
-- **ML-DSA-87**
+## Warning
 
-The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.
+The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
+You MUST provide a cryptographically secure RNG for production use.

examples/basic_deterministic/README.md

@@ -1,33 +1,36 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Building mldsa-native
 
-This directory contains a minimal example showing how to build **mldsa-native** for use cases only requiring the deterministic key generation and signing APIs (`crypto_sign_keypair_internal` and `crypto_sign_signature_internal`). In that case, no implementation of `randombytes()` has to be provided.
+This directory contains a minimal example for building mldsa-native using only the deterministic API,
+without requiring a `randombytes()` implementation.
 
-## Components
+## Use Case
 
-An application using mldsa-native as-is needs to include the following components:
+Use this approach when:
+- Your application manages its own entropy/randomness externally
+- You only need `crypto_sign_keypair_internal` and `crypto_sign_signature_internal` (deterministic variants)
 
-1. mldsa-native source tree, including [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202).
-2. The application source code
+## Components
 
-## Usage
+1. mldsa-native source tree: [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202)
+2. Your application source code
 
-Build this example with `make build`, run with `make run`.
+No `randombytes()` implementation is required.
 
-## What this example demonstrates
+## Configuration
 
-This basic_deterministic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_NO_RANDOMIZED_API`: Disables `crypto_sign_keypair`, `crypto_sign_signature`, etc. 
+- `MLD_CONFIG_PARAMETER_SET`: Security level (default 65)
+- `MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mldsa`)
 
-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
+## Notes
 
-## Parameter Sets
+- This is incompatible with `MLD_CONFIG_KEYGEN_PCT` (pairwise consistency test)
 
-ML-DSA supports three parameter sets:
-- **ML-DSA-44**
-- **ML-DSA-65**
-- **ML-DSA-87**
+## Usage
 
-The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.
+```bash
+make build   # Build the example
+make run     # Run the example
+```

examples/bring_your_own_fips202/README.md

@@ -1,40 +1,49 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Bring your own FIPS-202
+# Bring Your Own FIPS-202
 
-This directory contains a minimal example for how to use mldsa-native as a code package, with a custom FIPS-202
+This directory contains a minimal example for using mldsa-native with a custom FIPS-202 (SHA-3/SHAKE)
 implementation. We use tiny_sha3[^tiny_sha3] as an example.
 
+## Use Case
+
+Use this approach when:
+- You need only one ML-DSA parameter set (44, 65, or 87)
+- Your application already has a FIPS-202 software/hardware implementation you want to reuse
+
 ## Components
 
-An application using mldsa-native with a custom FIPS-202 implementation needs the following:
+1. Arithmetic part of mldsa-native: [`mldsa/src/`](../../mldsa/src) (excluding `fips202/`)
+2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h)
+3. Custom FIPS-202 implementation with headers compatible with:
+   - [`fips202.h`](../../mldsa/src/fips202/fips202.h)
+   - [`fips202x4.h`](../../mldsa/src/fips202/fips202x4.h)
+4. Your application source code
 
-1. Arithmetic part of the mldsa-native source tree: [`mldsa/src/`](../../mldsa/src)
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
-3. A custom FIPS-202 with `fips202.h` and `fips202x4.h` headers compatible with
-   [`mldsa/src/fips202/fips202.h`](../../mldsa/src/fips202/fips202.h) and [`mldsa/src/fips202/fips202x4.h`](../../mldsa/src/fips202/fips202x4.h).
-4. The application source code
+## Configuration
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h`
+- `MLD_CONFIG_FIPS202X4_CUSTOM_HEADER`: Path to your custom `fips202x4.h`
 
-## Usage
+Your custom FIPS-202 implementation must impelement the API specified in [FIPS202.md](../../FIPS202.md).
 
-Build this example with `make build`, run with `make run`.
+## Notes
 
-## Custom FIPS-202 Implementation
+- The 4x batched functions (`x4`) can fall back to 4 sequential calls if batching isn't available
+- Structure definitions may differ from mldsa-native's defaults (e.g., for incremental hashing)
 
-This example uses tiny_sha3 as the underlying Keccak/SHA3 implementation. The wrapper headers in `custom_fips202/`
-adapt the tiny_sha3 API to match the API expected by mldsa-native.
+## Usage
 
-Note that the `fips202x4.h` implementation provided here is a simple serial implementation that does not provide
-any performance benefits from parallelization. For production use, consider using an optimized parallel implementation.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
 
-## Verification
+## Warning
 
-This example uses the same test vectors as the basic example (via a symlink to `expected_signatures.h`) and verifies
-that the custom FIPS-202 implementation produces identical results to the default implementation. This ensures that
-the wrapper is correctly implementing the required API.
+The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
+You MUST provide a cryptographically secure RNG for production use.
 
 <!--- bibliography --->
 [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)

examples/bring_your_own_fips202_static/README.md

@@ -1,35 +1,54 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Bring your own FIPS-202 (Static State Variant)
+# Bring Your Own FIPS-202 (Static State Variant)
 
-This directory contains a minimal example for how to use mldsa-native with external FIPS-202
-HW/SW-implementations that use a single global state (for example, some hardware accelerators).
-Specifically, this example demonstrates the use of the serial-only FIPS-202 configuration
-`MLD_CONFIG_SERIAL_FIPS202_ONLY`.
+This directory contains a minimal example for using mldsa-native with a custom FIPS-202 implementation
+that uses a single global state. This is common for hardware accelerators that can only hold one
+Keccak state at a time.
 
-**WARNING:** This example is EXPECTED TO PRODUCE INCORRECT RESULTS because ML-DSA requires
-multiple independent FIPS-202 contexts to be active simultaneously. This example demonstrates
-what happens when only a single global state is available.
+## Use Case
+
+Use this approach when:
+- You need only one ML-DSA parameter set (44, 65, or 87)
+- Your application already has a FIPS-202 software/hardware implementation you want to reuse
+- Your FIPS-202 implementation does not support multiple active SHA3/SHAKE computations.
 
 ## Components
 
-An application using mldsa-native with a custom FIPS-202 implementation needs the following:
+1. Arithmetic part of mldsa-native: [`mldsa/src/`](../../mldsa/src) (excluding `fips202/`)
+2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h)
+3. Custom FIPS-202 implementation with headers compatible with [`fips202.h`](../../mldsa/src/fips202/fips202.h)
+4. Your application source code
+
+## Configuration
+
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_SERIAL_FIPS202_ONLY`: Disables batched Keccak; matrix entries generated one at a time
+- `MLD_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h`
 
-1. Arithmetic part of the mldsa-native source tree: [`mldsa/src/`](../../mldsa/src)
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
-3. A custom FIPS-202 with `fips202.h` header compatible with [`mldsa/fips202/fips202.h`](../../mldsa/src/fips202/fips202.h).
-   With `MLD_CONFIG_SERIAL_FIPS202_ONLY`, the FIPS-202x4 parallel API is not used.
-4. The application source code
+Your custom FIPS-202 implementation must provide:
+- `mld_shake128_init()`, `mld_shake128_absorb()`, `mld_shake128_finalize()`, `mld_shake128_squeeze()`, `mld_shake128_release()`
+- `mld_shake256_init()`, `mld_shake256_absorb()`, `mld_shake256_finalize()`, `mld_shake256_squeeze()`, `mld_shake256_release()`
+- `mld_shake256`
+- Structure definitions for `mld_shake128ctx` and `mld_shake256ctx`
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+## Notes
+
+- `MLD_CONFIG_SERIAL_FIPS202_ONLY` may reduce performance on CPUs with SIMD support
+- Matrix and vector generation becomes sequential instead of batched (4 entries at a time)
+- Only enable this when your hardware requires it
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
+
+## Warning
 
-You should see verification failures, which is the expected behavior demonstrating that a single
-global FIPS-202 state is insufficient for ML-DSA.
+The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
+You MUST provide a cryptographically secure RNG for production use.
 
 <!--- bibliography --->
 [^tiny_sha3]: Markku-Juhani O. Saarinen: tiny_sha3, [https://github.com/mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3)