Make tests and examples compatible with reduced-API configurations

The previous tests and examples assumed all APIs (keygen, encaps,
decaps) were always available: encaps tests generated a keypair as
setup, decaps tests generated a keypair and ciphertext as setup, and
the alloc test required keygen for every test function. This made them
incompatible with reduced-API configurations where some APIs are
disabled via MLK_CONFIG_NO_KEYPAIR_API, MLK_CONFIG_NO_ENCAPS_API, or
MLK_CONFIG_NO_DECAPS_API.

This commit introduces auto-generated test vectors and refactors all
tests and examples so that each operation (keygen, encaps, decaps) can
be tested independently using pre-computed test vectors.

scripts/notrandombytes:
- Add Python implementation of the SURF-based deterministic test PRNG,
  matching the C version in test/notrandombytes/
- Used by autogen --test-vectors to generate reproducible randomness
  for test vector generation

Test vector generation (scripts/autogen --test-vectors):
- Add --test-vectors flag to scripts/autogen that invokes the ACVP
  binaries with randomness from scripts/notrandombytes to generate
  test/test_vectors/expected_test_vectors.h and the multilevel variant
- Generate pk, sk, ct, ss vectors for all three parameter sets
  (512, 768, 1024)
- Include z, d, m byte-arrays in the header so consumers don't need
  to hardcode them
- Array dimensions are explicit in the generated header

Test changes (test_mlkem.c):
- The existing tests (test_keys, test_invalid_pk, etc.) require all
  three APIs and are left unchanged, guarded by
  !MLK_CONFIG_NO_KEYPAIR_API && !MLK_CONFIG_NO_ENCAPS_API &&
  !MLK_CONFIG_NO_DECAPS_API
- Add test_kem_expected() as a new minimal test that works in
  reduced-API configurations: each block (keygen, encaps, decaps) is
  independently guarded and uses test vectors directly, so e.g. the
  decaps block can run without keygen by using test_vector_sk

test_alloc.c and test_rng_fail.c:
- Both files exercise the same 7 API entry points (keypair_derand,
  keypair, enc_derand, enc, check_pk, dec, check_sk), each
  independently guarded by the minimal required API
- Encaps tests use test_vector_pk directly (no keygen dependency)
- Decaps tests use test_vector_sk/ct directly (no keygen or encaps
  dependency)
- main() uses r |= pattern for error accumulation

test_stack.c:
- Guard each test function (keygen/encaps/decaps stack measurement)
  by the matching API config; unavailable modes print SKIPPED

gen_KAT/wycheproof/acvp:
- KAT and Wycheproof stub out to a SKIPPED main() when any API is
  disabled (they inherently need all three)
- ACVP guards each mode (keyGen / encapDecap encapsulation /
  encapDecap decapsulation / encapsulationKeyCheck /
  decapsulationKeyCheck) by the matching API config, so it builds
  and works in any subset

Example refactoring:
- Hoist test logic into static example_xxx() functions with
  #if/#else/#endif guards and SKIPPED stubs for disabled APIs
- main() is a flat sequence of r |= example_xxx() calls
- example_end_to_end runs the full keygen->encaps->decaps flow only
  when all three APIs are enabled; example_expected_vectors runs
  independent keygen/encaps/decaps KAT checks for whichever APIs are
  enabled
- Multilevel examples use per-level static functions (test_expected_512,
  test_expected_768, test_expected_1024) with the same per-API guards
- basic_deterministic uses test_vector_z/d/m from the header instead
  of hardcoded byte arrays
- Add expected_test_vectors.h symlink (single- or multi-level) in each
  example directory pointing to test/test_vectors/

CI (config-variations):
- Add keygen-only, encaps-only, decaps-only, keygen-encaps, keygen-decaps,
  encaps-decaps test configurations, covering all 6 combinations of
  1 or 2 enabled APIs from {keygen, encaps, decaps}

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

Author: hanno-becker

.github/actions/config-variations/action.yml

@@ -11,7 +11,7 @@ inputs:
     description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled,
     pct-enabled-broken, custom-alloc-heap, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1,
     native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib,
-    nblocks-1, nblocks-2, nblocks-4'
+    nblocks-1, nblocks-2, nblocks-4, keygen-only, encaps-only, decaps-only, keygen-encaps, keygen-decaps, encaps-decaps'
     required: false
     default: 'all'
   opt:
@@ -276,3 +276,93 @@ runs:
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
         rng_fail: true
+    - name: "Keygen-only API"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'keygen-only') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_ENCAPS_API -DMLK_CONFIG_NO_DECAPS_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true
+    - name: "Encaps-only API"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'encaps-only') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_KEYPAIR_API -DMLK_CONFIG_NO_DECAPS_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true
+    - name: "Decaps-only API"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'decaps-only') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_KEYPAIR_API -DMLK_CONFIG_NO_ENCAPS_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true
+    - name: "Keygen+Encaps API (no decaps)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'keygen-encaps') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_DECAPS_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true
+    - name: "Keygen+Decaps API (no encaps)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'keygen-decaps') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_ENCAPS_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true
+    - name: "Encaps+Decaps API (no keygen)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'encaps-decaps') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-DMLK_CONFIG_NO_KEYPAIR_API -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        stack: true
+        rng_fail: true
+        opt: ${{ inputs.opt }}
+        examples: true

