Add a function that fills a buffer from the random generator provided by the operating system, for callers that need values which must not be predictable, such as keys, hash seeds and MAC addresses.
rte_rand() is a fast pseudo-random generator whose internal state can be recovered from a handful of outputs, so it is not suitable for those uses. The implementation uses getrandom(), which is now available on all supported platforms. Requests are split internally to stay within the size that is guaranteed to be returned in full, so that callers do not have to care about the limit. If the system random generator is not available an error is returned rather than falling back to the pseudo-random generator, since a guessable value is worse than a failure for the intended uses. Signed-off-by: Stephen Hemminger <[email protected]> --- doc/guides/rel_notes/release_26_11.rst | 5 +++ lib/eal/common/rte_random.c | 40 ++++++++++++++++++++++++ lib/eal/include/rte_random.h | 43 +++++++++++++++++++++++++- 3 files changed, 87 insertions(+), 1 deletion(-) diff --git a/doc/guides/rel_notes/release_26_11.rst b/doc/guides/rel_notes/release_26_11.rst index c1742b3c60..f25e497729 100644 --- a/doc/guides/rel_notes/release_26_11.rst +++ b/doc/guides/rel_notes/release_26_11.rst @@ -60,6 +60,11 @@ New Features * The initial seed is now always taken from ``getentropy()``. * Added ``rte_rand32()`` for callers which only need 32 bits and would otherwise have to truncate the result of ``rte_rand()``. + * Added ``rte_random_bytes()`` to fill a buffer from the random + generator provided by the operating system. It is intended for + values which must not be predictable, such as keys, hash seeds and + MAC addresses, where the pseudo-random ``rte_rand()`` is not + suitable. Removed Items diff --git a/lib/eal/common/rte_random.c b/lib/eal/common/rte_random.c index 1368b70e27..4b777f69f4 100644 --- a/lib/eal/common/rte_random.c +++ b/lib/eal/common/rte_random.c @@ -10,9 +10,13 @@ #include <errno.h> #include <string.h> #include <unistd.h> +#ifndef RTE_EXEC_ENV_WINDOWS +#include <sys/random.h> +#endif #include <rte_bitops.h> #include <rte_branch_prediction.h> +#include <rte_common.h> #include <rte_cycles.h> #include <rte_lcore.h> #include <rte_lcore_var.h> @@ -228,6 +232,42 @@ rte_drand(void) return (double)rand64 / denom; } +/* Requests of at most this size are guaranteed to return in full + * once the random source has been initialized. Larger requests are + * split so that callers do not have to care about the limit. + */ +#define RANDOM_BYTES_CHUNK 256 + +RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_random_bytes, 26.11) +int +rte_random_bytes(void *buf, size_t len) +{ + uint8_t *ptr = buf; + + while (len > 0) { + size_t chunk = RTE_MIN(len, (size_t)RANDOM_BYTES_CHUNK); + ssize_t ret; + + ret = getrandom(ptr, chunk, 0); + if (ret < 0) { + if (errno == EINTR) + continue; + return -errno; + } + + /* Should not happen, a bounded request either blocks + * until it can be satisfied in full or fails. + */ + if (ret == 0) + return -EIO; + + ptr += ret; + len -= ret; + } + + return 0; +} + static uint64_t __rte_random_initial_seed(void) { diff --git a/lib/eal/include/rte_random.h b/lib/eal/include/rte_random.h index 9d3ecc596e..7c5030ecab 100644 --- a/lib/eal/include/rte_random.h +++ b/lib/eal/include/rte_random.h @@ -8,9 +8,14 @@ /** * @file * - * Pseudo-random Generators in RTE + * Random number generation. + * + * A fast pseudo-random generator for general use, and access to the + * random source of the operating system for values which must not be + * predictable. */ +#include <stddef.h> #include <stdint.h> #include <rte_compat.h> @@ -104,6 +109,42 @@ rte_rand_max(uint64_t upper_bound); */ double rte_drand(void); +/** + * @warning + * @b EXPERIMENTAL: this API may change without prior notice. + * + * Fill a buffer with random bytes from the system random generator. + * + * The bytes are drawn from the same source as the urandom device and + * are suitable for cryptographic purposes such as keys, hash seeds and + * MAC addresses. Unlike rte_rand() the generator state is not + * recoverable from the output. + * + * If the system random source has not been initialized yet this call + * blocks until enough entropy is available. Once initialized it never + * blocks. + * + * It is several orders of magnitude slower than rte_rand() because it + * may enter the kernel on every call, and is not meant to be used on + * the datapath. + * + * This function is multi-thread safe. + * + * @param buf + * Buffer to fill with random bytes. + * @param len + * Number of bytes to write. There is no upper limit, larger requests + * are split internally. A length of zero succeeds without doing + * anything. + * @return + * 0 on success and the buffer is filled completely. + * A negative errno if the system random generator failed, the + * contents of the buffer are then undefined. + */ +__rte_experimental +int +rte_random_bytes(void *buf, size_t len); + #ifdef __cplusplus } #endif -- 2.53.0
