API: add failure mode support for randombytes()

L-series · L-series · commit 2e24d9ee1db3 · 2025-12-01T17:10:12.000-05:00
Change randombytes() to return int (0 on success, non-zero on failure)
instead of void, allowing callers to detect and handle RNG failures.

Updated function signature, all call sites to check return
values and test files to use CHECK macro.

Signed-off-by: Andreas Hatziiliou &lt;andreas.hatziiliou@savoirfairelinux.com&gt;
diff --git a/examples/monolithic_build_multilevel_native/multilevel_config.h b/examples/monolithic_build_multilevel_native/multilevel_config.h
@@ -327,9 +327,9 @@
 #include <stdint.h>
 #include "sys.h"
 #include "test_only_rng/notrandombytes.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)
 {
-  randombytes(ptr, len);
+  return randombytes(ptr, len);
 }
 #endif /* !__ASSEMBLER__ */
 
diff --git a/integration/liboqs/config_aarch64.h b/integration/liboqs/config_aarch64.h
@@ -182,7 +182,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
@@ -194,9 +194,10 @@
 #include <oqs/rand.h>
 #include <stdint.h>
 #include "../../mlkem/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)
 {
   OQS_randombytes(ptr, len);
+  return 0;
 }
 #endif /* !__ASSEMBLER__ */
 
diff --git a/integration/liboqs/config_c.h b/integration/liboqs/config_c.h
@@ -145,7 +145,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
@@ -157,9 +157,10 @@
 #include <oqs/rand.h>
 #include <stdint.h>
 #include "../../mlkem/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)
 {
   OQS_randombytes(ptr, len);
+  return 0;
 }
 #endif /* !__ASSEMBLER__ */
 
diff --git a/integration/liboqs/config_x86_64.h b/integration/liboqs/config_x86_64.h
@@ -182,7 +182,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
@@ -194,9 +194,10 @@
 #include <oqs/rand.h>
 #include <stdint.h>
 #include "../../mlkem/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)
 {
   OQS_randombytes(ptr, len);
+  return 0;
 }
 #endif /* !__ASSEMBLER__ */
 
diff --git a/mlkem/src/config.h b/mlkem/src/config.h
@@ -294,7 +294,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
@@ -305,7 +305,7 @@
    #if !defined(__ASSEMBLER__)
    #include <stdint.h>
    #include "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 ...
    }
diff --git a/mlkem/src/kem.c b/mlkem/src/kem.c
@@ -202,7 +202,10 @@ int crypto_kem_keypair(uint8_t pk[MLKEM_INDCCA_PUBLICKEYBYTES],
   MLK_ALIGN uint8_t coins[2 * MLKEM_SYMBYTES];
 
   /* Acquire necessary randomness, and mark it as secret. */
-  mlk_randombytes(coins, 2 * MLKEM_SYMBYTES);
+  if (mlk_randombytes(coins, 2 * MLKEM_SYMBYTES) != 0)
+  {
+    return -1;
+  }
   MLK_CT_TESTING_SECRET(coins, sizeof(coins));
 
   res = crypto_kem_keypair_derand(pk, sk, coins);
@@ -263,7 +266,10 @@ int crypto_kem_enc(uint8_t ct[MLKEM_INDCCA_CIPHERTEXTBYTES],
   int res;
   MLK_ALIGN uint8_t coins[MLKEM_SYMBYTES];
 
-  mlk_randombytes(coins, MLKEM_SYMBYTES);
+  if (mlk_randombytes(coins, MLKEM_SYMBYTES) != 0)
+  {
+    return -1;
+  }
   MLK_CT_TESTING_SECRET(coins, sizeof(coins));
 
   res = crypto_kem_enc_derand(ct, ss, pk, coins);
diff --git a/mlkem/src/randombytes.h b/mlkem/src/randombytes.h
@@ -12,11 +12,11 @@
 
 #if !defined(MLK_CONFIG_NO_RANDOMIZED_API)
 #if !defined(MLK_CONFIG_CUSTOM_RANDOMBYTES)
-void randombytes(uint8_t *out, size_t outlen);
-static MLK_INLINE void mlk_randombytes(uint8_t *out, size_t outlen)
+int randombytes(uint8_t *out, size_t outlen);
+static MLK_INLINE int mlk_randombytes(uint8_t *out, size_t outlen)
 __contract__(
   requires(memory_no_alias(out, outlen))
-  assigns(memory_slice(out, outlen))) { randombytes(out, outlen); }
+  assigns(memory_slice(out, outlen))) { return randombytes(out, outlen); }
 #endif /* !MLK_CONFIG_CUSTOM_RANDOMBYTES */
 #endif /* !MLK_CONFIG_NO_RANDOMIZED_API */
 #endif /* !MLK_RANDOMBYTES_H */
diff --git a/test/bench_components_mlkem.c b/test/bench_components_mlkem.c
@@ -27,14 +27,14 @@ static int cmp_uint64_t(const void *a, const void *b)
   return (int)((*((const uint64_t *)a)) - (*((const uint64_t *)b)));
 }
 