META.py

@@ -5,7 +5,9 @@
 # Checks the KAT output of a gen_KAT binary against META.yml.
 #
 # Reads the KAT bytes from stdin, hashes them with SHA-256, and compares
-# against the kat-sha256 field for the given scheme in META.yml.
+# against the kat-sha256 field for the given scheme in META.yml. If stdin is
+# "SKIPPED" (emitted by gen_KAT for reduced-API builds), the check is reported
+# as skipped.
 #
 # To run manually, pipe a gen_KAT binary into it, e.g.:
 #
@@ -53,9 +55,16 @@ def main():
         err(f"META.yml: no kat-sha256 entry for {scheme_name}")
         sys.exit(1)
 
-    # Hash the raw bytes piped in from gen_KAT on stdin. Read in binary mode so
+    # Read the raw bytes piped in from gen_KAT on stdin. Read in binary mode so
     # that no newline translation occurs on Windows.
-    computed = hashlib.sha256(sys.stdin.buffer.read()).hexdigest()
+    data = sys.stdin.buffer.read()
+
+    # Reduced-API builds emit "SKIPPED" instead of KAT bytes; report as skipped.
+    if data.startswith(b"SKIPPED"):
+        info(f"META.yml {scheme_name} kat-sha256: SKIPPED")
+        sys.exit(0)
+
+    computed = hashlib.sha256(data).hexdigest()
 
     if computed == ref:
         info(f"META.yml {scheme_name} kat-sha256: OK")

examples/basic/expected_test_vectors.h

@@ -0,0 +1 @@
+../../test/test_vectors/expected_test_vectors.h

examples/basic/main.c

@@ -6,13 +6,9 @@
 #include <stdio.h>
 #include <string.h>
 
-/* Import public mlkem-native API
- *
- * This requires specifying the parameter set and namespace prefix
- * used for the build.
- */
+/* Import public mlkem-native API */
+#include "expected_test_vectors.h"
 #include "mlkem_native/mlkem_native.h"
-
 #include "test_only_rng/notrandombytes.h"
 
 #define CHECK(x)                                              \
@@ -27,80 +23,81 @@
     }                                                         \
   } while (0)
 
-int main(void)
+#if !defined(MLK_CONFIG_NO_KEYPAIR_API) && \
+    !defined(MLK_CONFIG_NO_RANDOMIZED_API)
+static int example_keygen(void)
 {
   uint8_t pk[CRYPTO_PUBLICKEYBYTES];
   uint8_t sk[CRYPTO_SECRETKEYBYTES];
-  uint8_t ct[CRYPTO_CIPHERTEXTBYTES];
-  uint8_t key_a[CRYPTO_BYTES];
-  uint8_t key_b[CRYPTO_BYTES];
-
-  /* The PCT modifies the PRNG state, so the KAT tests don't work.
-   * We run KAT tests only for disabled PCT. */
-#if !defined(MLK_CONFIG_KEYGEN_PCT)
-#if MLK_CONFIG_PARAMETER_SET == 512
-  const uint8_t expected_key[] = {
-      0x77, 0x6c, 0x74, 0xdf, 0x30, 0x1f, 0x8d, 0x82, 0x52, 0x5e, 0x8e,
-      0xbb, 0xb4, 0x00, 0x95, 0xcd, 0x2e, 0x92, 0xdf, 0x6d, 0xc9, 0x33,
-      0xe7, 0x86, 0x62, 0x59, 0xf5, 0x31, 0xc7, 0x35, 0x0a, 0xd5};
-#elif MLK_CONFIG_PARAMETER_SET == 768
-  const uint8_t expected_key[] = {
-      0xe9, 0x13, 0x77, 0x84, 0x0e, 0x6b, 0x66, 0x94, 0xea, 0xa9, 0xf0,
-      0x1c, 0x97, 0xff, 0x68, 0x87, 0x4e, 0x8b, 0x0c, 0x52, 0x0b, 0x00,
-      0xc2, 0xcd, 0xe3, 0x7c, 0x4f, 0xc2, 0x39, 0x62, 0x6e, 0x70};
-#elif MLK_CONFIG_PARAMETER_SET == 1024
-  const uint8_t expected_key[] = {
-      0x5d, 0x9e, 0x23, 0x5f, 0xcc, 0xb2, 0xb3, 0x49, 0x9a, 0x5f, 0x49,
-      0x0a, 0x56, 0xe3, 0xf0, 0xd3, 0xfd, 0x9b, 0x58, 0xbd, 0xa2, 0x8b,
-      0x69, 0x0f, 0x91, 0xb5, 0x7b, 0x88, 0xa5, 0xa8, 0x0b, 0x90};
-#endif /* MLK_CONFIG_PARAMETER_SET == 1024 */
-#endif /* !MLK_CONFIG_KEYGEN_PCT */
 
-  /* WARNING: Test-only
-   * Normally, you would want to seed a PRNG with trustworthy entropy here. */
-  randombytes_reset();
-
-  printf("Generating keypair ... ");
-
-  /* Alice generates a public key */
+  printf("Generating keypair... ");
   CHECK(crypto_kem_keypair(pk, sk) == 0);
-
+  CHECK(memcmp(pk, test_vector_pk, CRYPTO_PUBLICKEYBYTES) == 0);
+  CHECK(memcmp(sk, test_vector_sk, CRYPTO_SECRETKEYBYTES) == 0);
   printf("DONE\n");
-  printf("Encaps... ");
+  return 0;
+}
+#else  /* !MLK_CONFIG_NO_KEYPAIR_API && !MLK_CONFIG_NO_RANDOMIZED_API */
+static int example_keygen(void)
+{
+  printf("Generating keypair... SKIPPED (keygen API disabled)\n");
+  return 0;
+}
+#endif /* !(!MLK_CONFIG_NO_KEYPAIR_API && !MLK_CONFIG_NO_RANDOMIZED_API) */
 
