From 2ccda0f48c603afb96402dfd9be0b4639362309b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 25 Feb 2026 22:10:17 +0100 Subject: [PATCH 1/8] Make the random device configurable Instead of unconditionally using `/dev/urandom`, make the device path configurable at compile time through `MBEDTLS_PLATFORM_DEV_RANDOM` or at run time through `mbedtls_platform_dev_random`. Signed-off-by: Gilles Peskine --- include/mbedtls/platform.h | 25 +++++++++++++++++++++++++ library/entropy_poll.c | 4 +++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index de3d71d9dc..95eb6d9dc1 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -385,6 +385,31 @@ int mbedtls_platform_set_exit(void (*exit_func)(int status)); #define MBEDTLS_EXIT_FAILURE 1 #endif +#if defined(MBEDTLS_ENTROPY_C) && \ + !defined(MBEDTLS_NO_PLATFORM_ENTROPY) && \ + !(defined(_WIN32) && !defined(EFIX64) && !defined(EFI32)) +/* Platforms where MBEDTLS_PLATFORM_DEV_RANDOM is used + * unless a dedicated system call is available both at + * compile time and at run time. */ +#define MBEDTLS_PLATFORM_HAVE_DEV_RANDOM +#endif + +#if !defined(MBEDTLS_PLATFORM_DEV_RANDOM) +#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/urandom" +#endif + +#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). + * + * The default value is #MBEDTLS_PLATFORM_DEV_RANDOM. + */ +extern const char *mbedtls_platform_dev_random; +#endif + /* * The function pointers for reading from and writing a seed file to * Non-Volatile storage (NV) in a platform-independent way diff --git a/library/entropy_poll.c b/library/entropy_poll.c index 611768cd85..1c8a29d6e2 100644 --- a/library/entropy_poll.c +++ b/library/entropy_poll.c @@ -147,6 +147,8 @@ static int sysctl_arnd_wrapper(unsigned char *buf, size_t buflen) #include +const char *mbedtls_platform_dev_random = MBEDTLS_PLATFORM_DEV_RANDOM; + int mbedtls_platform_entropy_poll(void *data, unsigned char *output, size_t len, size_t *olen) { @@ -180,7 +182,7 @@ int mbedtls_platform_entropy_poll(void *data, *olen = 0; - file = fopen("/dev/urandom", "rb"); + file = fopen(mbedtls_platform_dev_random, "rb"); if (file == NULL) { return MBEDTLS_ERR_ENTROPY_SOURCE_FAILED; } From 8f962c1b22974a44b476aedd7fc404be274ce270 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 25 Feb 2026 22:12:13 +0100 Subject: [PATCH 2/8] 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 --- 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 From 409baa7b7baff8b7200a7bd5c21d2d11a0369ac0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 25 Feb 2026 22:40:42 +0100 Subject: [PATCH 3/8] Document /dev/random vs /dev/urandom on Linux Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 958c0d8385..50b87351a3 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -4161,6 +4161,25 @@ * non-Windows platforms unless a dedicated system call is available * (see #MBEDTLS_NO_PLATFORM_ENTROPY). * + * The default value is `/dev/urandom`, which is suitable on most platforms + * other than Linux. On Linux, either `/dev/random` or `/dev/urandom` + * may be the right choice, depending on the circumstances: + * + * - If possible, the library will use the getrandom() system call, + * which is preferable, and #MBEDTLS_PLATFORM_DEV_RANDOM is not used. + * - If there is a dedicated hardware entropy source (e.g. RDRAND on x86 + * processors), then both `/dev/random` and `/dev/urandom` are fine. + * - `/dev/random` is always secure. However, with kernels older than 5.6, + * `/dev/random` often blocks unnecessarily if there is no dedicated + * hardware entropy source. + * - `/dev/urandom` never blocks. However, it may return predictable data + * if it is used early after the kernel boots, especially on embedded + * devices without an interactive user. + * + * Thus you should change the value to `/dev/random` if your application + * may be used on a device running Linux without a dedicated hardware + * entropy source early after boot. + * * This is the default value of ::mbedtls_platform_dev_random, which * can be changed at run time. */ From 6f63121a00dbf16a55668249b6f986b2db113226 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 25 Feb 2026 22:46:43 +0100 Subject: [PATCH 4/8] Change the default from /dev/urandom to /dev/random Signed-off-by: Gilles Peskine --- ChangeLog.d/dev-random.txt | 7 +++++++ include/mbedtls/mbedtls_config.h | 6 +++--- include/mbedtls/platform.h | 2 +- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/ChangeLog.d/dev-random.txt b/ChangeLog.d/dev-random.txt index b27e95e552..eff1352354 100644 --- a/ChangeLog.d/dev-random.txt +++ b/ChangeLog.d/dev-random.txt @@ -2,3 +2,10 @@ 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. + +Security + * The default device for reading entropy on platforms without a dedicated + system call is now /dev/random instead of /dev/urandom. This is safer + on Linux in case the application runs early after the kernel boots, + but may block needlessly on Linux <= 5.6. Reported by supers1ngular + (BayLibre). diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 50b87351a3..9ebf376a96 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -4176,14 +4176,14 @@ * if it is used early after the kernel boots, especially on embedded * devices without an interactive user. * - * Thus you should change the value to `/dev/random` if your application + * Thus you should change the value to `/dev/urandom` if your application * may be used on a device running Linux without a dedicated hardware - * entropy source early after boot. + * entropy source, and doesn't run early during or after boot. * * This is the default value of ::mbedtls_platform_dev_random, which * can be changed at run time. */ -//#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/urandom" +//#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/random" /** \def MBEDTLS_CHECK_RETURN * diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index 3ef72074c4..82dd305e00 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -395,7 +395,7 @@ int mbedtls_platform_set_exit(void (*exit_func)(int status)); #endif #if !defined(MBEDTLS_PLATFORM_DEV_RANDOM) -#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/urandom" +#define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/random" #endif #if defined(MBEDTLS_PLATFORM_HAVE_DEV_RANDOM) From 3f8f4a0c3fa25cc8e8ee2d9e2c1027352fcd600c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 27 Feb 2026 20:45:48 +0100 Subject: [PATCH 5/8] Improve advice Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 9ebf376a96..875ee8b09f 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -4177,8 +4177,8 @@ * devices without an interactive user. * * Thus you should change the value to `/dev/urandom` if your application - * may be used on a device running Linux without a dedicated hardware - * entropy source, and doesn't run early during or after boot. + * definitely won't be used on a device running Linux without a dedicated + * entropy source early during or after boot. * * This is the default value of ::mbedtls_platform_dev_random, which * can be changed at run time. From d8ce52df193ce5aac8b43f934d32bcbbef371d30 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 11 Mar 2026 10:48:58 +0100 Subject: [PATCH 6/8] Fix Doxygen comment start Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 875ee8b09f..f1fe6a12e7 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -4154,7 +4154,7 @@ //#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 +/** \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 From 43afaa53438f91509ff6fe9be65e59912963b529 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 11 Mar 2026 12:21:18 +0100 Subject: [PATCH 7/8] Fix Doxygen warning in realfull config Signed-off-by: Gilles Peskine --- include/mbedtls/platform.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index 82dd305e00..f1ec9975e8 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -398,11 +398,18 @@ int mbedtls_platform_set_exit(void (*exit_func)(int status)); #define MBEDTLS_PLATFORM_DEV_RANDOM "/dev/random" #endif -#if defined(MBEDTLS_PLATFORM_HAVE_DEV_RANDOM) +/* Arrange for mbedtls_platform_dev_random to always be visible to + * Doxygen, because it's linked from the documentation of + * MBEDTLS_PLATFORM_DEV_RANDOM and that documentation can be visible + * even in configurations where it isn't used. */ +#if defined(MBEDTLS_PLATFORM_HAVE_DEV_RANDOM) || defined(__DOXYGEN__) /** * Path to a special file that returns cryptographic-quality random bytes * when read. * + * This variable is only declared on platforms where it is used. + * It is available when the macro `MBEDTLS_PLATFORM_HAVE_DEV_RANDOM` is defined. + * * The default value is #MBEDTLS_PLATFORM_DEV_RANDOM. * See the documentation of this option for guidance. */ From 03fafd2637a4d7180ce3fe6cbb436858f2cbfd53 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Mar 2026 14:02:47 +0100 Subject: [PATCH 8/8] Update a statement about the default value (now /dev/random) Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index f1fe6a12e7..8fa445a132 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -4161,7 +4161,7 @@ * non-Windows platforms unless a dedicated system call is available * (see #MBEDTLS_NO_PLATFORM_ENTROPY). * - * The default value is `/dev/urandom`, which is suitable on most platforms + * The default value is `/dev/random`, which is suitable on most platforms * other than Linux. On Linux, either `/dev/random` or `/dev/urandom` * may be the right choice, depending on the circumstances: *