From 409baa7b7baff8b7200a7bd5c21d2d11a0369ac0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 25 Feb 2026 22:40:42 +0100 Subject: [PATCH] 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. */