Expand and unify example READMEs

Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>

Author: hanno-becker

examples/basic/README.md

@@ -1,20 +1,41 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Building mlkem-native
+# Basic build
 
-This directory contains a minimal example for how to build mlkem-native.
+This directory contains a minimal example for how to build mlkem-native for a single security level.
+
+## Use Case
+
+Use this approach when:
+- You need only one ML-KEM security level (512, 768, or 1024)
+- You want to build the mlkem-native C files separately, not as a single compilation unit.
+- You're using C only, no native backends.
 
 ## Components
 
-An application using mlkem-native as-is needs to include the following components:
+1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202)
+2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h)
+3. Your application source code
+
+## Configuration
 
-1. mlkem-native source tree, including [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202).
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h).
-3. The application source code
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_PARAMETER_SET`: Security level (512, 768, or 1024). Default is 768.
+- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mlkem` in this example.
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+To change the security level, modify `MLK_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS:
+```bash
+make build CFLAGS="-DMLK_CONFIG_PARAMETER_SET=512"
+```
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
+
+## Warning
+
+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,20 +1,37 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Building mlkem-native
+# Basic derandomized-only build
 
-This directory contains a minimal example showing how to build **mlkem-native** for use cases only requiring the deterministic key generation and encapsulation APIs (`crypto_kem_keypair_derand` and `crypto_kem_enc_derand`). In that case, no implementation of `randombytes()` has to be provided.
+This directory contains a minimal example for building mlkem-native using only the deterministic API,
+without requiring a `randombytes()` implementation.
 
-The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets `MLK_CONFIG_NO_RANDOMIZED_API`
-to disable the randomized API functions.
+## Use Case
+
+Use this approach when:
+- Your application manages its own entropy/randomness externally
+- You only need `crypto_kem_keypair_derand` and `crypto_kem_enc_derand` (deterministic variants)
 
 ## Components
 
-An application using mlkem-native as-is needs to include the following components:
+1. mlkem-native source tree: [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202)
+2. Your application source code
+
+No `randombytes()` implementation is required.
+
+## Configuration
+
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_NO_RANDOMIZED_API`: Disables `crypto_kem_keypair` and `crypto_kem_enc`
+- `MLK_CONFIG_PARAMETER_SET`: Security level (default 768)
+- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mlkem`)
 
-1. mlkem-native source tree, including [`mlkem/src/`](../../mlkem/src) and [`mlkem/src/fips202/`](../../mlkem/src/fips202).
-2. The application source code
+## Notes
 
+- This is incompatible with `MLK_CONFIG_KEYGEN_PCT` (pairwise consistency test)
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```

examples/bring_your_own_fips202/README.md

@@ -1,29 +1,55 @@
 [//]: # (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 mlkem-native as a code package, with a custom FIPS-202
+This directory contains a minimal example for using mlkem-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:
+- Your application already has a FIPS-202 software/hardware implementation you want to reuse
+
 ## Components
 
-An application using mlkem-native with a custom FIPS-202 implementation needs the following:
+1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src) (excluding `fips202/`)
+2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h)
+3. Custom FIPS-202 implementation with headers compatible with:
+   - [`fips202.h`](../../mlkem/src/fips202/fips202.h)
+   - [`fips202x4.h`](../../mlkem/src/fips202/fips202x4.h)
+4. Your application source code
+
+## Configuration
+
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h`
+- `MLK_CONFIG_FIPS202X4_CUSTOM_HEADER`: Path to your custom `fips202x4.h`
 
-1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src)
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h).
-3. A custom FIPS-202 with `fips202.h` and `fips202x4.h` headers compatible with
-   [`mlkem/src/fips202/fips202.h`](../../mlkem/src/fips202/fips202.h) and [`mlkem/src/fips202/fips202x4.h`](../../mlkem/src/fips202/fips202x4.h).
-4. The application source code
+Your custom FIPS-202 implementation must provide:
+- `mlk_shake128_absorb_once()`, `mlk_shake128_squeezeblocks()`, `mlk_shake128_release()`
+- `mlk_shake256()`, `mlk_sha3_256()`, `mlk_sha3_512()`
+- `mlk_shake256x4()`
+- `mlk_shake128x4_absorb_once()`, `mlk_shake128x4_squeezeblocks()`, `mlk_shake128x4_release()`
+- Structure definitions for `mlk_shake128ctx` and `mlk_shake128x4ctx`
 
-The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets
-`MLK_CONFIG_FIPS202_CUSTOM_HEADER` and `MLK_CONFIG_FIPS202X4_CUSTOM_HEADER` to point to the custom FIPS-202 headers.
+See [FIPS202.md](../../FIPS202.md) for the complete API specification.
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+## Notes
+
+- The 4x batched functions (`x4`) can fall back to 4 sequential calls if batching isn't available
+- Structure definitions may differ from mlkem-native's defaults (e.g., for incremental hashing)
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
+
+## Warning
+
+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,28 +1,56 @@
 [//]: # (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 mlkem-native with external FIPS202
-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
-`MLK_CONFIG_SERIAL_FIPS202_ONLY`.
+This directory contains a minimal example for using mlkem-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.
+
+## Use Case
+
+Use this approach when:
+- 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 mlkem-native with a custom FIPS-202 implementation needs the following:
+1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src) (excluding `fips202/`)
+2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h)
+3. Custom FIPS-202 implementation with header compatible with [`fips202.h`](../../mlkem/src/fips202/fips202.h)
+4. Stub `fips202x4.h` header (the 4x functions are unused in this mode)
+5. Your application source code
+
+## Configuration
+
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_SERIAL_FIPS202_ONLY`: Disables batched Keccak; matrix entries generated one at a time
+- `MLK_CONFIG_FIPS202_CUSTOM_HEADER`: Path to your custom `fips202.h`
+- `MLK_CONFIG_FIPS202X4_CUSTOM_HEADER`: Path to stub `fips202x4.h`
 
