Struct `SystemRng`

pub struct SystemRng;

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, 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

`impl Copy for SystemRng`

`impl Debug for SystemRng`

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

`impl Default for SystemRng`

fn default() -> SystemRng

`impl Rng for SystemRng`

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

`impl TrivialClone for SystemRng`

Auto Trait Implementations

`impl Freeze for SystemRng`

`impl RefUnwindSafe for SystemRng`

`impl Send for SystemRng`

`impl Sync for SystemRng`

`impl Unpin for SystemRng`

`impl UnsafeUnpin for SystemRng`

`impl UnwindSafe for SystemRng`

Blanket Implementations

`impl<T> Any for SystemRng where T: 'static + ?Sized,`

fn type_id(&self) -> TypeId

`impl<T> Borrow<T> for SystemRng where T: ?Sized,`

fn borrow(&self) -> &T

`impl<T> BorrowMut<T> for SystemRng where T: ?Sized,`

fn borrow_mut(&mut self) -> &mut T

`impl<T> CloneToUninit for SystemRng where T: Clone,`

unsafe fn clone_to_uninit(&self, dest: *mut u8)

`impl<T> From<T> for SystemRng`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> Printable for SystemRng where T: Copy + Debug,`

`impl<T> SizeHint for SystemRng where T: ?Sized,`

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

`impl<T> SizedTypeProperties for SystemRng`

`impl<T> ToOwned for SystemRng where T: Clone,`

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

`impl<T, U> Into for SystemRng where U: From<T>,`

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for SystemRng where U: Into<T>,`

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

`impl<T, U> TryInto for SystemRng where U: TryFrom<T>,`

type Error = >::Error;
fn try_into(self) -> Result<U, >::Error>