From 8f962c1b22974a44b476aedd7fc404be274ce270 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 25 Feb 2026 22:12:13 +0100
Subject: [PATCH] Add MBEDTLS_PLATFORM_DEV_RANDOM as a compile-time option

Document when this is not used. This was the case in TF-PSA-Crypto 1.0.0,
but not yet in Mbed TLS 3.6.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 ChangeLog.d/dev-random.txt       |  4 ++++
 include/mbedtls/mbedtls_config.h | 26 ++++++++++++++++++++++++++
 include/mbedtls/platform.h       |  5 ++---
 3 files changed, 32 insertions(+), 3 deletions(-)
 create mode 100644 ChangeLog.d/dev-random.txt

diff --git a/ChangeLog.d/dev-random.txt b/ChangeLog.d/dev-random.txt
new file mode 100644
index 0000000000..b27e95e552
--- /dev/null
+++ b/ChangeLog.d/dev-random.txt
@@ -0,0 +1,4 @@
+Features
+   * The device for reading entropy on platforms without a dedicated system
+     call can now be configured with MBEDTLS_PLATFORM_DEV_RANDOM or
+     mbedtls_platform_dev_random.
diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h
index 75eff2d89a..958c0d8385 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -1204,6 +1204,20 @@
  * This is useful if your platform does not support
  * standards like the /dev/urandom or Windows CryptoAPI.
  *
+ * If you enable this macro, you will probably need to enable
+ * #MBEDTLS_ENTROPY_HARDWARE_ALT and provide a function
+ * mbedtls_hardware_poll().
+ *
+ * \note The default platform entropy function supports the following
+ *       sources:
+ *       - getrandom() on Linux (if syscall() is available at compile time);
+ *       - getrandom() on FreeBSD and DragonFlyBSD (if available at compile
+ *         time);
+ *       - `sysctl(KERN_ARND)` on FreeBSD and NetBSD;
+ *       - #MBEDTLS_PLATFORM_DEV_RANDOM on Unix-like platforms
+ *         (unless one of the above is used);
+ *       - BCryptGenRandom() on Windows.
+ *
  * Uncomment this macro to disable the built-in platform entropy functions.
  */
 //#define MBEDTLS_NO_PLATFORM_ENTROPY
@@ -4140,6 +4154,18 @@
 //#define MBEDTLS_PLATFORM_MS_TIME_TYPE_MACRO   int64_t //#define MBEDTLS_PLATFORM_MS_TIME_TYPE_MACRO   int64_t /**< Default milliseconds time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled. It must be signed, and at least 64 bits. If it is changed from the default, MBEDTLS_PRINTF_MS_TIME must be updated to match.*/
 //#define MBEDTLS_PRINTF_MS_TIME    PRId64 /**< Default fmt for printf. That's avoid compiler warning if mbedtls_ms_time_t is redefined */
 
+/*** \def MBEDTLS_PLATFORM_DEV_RANDOM
+ *
+ * Path to a special file that returns cryptographic-quality random bytes
+ * when read. This is used by the default platform entropy source on
+ * non-Windows platforms unless a dedicated system call is available
+ * (see #MBEDTLS_NO_PLATFORM_ENTROPY).
+ *
+ * This is the default value of ::mbedtls_platform_dev_random, which
+ * can be changed at run time.
+ */
+//#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/urandom"
+
 /** \def MBEDTLS_CHECK_RETURN
  *
  * This macro is used at the beginning of the declaration of a function
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 95eb6d9dc1..3ef72074c4 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -401,11 +401,10 @@ int mbedtls_platform_set_exit(void (*exit_func)(int status));
 #if defined(MBEDTLS_PLATFORM_HAVE_DEV_RANDOM)
 /**
  * Path to a special file that returns cryptographic-quality random bytes
- * when read. This is used by the default platform entropy source on
- * non-Windows platforms unless a dedicated system call is available
- * (see #MBEDTLS_NO_PLATFORM_ENTROPY).
+ * when read.
  *
  * The default value is #MBEDTLS_PLATFORM_DEV_RANDOM.
+ * See the documentation of this option for guidance.
  */
 extern const char *mbedtls_platform_dev_random;
 #endif