-  /* Bob derives a secret key and creates a response */
-  CHECK(crypto_kem_enc(ct, key_b, pk) == 0);
+#if !defined(MLK_CONFIG_NO_ENCAPS_API) && !defined(MLK_CONFIG_NO_RANDOMIZED_API)
+static int example_encaps(void)
+{
+  uint8_t ct[CRYPTO_CIPHERTEXTBYTES];
+  uint8_t ss[CRYPTO_BYTES];
 
+  printf("Encaps... ");
+  CHECK(crypto_kem_enc(ct, ss, test_vector_pk) == 0);
+  CHECK(memcmp(ct, test_vector_ct, CRYPTO_CIPHERTEXTBYTES) == 0);
+  CHECK(memcmp(ss, test_vector_ss, CRYPTO_BYTES) == 0);
   printf("DONE\n");
-  printf("Decaps... ");
+  return 0;
+}
+#else  /* !MLK_CONFIG_NO_ENCAPS_API && !MLK_CONFIG_NO_RANDOMIZED_API */
+static int example_encaps(void)
+{
+  printf("Encaps... SKIPPED (encaps API disabled)\n");
+  return 0;
+}
+#endif /* !(!MLK_CONFIG_NO_ENCAPS_API && !MLK_CONFIG_NO_RANDOMIZED_API) */
 
-  /* Alice uses Bobs response to get her shared key */
-  CHECK(crypto_kem_dec(key_a, ct, sk) == 0);
+#if !defined(MLK_CONFIG_NO_DECAPS_API)
+static int example_decaps(void)
+{
+  uint8_t ss[CRYPTO_BYTES];
 
+  printf("Decaps... ");
+  CHECK(crypto_kem_dec(ss, test_vector_ct, test_vector_sk) == 0);
+  CHECK(memcmp(ss, test_vector_ss, CRYPTO_BYTES) == 0);
   printf("DONE\n");
-  printf("Compare... ");
-
-  CHECK(memcmp(key_a, key_b, CRYPTO_BYTES) == 0);
+  return 0;
+}
+#else  /* !MLK_CONFIG_NO_DECAPS_API */
+static int example_decaps(void)
+{
+  printf("Decaps... SKIPPED (decaps API disabled)\n");
+  return 0;
+}
+#endif /* MLK_CONFIG_NO_DECAPS_API */
 
-  printf("Shared secret: ");
-  {
-    size_t i;
-    for (i = 0; i < sizeof(key_a); i++)
-    {
-      printf("%02x", key_a[i]);
-    }
-  }
-  printf("\n");
+int main(void)
+{
+  int r = 0;
 
-#if !defined(MLK_CONFIG_KEYGEN_PCT)
-  /* Check against hardcoded result to make sure that
-   * we integrated custom FIPS202 correctly */
-  CHECK(memcmp(key_a, expected_key, CRYPTO_BYTES) == 0);
-#else
-  printf(
-      "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n");
-#endif
+  /* WARNING: Test-only
+   * Normally, you would seed a PRNG _once_ with trustworthy entropy and not
+   * reseed it afterwards. Here, we reseed before each API call to make each
+   * test independent and reproducible even when some API is disabled. */
+  randombytes_reset();
+  r |= example_keygen();
+  randombytes_reset();
+  r |= example_encaps();
+  r |= example_decaps();
 
-  printf("OK\n");
-  return 0;
+  return r;
 }

examples/basic_deterministic/expected_test_vectors.h

@@ -0,0 +1 @@
+../../test/test_vectors/expected_test_vectors.h