API: add failure mode support for randombytes()

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

@@ -62,6 +62,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
@@ -76,6 +77,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
@@ -90,6 +92,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
@@ -104,6 +107,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
@@ -118,6 +122,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
@@ -132,6 +137,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
@@ -146,6 +152,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
@@ -160,6 +167,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
@@ -174,6 +182,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
@@ -188,6 +197,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
@@ -202,6 +212,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
@@ -216,3 +227,4 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        rng_fail: false # Requires custom config

.github/actions/functest/action.yml

@@ -60,6 +60,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: ""
@@ -81,6 +84,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:
@@ -111,11 +115,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

@@ -57,6 +57,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: ""
@@ -86,6 +89,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
@@ -110,6 +114,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
@@ -134,6 +139,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
@@ -158,6 +164,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
@@ -182,6 +189,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)
@@ -206,6 +214,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)
@@ -229,6 +238,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)
@@ -252,6 +262,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)
@@ -275,6 +286,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
@@ -299,6 +311,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 }}
 

.github/workflows/baremetal.yml

@@ -36,3 +36,4 @@ jobs:
           examples: false
           stack: false
           alloc: false
+          rng_fail: false

BIBLIOGRAPHY.md

@@ -53,6 +53,7 @@ source code and documentation.
   - [test/no_asm_config.h](test/no_asm_config.h)
   - [test/serial_fips202_config.h](test/serial_fips202_config.h)
   - [test/test_alloc_config.h](test/test_alloc_config.h)
+  - [test/test_rng_fail_config.h](test/test_rng_fail_config.h)
 
 ### `FIPS202`
 
@@ -107,6 +108,7 @@ source code and documentation.
   - [test/no_asm_config.h](test/no_asm_config.h)
   - [test/serial_fips202_config.h](test/serial_fips202_config.h)
   - [test/test_alloc_config.h](test/test_alloc_config.h)
+  - [test/test_rng_fail_config.h](test/test_rng_fail_config.h)
 
 ### `HYBRID`
 

Makefile

@@ -2,14 +2,14 @@
 # Copyright (c) The mldsa-native project authors
 # SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
 
-.PHONY: func kat acvp stack unit alloc \
-	func_44 kat_44 acvp_44 stack_44 unit_44 alloc_44 \
-	func_65 kat_65 acvp_65 stack_65 unit_65 alloc_65 \
-	func_87 kat_87 acvp_87 stack_87 unit_87 alloc_87 \
-	run_func run_kat run_acvp run_stack run_unit run_alloc \
-	run_func_44 run_kat_44 run_stack_44 run_unit_44 run_alloc_44 \
-	run_func_65 run_kat_65 run_stack_65 run_unit_65 run_alloc_65 \
-	run_func_87 run_kat_87 run_stack_87 run_unit_87 run_alloc_87 \
+.PHONY: func kat acvp stack unit alloc rng_fail \
+	func_44 kat_44 acvp_44 stack_44 unit_44 alloc_44 rng_fail_44 \
+	func_65 kat_65 acvp_65 stack_65 unit_65 alloc_65 rng_fail_65 \
+	func_87 kat_87 acvp_87 stack_87 unit_87 alloc_87 rng_fail_87 \
+	run_func run_kat run_acvp run_stack run_unit run_alloc run_rng_fail \
+	run_func_44 run_kat_44 run_stack_44 run_unit_44 run_alloc_44 run_rng_fail_44 \
+	run_func_65 run_kat_65 run_stack_65 run_unit_65 run_alloc_65 run_rng_fail_65 \
+	run_func_87 run_kat_87 run_stack_87 run_unit_87 run_alloc_87 run_rng_fail_87 \
 	bench_44 bench_65 bench_87 bench \
 	run_bench_44 run_bench_65 run_bench_87 run_bench \
 	bench_components_44 bench_components_65 bench_components_87 bench_components \
@@ -48,7 +48,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
@@ -157,6 +157,22 @@ run_alloc_87: alloc_87
 	$(W) $(MLDSA87_DIR)/bin/test_alloc87
 run_alloc: run_alloc_44 run_alloc_65 run_alloc_87
 
+rng_fail_44: $(MLDSA44_DIR)/bin/test_rng_fail44
+	$(Q)echo "  RNG_FAIL   ML-DSA-44:   $^"
+rng_fail_65: $(MLDSA65_DIR)/bin/test_rng_fail65
+	$(Q)echo "  RNG_FAIL   ML-DSA-65:   $^"
+rng_fail_87: $(MLDSA87_DIR)/bin/test_rng_fail87
+	$(Q)echo "  RNG_FAIL   ML-DSA-87:  $^"
+rng_fail: rng_fail_44 rng_fail_65 rng_fail_87
+
+run_rng_fail_44: rng_fail_44
+	$(W) $(MLDSA44_DIR)/bin/test_rng_fail44
+run_rng_fail_65: rng_fail_65
+	$(W) $(MLDSA65_DIR)/bin/test_rng_fail65
+run_rng_fail_87: rng_fail_87
+	$(W) $(MLDSA87_DIR)/bin/test_rng_fail87
+run_rng_fail: run_rng_fail_44 run_rng_fail_65 run_rng_fail_87
+
 lib: $(BUILD_DIR)/libmldsa.a $(BUILD_DIR)/libmldsa44.a $(BUILD_DIR)/libmldsa65.a $(BUILD_DIR)/libmldsa87.a
 
 # Enforce setting CYCLES make variable when

examples/basic_deterministic/mldsa_native/mldsa_native_config.h

@@ -406,7 +406,7 @@
  *              consumer.
  *
  *              If this option is not set, mldsa-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 `mld_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -417,9 +417,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/src.h"
-   static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len)
+   static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/basic_lowram/mldsa_native/mldsa_native_config.h

@@ -405,7 +405,7 @@
  *              consumer.
  *
  *              If this option is not set, mldsa-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 `mld_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/src.h"
-   static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len)
+   static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h

@@ -406,7 +406,7 @@
  *              consumer.
  *
  *              If this option is not set, mldsa-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 `mld_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -417,9 +417,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/src.h"
-   static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len)
+   static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h

@@ -407,7 +407,7 @@
  *              consumer.
  *
  *              If this option is not set, mldsa-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 `mld_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -418,9 +418,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/src.h"
-   static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len)
+   static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */

examples/custom_backend/mldsa_native/mldsa_native_config.h

@@ -402,7 +402,7 @@
  *              consumer.
  *
  *              If this option is not set, mldsa-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 `mld_randombytes` if you want to
  *              use a custom method to sample randombytes with a different name
@@ -413,9 +413,10 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "src/src.h"
-   static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len)
+   static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len)
    {
        ... your implementation ...
+       return 0;
    }
    #endif
 */