-#define BENCH(txt, code)                                \
-  for (i = 0; i < NTESTS; i++)                          \
-  {                                                     \
-    randombytes((uint8_t *)data0, sizeof(data0));       \
-    randombytes((uint8_t *)data1, sizeof(data1));       \
-    randombytes((uint8_t *)data2, sizeof(data2));       \
-    randombytes((uint8_t *)data3, sizeof(data3));       \
-    randombytes((uint8_t *)data4, sizeof(data4));       \
+#define BENCH(txt, code)                                            \
+  for (i = 0; i < NTESTS; i++)                                      \
+  {                                                                 \
+    CHECK(randombytes((uint8_t *)data0, sizeof(data0)) == 0);       \
+    CHECK(randombytes((uint8_t *)data1, sizeof(data1)) == 0);       \
+    CHECK(randombytes((uint8_t *)data2, sizeof(data2)) == 0);       \
+    CHECK(randombytes((uint8_t *)data3, sizeof(data3)) == 0);       \
+    CHECK(randombytes((uint8_t *)data4, sizeof(data4)) == 0);       \
     for (j = 0; j < NWARMUP; j++)                       \
     {                                                   \
       code;                                             \
diff --git a/test/bench_mlkem.c b/test/bench_mlkem.c
@@ -80,8 +80,8 @@ static int bench(void)
   for (i = 0; i < NTESTS; i++)
   {
     int ret = 0;
-    randombytes(kg_rand, 2 * CRYPTO_BYTES);
-    randombytes(enc_rand, CRYPTO_BYTES);
+    CHECK(randombytes(kg_rand, 2 * CRYPTO_BYTES) == 0);
+    CHECK(randombytes(enc_rand, CRYPTO_BYTES) == 0);
 
     /* Key-pair generation */
     for (j = 0; j < NWARMUP; j++)
diff --git a/test/configs.yml b/test/configs.yml
@@ -37,9 +37,9 @@ configs:
           #include <stdint.h>
           #include "../mlkem/src/sys.h"
           #include "notrandombytes/notrandombytes.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)
           {
-            randombytes(ptr, len);
+            return randombytes(ptr, len);
           }
           #endif /* !__ASSEMBLER__ */
 
@@ -367,9 +367,9 @@ configs:
           #include <stdint.h>
           #include "sys.h"
           #include "test_only_rng/notrandombytes.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)
           {
-            randombytes(ptr, len);
+            return randombytes(ptr, len);
           }
           #endif /* !__ASSEMBLER__ */
 
diff --git a/test/notrandombytes/notrandombytes.c b/test/notrandombytes/notrandombytes.c
@@ -86,7 +86,7 @@ static void surf(void)
   }
 }
 
-void randombytes(uint8_t *buf, size_t n)
+int randombytes(uint8_t *buf, size_t n)
 {
   while (n > 0)
   {
@@ -109,4 +109,5 @@ void randombytes(uint8_t *buf, size_t n)
     ++buf;
     --n;
   }
+  return 0;
 }
diff --git a/test/notrandombytes/notrandombytes.h b/test/notrandombytes/notrandombytes.h
@@ -29,6 +29,6 @@
  */
 
 void randombytes_reset(void);
-void randombytes(uint8_t *buf, size_t n);
+int randombytes(uint8_t *buf, size_t n);
 
 #endif /* !NOTRANDOMBYTES_H */
diff --git a/test/test_mlkem.c b/test/test_mlkem.c
@@ -98,7 +98,7 @@ static int test_invalid_sk_a(void)
   /* Bob derives a secret key and creates a response */
   CHECK(crypto_kem_enc(ct, key_b, pk) == 0);
   /* Replace first part of secret key with random values */
-  randombytes(sk, 10);
+  CHECK(randombytes(sk, 10) == 0);
   /* Alice uses Bobs response to get her shared key
    * This should fail due to wrong sk */
   CHECK(crypto_kem_dec(key_a, ct, sk) == 0);
@@ -122,7 +122,7 @@ static int test_invalid_sk_b(void)
   /* Bob derives a secret key and creates a response */
   CHECK(crypto_kem_enc(ct, key_b, pk) == 0);
   /* Replace H(pk) with radom values; */
-  randombytes(sk + CRYPTO_SECRETKEYBYTES - 64, 32);
+  CHECK(randombytes(sk + CRYPTO_SECRETKEYBYTES - 64, 32) == 0);
   /* Alice uses Bobs response to get her shared key
    * This should fail due to the input validation */
   CHECK(crypto_kem_dec(key_a, ct, sk) != 0);
@@ -141,9 +141,9 @@ static int test_invalid_ciphertext(void)
 
   do
   {
-    randombytes(&b, sizeof(uint8_t));
+    CHECK(randombytes(&b, sizeof(uint8_t)) == 0);
   } while (!b);
-  randombytes((uint8_t *)&pos, sizeof(size_t));
+  CHECK(randombytes((uint8_t *)&pos, sizeof(size_t)) == 0);
 
   /* Alice generates a public key */
   CHECK(crypto_kem_keypair(pk, sk) == 0);
diff --git a/test/test_unit.c b/test/test_unit.c
@@ -110,7 +110,10 @@ static void generate_i16_array_ranged(int16_t *data, size_t len, int min_incl,
 {
   size_t i;
 
-  randombytes((uint8_t *)data, len * sizeof(int16_t));
+  if (randombytes((uint8_t *)data, len * sizeof(int16_t)) != 0)
+  {
+    return;
+  }
   for (i = 0; i < len; i++)
   {
     data[i] = (int16_t)((unsigned)min_incl +

Original file line number	Diff line number	Diff line change
`@@ -327,9 +327,9 @@`
`327`	`327`	`#include <stdint.h>`
`328`	`328`	`#include "sys.h"`
`329`	`329`	`#include "test_only_rng/notrandombytes.h"`
`330`		`-static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`330`	`+static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`331`	`331`	`{`
`332`		`- randombytes(ptr, len);`
	`332`	`+ return randombytes(ptr, len);`
`333`	`333`	`}`
`334`	`334`	`#endif /* !__ASSEMBLER__ */`
`335`	`335`
Original file line number	Diff line number	Diff line change
`@@ -182,7 +182,7 @@`
`182`	`182`	`* consumer.`
`183`	`183`	`*`
`184`	`184`	`* If this option is not set, mlkem-native expects a function`
`185`		`- * void randombytes(uint8_t *out, size_t outlen).`
	`185`	`+ * int randombytes(uint8_t *out, size_t outlen).`
`186`	`186`	`*`
`187`	`187`	* Set this option and define `mlk_randombytes` if you want to
`188`	`188`	`* use a custom method to sample randombytes with a different name`
`@@ -194,9 +194,10 @@`
`194`	`194`	`#include <oqs/rand.h>`
`195`	`195`	`#include <stdint.h>`
`196`	`196`	`#include "../../mlkem/src/sys.h"`
`197`		`-static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`197`	`+static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`198`	`198`	`{`
`199`	`199`	`OQS_randombytes(ptr, len);`
	`200`	`+ return 0;`
`200`	`201`	`}`
`201`	`202`	`#endif /* !__ASSEMBLER__ */`
`202`	`203`
Original file line number	Diff line number	Diff line change
`@@ -145,7 +145,7 @@`
`145`	`145`	`* consumer.`
`146`	`146`	`*`
`147`	`147`	`* If this option is not set, mlkem-native expects a function`
`148`		`- * void randombytes(uint8_t *out, size_t outlen).`
	`148`	`+ * int randombytes(uint8_t *out, size_t outlen).`
`149`	`149`	`*`
`150`	`150`	* Set this option and define `mlk_randombytes` if you want to
`151`	`151`	`* use a custom method to sample randombytes with a different name`
`@@ -157,9 +157,10 @@`
`157`	`157`	`#include <oqs/rand.h>`
`158`	`158`	`#include <stdint.h>`
`159`	`159`	`#include "../../mlkem/src/sys.h"`
`160`		`-static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`160`	`+static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`161`	`161`	`{`
`162`	`162`	`OQS_randombytes(ptr, len);`
	`163`	`+ return 0;`
`163`	`164`	`}`
`164`	`165`	`#endif /* !__ASSEMBLER__ */`
`165`	`166`
Original file line number	Diff line number	Diff line change
`@@ -294,7 +294,7 @@`
`294`	`294`	`* consumer.`
`295`	`295`	`*`
`296`	`296`	`* If this option is not set, mlkem-native expects a function`
`297`		`- * void randombytes(uint8_t *out, size_t outlen).`
	`297`	`+ * int randombytes(uint8_t *out, size_t outlen).`
`298`	`298`	`*`
`299`	`299`	* Set this option and define `mlk_randombytes` if you want to
`300`	`300`	`* use a custom method to sample randombytes with a different name`
`@@ -305,7 +305,7 @@`
`305`	`305`	`#if !defined(__ASSEMBLER__)`
`306`	`306`	`#include <stdint.h>`
`307`	`307`	`#include "sys.h"`
`308`		`- static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`308`	`+ static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`309`	`309`	`{`
`310`	`310`	`... your implementation ...`
`311`	`311`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,9 +37,9 @@ configs:`
`37`	`37`	`#include <stdint.h>`
`38`	`38`	`#include "../mlkem/src/sys.h"`
`39`	`39`	`#include "notrandombytes/notrandombytes.h"`
`40`		`- static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`40`	`+ static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`41`	`41`	`{`
`42`		`- randombytes(ptr, len);`
	`42`	`+ return randombytes(ptr, len);`
`43`	`43`	`}`
`44`	`44`	`#endif /* !__ASSEMBLER__ */`
`45`	`45`
`@@ -367,9 +367,9 @@ configs:`
`367`	`367`	`#include <stdint.h>`
`368`	`368`	`#include "sys.h"`
`369`	`369`	`#include "test_only_rng/notrandombytes.h"`
`370`		`- static MLK_INLINE void mlk_randombytes(uint8_t *ptr, size_t len)`
	`370`	`+ static MLK_INLINE int mlk_randombytes(uint8_t *ptr, size_t len)`
`371`	`371`	`{`
`372`		`- randombytes(ptr, len);`
	`372`	`+ return randombytes(ptr, len);`
`373`	`373`	`}`
`374`	`374`	`#endif /* !__ASSEMBLER__ */`
`375`	`375`