std/random.rs
1//! Random value generation.
2
3#[unstable(feature = "random", issue = "130703")]
4pub use core::random::*;
5
6use crate::sys::random as sys;
7
8/// The default random source.
9///
10/// This asks the system for random data suitable for cryptographic purposes
11/// such as key generation. If security is a concern, consult the platform
12/// documentation below for the specific guarantees your target provides.
13///
14/// The high quality of randomness provided by this source means it can be quite
15/// slow on some targets. If you need a large quantity of random numbers and
16/// security is not a concern, consider using an alternative random number
17/// generator (potentially seeded from this one).
18///
19/// # Underlying sources
20///
21/// Platform | Source
22/// -----------------------|---------------------------------------------------------------
23/// Linux | [`getrandom`] or [`/dev/urandom`] after polling `/dev/random`
24/// Windows | [`ProcessPrng`](https://learn.microsoft.com/en-us/windows/win32/seccng/processprng)
25/// Apple | `CCRandomGenerateBytes`
26/// DragonFly | [`arc4random_buf`](https://man.dragonflybsd.org/?command=arc4random)
27/// ESP-IDF | [`esp_fill_random`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html#_CPPv415esp_fill_randomPv6size_t)
28/// FreeBSD | [`arc4random_buf`](https://man.freebsd.org/cgi/man.cgi?query=arc4random)
29/// Fuchsia | [`cprng_draw`](https://fuchsia.dev/reference/syscalls/cprng_draw)
30/// Haiku | `arc4random_buf`
31/// Illumos | [`arc4random_buf`](https://www.illumos.org/man/3C/arc4random)
32/// NetBSD | [`arc4random_buf`](https://man.netbsd.org/arc4random.3)
33/// OpenBSD | [`arc4random_buf`](https://man.openbsd.org/arc4random.3)
34/// Solaris | [`arc4random_buf`](https://docs.oracle.com/cd/E88353_01/html/E37843/arc4random-3c.html)
35/// Vita | `arc4random_buf`
36/// Hermit | `read_entropy`
37/// Horizon, Cygwin | `getrandom`
38/// AIX, Hurd, L4Re, QNX | `/dev/urandom`
39/// Redox | `/scheme/rand`
40/// RTEMS | [`arc4random_buf`](https://docs.rtems.org/branches/master/bsp-howto/getentropy.html)
41/// SGX | [`rdrand`](https://en.wikipedia.org/wiki/RDRAND)
42/// SOLID | `SOLID_RNG_SampleRandomBytes`
43/// TEEOS | `TEE_GenerateRandom`
44/// UEFI | [`EFI_RNG_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/37_Secure_Technologies.html#random-number-generator-protocol)
45/// VxWorks | `randABytes` after waiting for `randSecure` to become ready
46/// WASI | [`random_get`](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#-random_getbuf-pointeru8-buf_len-size---result-errno)
47/// ZKVM | `sys_rand`
48///
49/// Note that the sources used might change over time.
50///
51/// Consult the documentation for the underlying operations on your supported
52/// targets to determine whether they provide any particular desired properties,
53/// such as support for reseeding on VM fork operations.
54///
55/// [`getrandom`]: https://www.man7.org/linux/man-pages/man2/getrandom.2.html
56/// [`/dev/urandom`]: https://www.man7.org/linux/man-pages/man4/random.4.html
57#[derive(Default, Debug, Clone, Copy)]
58#[unstable(feature = "random", issue = "130703")]
59pub struct DefaultRandomSource;
60
61#[unstable(feature = "random", issue = "130703")]
62impl RandomSource for DefaultRandomSource {
63 fn fill_bytes(&mut self, bytes: &mut [u8]) {
64 sys::fill_bytes(bytes)
65 }
66}
67
68/// Generates a random value from a distribution, using the default random source.
69///
70/// This is a convenience function for `dist.sample(&mut DefaultRandomSource)` and will sample
71/// according to the same distribution as the underlying [`Distribution`] trait implementation. See
72/// [`DefaultRandomSource`] for more information about how randomness is sourced.
73///
74/// # Examples
75///
76/// Generating a [version 4/variant 1 UUID] represented as text:
77/// ```
78/// #![feature(random)]
79///
80/// use std::random::random;
81///
82/// let bits: u128 = random(..);
83/// let g1 = (bits >> 96) as u32;
84/// let g2 = (bits >> 80) as u16;
85/// let g3 = (0x4000 | (bits >> 64) & 0x0fff) as u16;
86/// let g4 = (0x8000 | (bits >> 48) & 0x3fff) as u16;
87/// let g5 = (bits & 0xffffffffffff) as u64;
88/// let uuid = format!("{g1:08x}-{g2:04x}-{g3:04x}-{g4:04x}-{g5:012x}");
89/// println!("{uuid}");
90/// ```
91///
92/// [version 4/variant 1 UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
93#[unstable(feature = "random", issue = "130703")]
94pub fn random<T>(dist: impl Distribution<T>) -> T {
95 dist.sample(&mut DefaultRandomSource)
96}