-1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src)
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h).
-2. A custom FIPS202 with `fips202.h` header compatible with [`mlkem/src/fips202/fips202.h`](../../mlkem/src/fips202/fips202.h).
-   The FIPS202x4 header `fips202x4.h` is unused with `MLK_CONFIG_SERIAL_FIPS202_ONLY` and can be filled with stubs.
-3. The application source code
+Your custom FIPS-202 implementation must provide:
+- `mlk_shake128_absorb_once()`, `mlk_shake128_squeezeblocks()`, `mlk_shake128_release()`
+- `mlk_shake256()`, `mlk_sha3_256()`, `mlk_sha3_512()`
+- Structure definition for `mlk_shake128ctx`
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+The `fips202x4.h` header can contain stubs since the 4x functions are never called.
+
+## Notes
+
+- `MLK_CONFIG_SERIAL_FIPS202_ONLY` may reduce performance on CPUs with SIMD support
+- Matrix 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
+
+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/custom_backend/README.md

@@ -1,38 +1,69 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Using a custom configuration and FIPS-202 backend
+# Custom FIPS-202 Backend
 
-This directory contains a minimal example for how to use mlkem-native as a code package, with a custom FIPS-202
-backend and a custom configuration. We use [^tiny_sha3] as an example.
+This directory contains a minimal example for using mlkem-native with a custom FIPS-202 *backend*
+(as opposed to a complete custom FIPS-202 implementation). We use tiny_sha3[^tiny_sha3] as an example.
+
+## Use Case
+
+Use this approach when:
+- You want to replace the low-level Keccak-f1600 permutation
+- You want to keep mlkem-native's FIPS-202 frontend (absorb/squeeze logic)
+
+This differs from `bring_your_own_fips202` in that you only replace the *backend* (Keccak permutation),
+not the entire FIPS-202 implementation.
 
 ## Components
 
