Struct SystemRng 

pub struct SystemRng;

🔬This is a nightly-only experimental API. (random #130703)

The system random number generator.

This asks the system for random data suitable for cryptographic purposes such as key generation. If security is a concern, consult the platform documentation below for the specific guarantees your target provides.

The high quality of randomness provided by this source means it can be quite slow on some targets. If you need a large quantity of random numbers and security is not a concern, you might want to consider using an alternative random number generator. That said, std attempts to use the fastest source available on the system that still provides strong security. A custom random number generator will in nearly all cases have weaker security attributes than SystemRng.

Blocking

The underlying syscalls might block the calling thread until there is sufficient entropy in the system to seed a procedural random number generator. This is usually only a concern if the program runs immediately after the system boots.

Panicking

Calling fill_bytes will panic if the system cannot provide the required random data. Due to the blocking behaviour described above, this is a permanent condition in nearly all cases and implies that the system lacks the facilities (hardware or software) necessary for collecting entropy. Non-embedded systems usually do not suffer from this limitation.

Underlying sources

Platform	Source
Linux	getrandom or /dev/urandom after polling /dev/random
Windows	ProcessPrng
Apple	CCRandomGenerateBytes
DragonFly	arc4random_buf
ESP-IDF	esp_fill_random
FreeBSD	arc4random_buf
Fuchsia	cprng_draw
Haiku	arc4random_buf
Illumos	arc4random_buf
NetBSD	arc4random_buf
OpenBSD	arc4random_buf
Solaris	arc4random_buf
Vita	arc4random_buf
Hermit	read_entropy
Horizon, Cygwin	getrandom
AIX, Hurd, L4Re, QNX	/dev/urandom
Redox	/scheme/rand
RTEMS	arc4random_buf
SGX	rdrand
SOLID	SOLID_RNG_SampleRandomBytes
TEEOS	TEE_GenerateRandom
UEFI	EFI_RNG_PROTOCOL
VxWorks	randABytes after waiting for randSecure to become ready
WASIp1	random_get
WASIp2	get-random-bytes
WASIp3	get-random-bytes
ZKVM	sys_rand

Note that the sources used might change over time.

Consult the documentation for the underlying operations on your supported targets to determine whether they provide any particular desired properties, such as support for reseeding on VM fork operations.

Examples

Filling a buffer with random bytes

#![feature(random)]

use std::random::{Rng, SystemRng};

let mut buf = [0; 16];
SystemRng.fill_bytes(&mut buf);
dbg!(buf);

Trait Implementations

impl Clone for SystemRng

fn clone(&self) -> SystemRng

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

This item is validated for IEC 61508 (SIL 2) and ISO 26262 (ASIL B).

Performs copy-assignment from source.

impl Copy for SystemRng

impl Debug for SystemRng

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SystemRng

fn default() -> SystemRng

Returns the “default value” for a type.

impl Rng for SystemRng

fn fill_bytes(&mut self, bytes: &mut [u8])

🔬This is a nightly-only experimental API. (random #130703)

Fills bytes with random bytes.