API: add failure mode support for randombytes()

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

@@ -65,6 +65,7 @@ runs:
         extra_env: 'ASAN_OPTIONS=detect_leaks=1'
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom zeroization (explicit_bzero)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-zeroize') }}
       uses: ./.github/actions/multi-functest
@@ -79,6 +80,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom native capability functions (static ON)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'native-cap-ON') }}
       uses: ./.github/actions/multi-functest
@@ -93,6 +95,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom native capability functions (static OFF)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'native-cap-OFF') }}
       uses: ./.github/actions/multi-functest
@@ -107,6 +110,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom native capability functions (ID_AA64PFR1_EL1 detection)"
       if: ${{ (inputs.tests == 'all' || contains(inputs.tests, 'native-cap-ID_AA64PFR1_EL1')) && runner.os == 'Linux' && runner.arch == 'ARM64' }}
       uses: ./.github/actions/multi-functest
@@ -121,6 +125,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom native capability functions (CPUID AVX2 detection)"
       if: ${{ (inputs.tests == 'all' || contains(inputs.tests, 'native-cap-CPUID_AVX2')) && runner.os == 'Linux' && runner.arch == 'X64' }}
       uses: ./.github/actions/multi-functest
@@ -135,6 +140,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "No ASM"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'no-asm') }}
       uses: ./.github/actions/multi-functest
@@ -149,6 +155,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Serial FIPS202 (no batched Keccak)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'serial-fips202') }}
       uses: ./.github/actions/multi-functest
@@ -163,6 +170,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom randombytes"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-randombytes') }}
       uses: ./.github/actions/multi-functest
@@ -177,6 +185,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom memcpy"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-memcpy') }}
       uses: ./.github/actions/multi-functest
@@ -191,6 +200,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom memset"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-memset') }}
       uses: ./.github/actions/multi-functest
@@ -205,6 +215,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "Custom stdlib (memcpy + memset)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-stdlib') }}
       uses: ./.github/actions/multi-functest
@@ -219,6 +230,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config
     - name: "MLKEM_GEN_MATRIX_NBLOCKS=1"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-1') }}
       uses: ./.github/actions/multi-functest

.github/actions/functest/action.yml

@@ -59,6 +59,9 @@ inputs:
   alloc:
     description: Determine whether to run alloc tests or not
     default: "true"
+  rng_fail:
+    description: Determine whether to run rng fail tests or not
+    default: "true"
   extra_args:
     description: Additional arguments to pass to the tests script
     default: ""
@@ -80,6 +83,7 @@ runs:
           echo EXAMPLES="${{ inputs.examples == 'true' && 'examples' || 'no-examples' }}" >> $GITHUB_ENV
           echo STACK="${{ inputs.stack == 'true' && 'stack' || 'no-stack' }}" >> $GITHUB_ENV
           echo ALLOC="${{ inputs.alloc == 'true' && 'alloc' || 'no-alloc' }}" >> $GITHUB_ENV
+          echo RNGFAIL="${{ inputs.rng_fail == 'true' && 'rng-fail' || 'no-rng-fail' }}" >> $GITHUB_ENV
       - name: Setup nix
         uses: ./.github/actions/setup-shell
         with:
@@ -110,11 +114,11 @@ runs:
             - $(python3 --version)
             - $(${{ inputs.cross_prefix }}${CC} --version | grep -m1 "")
           EOF
-      - name: ${{ env.MODE }} ${{ inputs.opt }} tests (${{ env.FUNC }}, ${{ env.KAT }}, ${{ env.EXAMPLES }}, ${{ env.STACK }}, ${{ env.UNIT }}, ${{ env.ALLOC }})
+      - name: ${{ env.MODE }} ${{ inputs.opt }} tests (${{ env.FUNC }}, ${{ env.KAT }}, ${{ env.EXAMPLES }}, ${{ env.STACK }}, ${{ env.UNIT }}, ${{ env.ALLOC }}, ${{ env.RNGFAIL }})
         shell: ${{ env.SHELL }}
         run: |
           make clean
-          ${{ inputs.extra_env }} ./scripts/tests all ${{ inputs.check_namespace == 'true' && '--check-namespace' || ''}} --exec-wrapper="${{ inputs.exec_wrapper }}" --cross-prefix="${{ inputs.cross_prefix }}" --cflags="${{ inputs.cflags }}" --ldflags="${{ inputs.ldflags }}" --opt=${{ inputs.opt }} --${{ env.FUNC }} --${{ env.KAT }} --${{ env.ACVP }} --${{ env.EXAMPLES }} --${{ env.STACK }} --${{ env.UNIT }} --${{ env.ALLOC }} -v ${{ inputs.extra_args }}
+          ${{ inputs.extra_env }} ./scripts/tests all ${{ inputs.check_namespace == 'true' && '--check-namespace' || ''}} --exec-wrapper="${{ inputs.exec_wrapper }}" --cross-prefix="${{ inputs.cross_prefix }}" --cflags="${{ inputs.cflags }}" --ldflags="${{ inputs.ldflags }}" --opt=${{ inputs.opt }} --${{ env.FUNC }} --${{ env.KAT }} --${{ env.ACVP }} --${{ env.EXAMPLES }} --${{ env.STACK }} --${{ env.UNIT }} --${{ env.ALLOC }} --${{ env.RNGFAIL }} -v ${{ inputs.extra_args }}
       - name: Post ${{ env.MODE }} Tests
         shell: ${{ env.SHELL }}
         if: success() || failure()

.github/actions/multi-functest/action.yml

@@ -56,6 +56,9 @@ inputs:
   alloc:
     description: Determine whether to run alloc tests or not
     default: "true"