-An application using mlkem-native with a custom FIPS-202 backend and custom configuration needs the following:
-
-1. Arithmetic part of the mlkem-native source tree: [`mlkem/src/`](../../mlkem/src). In this example, we disable arithmetic
-   backends, hence it is safe to remove the entire `native` subfolder.
-2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mlkem/src/randombytes.h). **WARNING:** The
-   `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation outside of testing.
-3. FIPS-202 part of the mlkem-native source tree, [`fips202/`](../../mlkem/src/fips202). If you only want to use your backend,
-   you can remove all existing backends; that's what this example does.
-4. A custom FIPS-202 backend. In this example, the backend file is
-   [custom.h](mlkem_native/src/fips202/native/custom/custom.h), wrapping
-   [sha3.c](mlkem_native/src/fips202/native/custom/src/sha3.c) and setting `MLK_USE_FIPS202_X1_NATIVE` to indicate that we
-   replace 1-fold Keccak-F1600.
-5. Either modify the existing [mlkem_native_config.h](mlkem_native/mlkem_native_config.h), or register a new config.
-   In this example, we modify [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) directly. For the sake of
-   demonstration, we set a custom namespace. We set `MLK_CONFIG_FIPS202_BACKEND_FILE` to point to our custom FIPS-202
-   backend, but leave `MLK_CONFIG_USE_NATIVE_BACKEND_ARITH` undefined to indicate that we wish to use the C backend.
-
-## Note
-
-The tiny_sha3 code uses a byte-reversed presentation of the Keccakf1600 state for big-endian targets. Since
-mlkem-native's FIPS202 frontend assumes a standard presentation, the corresponding byte-reversal in
-[sha3.c](mlkem_native/src/fips202/native/custom/src/sha3.c) is removed.
+1. Arithmetic part of mlkem-native: [`mlkem/src/`](../../mlkem/src)
+2. FIPS-202 frontend: [`mlkem/src/fips202/`](../../mlkem/src/fips202) (can remove existing backends)
+3. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h)
+4. Custom FIPS-202 backend (see below)
+5. Your application source code
+
+## Configuration
+
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202`: Enables native FIPS-202 backend
+- `MLK_CONFIG_FIPS202_BACKEND_FILE`: Path to your custom backend metadata file
+
+A custom backend consists of:
+1. A metadata header (e.g., [custom.h](mlkem_native/src/fips202/native/custom/custom.h)) that:
+   - Sets `MLK_USE_FIPS202_X1_NATIVE` (and/or `X2`/`X4`) to indicate which functions are replaced
+   - Includes the implementation header
+2. An implementation providing `mlk_keccakf1600_native()` (and/or batched variants)
+
+Example backend metadata file:
+```c
+#ifndef CUSTOM_FIPS202_BACKEND_H
+#define CUSTOM_FIPS202_BACKEND_H
+
+/* Indicate we're replacing 1-fold Keccak-f1600 */
+#define MLK_USE_FIPS202_X1_NATIVE
+
+/* Include the implementation */
+#include "custom/src/keccak_impl.h"
+
+#endif
+```
+
+## Notes
+
+- The tiny_sha3 code uses byte-reversed Keccak state on big-endian targets; this example removes
+  that reversal since mlkem-native's frontend assumes standard byte order
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
+
+## Warning
+
+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/monolithic_build/README.md

@@ -1,20 +1,46 @@
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
-# Single-level mlkem-native in a single compilation unit
+# Monolithic Build (C Backend)
 
-This directory contains a minimal example for how to build a single instance of mlkem-native in a single compilation
-unit. Only the C-backend is exercised.
+This directory contains a minimal example for building mlkem-native as a single compilation unit
+using the auto-generated `mlkem_native.c` file.
 
-The auto-generated source file [mlkem_native.c](mlkem_native/mlkem_native.c) includes all mlkem-native C source
-files. Moreover, it clears all `#define`s clauses set by mlkem-native at the end, and is hence amenable to multiple
-inclusion in another compilation unit. It exposes the API [mlkem_native.h](mlkem_native/mlkem_native.h).
+## Use Case
 
-The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets
-`MLK_CONFIG_INTERNAL_API_QUALIFIER` to `static`, making all internal functions static for the single-CU build.
+Use this approach when:
+- You want the simplest possible build integration (one `.c` file)
+- You're using only C (no native backends)
+
+## Components
+
+1. Auto-generated [mlkem_native.c](mlkem_native/mlkem_native.c) (includes all C sources)
+2. A secure random number generator implementing [`randombytes.h`](../../mlkem/src/randombytes.h)
+3. Your application source code
+
+## Configuration
+
+The configuration file [mlkem_native_config.h](mlkem_native/mlkem_native_config.h) sets:
+- `MLK_CONFIG_PARAMETER_SET`: Security level (default 768)
+- `MLK_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mlkem`)
+- `MLK_CONFIG_INTERNAL_API_QUALIFIER=static`: Makes internal functions static for single-CU builds
+
+The auto-generated `mlkem_native.c`:
+- Includes all mlkem-native C source files
+- Clears all internal `#define`s at the end, allowing multiple inclusion
+
+## Notes
+
+- The monolithic `.c` file is auto-generated by `scripts/autogen`
+- Internal functions become `static`, enabling better compiler optimization
 
 ## Usage
 
-Build this example with `make build`, run with `make run`.
+```bash
+make build   # Build the example
+make run     # Run the example
+```
+
+## Warning
 
-**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
-outside of testing.
+The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
+You MUST provide a cryptographically secure RNG for production use.