+  rng_fail:
+    description: Determine whether to run rng fail tests or not
+    default: "true"
   extra_args:
     description: Additional arguments to pass to the tests script
     default: ""
@@ -85,6 +88,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross x86_64 Tests
@@ -109,6 +113,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross aarch64 Tests
@@ -133,6 +138,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross ppc64le Tests
@@ -157,6 +163,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross aarch64_be Tests
@@ -181,6 +188,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross riscv64 Tests (RVV, VLEN=128)
@@ -205,6 +213,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross riscv64 Tests (RVV, VLEN=256)
@@ -228,6 +237,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross riscv64 Tests (RVV, VLEN=512)
@@ -251,6 +261,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross riscv64 Tests (RVV, VLEN=1024)
@@ -274,6 +285,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
       - name: Cross riscv32 Tests

.github/workflows/baremetal.yml

@@ -49,3 +49,4 @@ jobs:
           examples: false
           stack: false
           alloc: ${{ matrix.target.alloc }}
+          rng_fail: false

Makefile

@@ -1,14 +1,14 @@
 # Copyright (c) The mlkem-native project authors
 # SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
 
-.PHONY: func kat acvp stack alloc \
-	func_512 kat_512 acvp_512 stack_512 alloc_512 \
-	func_768 kat_768 acvp_768 stack_768 alloc_768 \
-	func_1024 kat_1024 acvp_1024 stack_1024 alloc_1024 \
-	run_func run_kat run_acvp run_stack run_alloc \
-	run_func_512 run_kat_512 run_stack_512 run_alloc_512 \
-	run_func_768 run_kat_768 run_stack_768 run_alloc_768 \
-	run_func_1024 run_kat_1024 run_stack_1024 run_alloc_1024 \
+.PHONY: func kat acvp stack alloc rng_fail \
+	func_512 kat_512 acvp_512 stack_512 alloc_512 rng_fail_512 \
+	func_768 kat_768 acvp_768 stack_768 alloc_768 rng_fail_768 \
+	func_1024 kat_1024 acvp_1024 stack_1024 alloc_1024 rng_fail_1024 \
+	run_func run_kat run_acvp run_stack run_alloc run_rng_fail \
+	run_func_512 run_kat_512 run_stack_512 run_alloc_512 run_rng_fail_512 \
+	run_func_768 run_kat_768 run_stack_768 run_alloc_768 run_rng_fail_768 \
+	run_func_1024 run_kat_1024 run_stack_1024 run_alloc_1024 run_rng_fail_1024 \
 	bench_512 bench_768 bench_1024 bench \
 	run_bench_512 run_bench_768 run_bench_1024 run_bench \
 	bench_components_512 bench_components_768 bench_components_1024 bench_components \
@@ -47,7 +47,7 @@ quickcheck: test
 build: func kat acvp
 	$(Q)echo "  Everything builds fine!"
 
-test: run_kat run_func run_acvp run_unit run_alloc
+test: run_kat run_func run_acvp run_unit run_alloc run_rng_fail
 	$(Q)echo "  Everything checks fine!"
 
 # Detect available SHA256 command
@@ -156,6 +156,22 @@ run_alloc_1024: alloc_1024
 	$(W) $(MLKEM1024_DIR)/bin/test_alloc1024
 run_alloc: run_alloc_512 run_alloc_768 run_alloc_1024
 
+rng_fail_512: $(MLKEM512_DIR)/bin/test_rng_fail512
+	$(Q)echo "  RNG_FAIL   ML-KEM-512:   $^"
+rng_fail_768: $(MLKEM768_DIR)/bin/test_rng_fail768
+	$(Q)echo "  RNG_FAIL   ML-KEM-768:   $^"
+rng_fail_1024: $(MLKEM1024_DIR)/bin/test_rng_fail1024
+	$(Q)echo "  RNG_FAIL   ML-KEM-1024:  $^"
+rng_fail: rng_fail_512 rng_fail_768 rng_fail_1024
+
+run_rng_fail_512: rng_fail_512
+	$(W) $(MLKEM512_DIR)/bin/test_rng_fail512
+run_rng_fail_768: rng_fail_768
+	$(W) $(MLKEM768_DIR)/bin/test_rng_fail768
+run_rng_fail_1024: rng_fail_1024
+	$(W) $(MLKEM1024_DIR)/bin/test_rng_fail1024
+run_rng_fail: run_rng_fail_512 run_rng_fail_768 run_rng_fail_1024
+
 lib: $(BUILD_DIR)/libmlkem.a $(BUILD_DIR)/libmlkem512.a $(BUILD_DIR)/libmlkem768.a $(BUILD_DIR)/libmlkem1024.a
 
 # Enforce setting CYCLES make variable when

examples/basic_deterministic/mlkem_native/mlkem_native_config.h

@@ -409,7 +409,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -420,9 +420,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h

@@ -409,7 +409,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -420,9 +420,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h

@@ -410,7 +410,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -421,9 +421,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/custom_backend/mlkem_native/mlkem_native_config.h

@@ -405,7 +405,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -416,9 +416,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/monolithic_build/mlkem_native/mlkem_native_config.h

@@ -408,7 +408,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -419,9 +419,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h

@@ -410,7 +410,7 @@
  *              consumer.
  *
  *              If this option is not set, mlkem-native expects a function
- *              void randombytes(uint8_t *out, size_t outlen).
+ *              int randombytes(uint8_t *out, size_t outlen).
  *
  *              Set this option and define `mlk_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -421,9 +421,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/sys.h"
-   static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)
+   static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */