Struct RdRand

pub struct RdRand(/* private fields */);

A cryptographically secure statistically uniform, non-periodic and non-deterministic random bit generator.

Note that this generator may be implemented using a deterministic algorithm that is reseeded routinely from a non-deterministic entropy source to achieve the desirable properties.

This generator is a viable replacement to any generator, however, since nobody has audited this hardware implementation yet, the usual disclaimers as to their suitability apply.

It is potentially faster than OsRng, but is only supported by more recent architectures such as Intel Ivy Bridge and AMD Zen.

Implementations

impl RdRand

pub fn new() -> Result<Self, ErrorCode>

Create a new instance of the random number generator.

This constructor checks whether the CPU the program is running on supports the instruction necessary for this generator to operate. If the instruction is not supported, an error is returned.

pub unsafe fn new_unchecked() -> Self

Create a new instance of the random number generator.

Safety

This constructor is unsafe because it doesn’t check that the CPU supports the instruction, but devolves this responsibility to the caller.

pub fn try_next_u16(&self) -> Result<u16, ErrorCode>

Generate a single random u16 value.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

This method will retry calling the instruction a few times, however if all the attempts fail, it will return None.

In case Err is returned, the caller should assume that a non-recoverable failure has occured and use another random number genrator instead.

pub fn try_next_u32(&self) -> Result<u32, ErrorCode>

Generate a single random u32 value.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

This method will retry calling the instruction a few times, however if all the attempts fail, it will return None.

In case Err is returned, the caller should assume that a non-recoverable failure has occured and use another random number genrator instead.

pub fn try_next_u64(&self) -> Result<u64, ErrorCode>

Generate a single random u64 value.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

This method will retry calling the instruction a few times, however if all the attempts fail, it will return None.

In case Err is returned, the caller should assume that a non-recoverable failure has occured and use another random number genrator instead.

Note, that on 32-bit targets, there’s no underlying instruction to generate a 64-bit number, so it is emulated with the 32-bit version of the instruction.

pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), ErrorCode>

Fill a buffer dest with random data.

This method will use the most appropriate variant of the instruction available on the machine to achieve the greatest single-core throughput, however it has a slightly higher setup cost than the plain next_u32 or next_u64 methods.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

This method will retry calling the instruction a few times, however if all the attempts fail, it will return an error.

If an error is returned, the caller should assume that an non-recoverable hardware failure has occured and use another random number genrator instead.

Trait Implementations

impl Clone for RdRand

fn clone(&self) -> RdRand

Returns a copy of the value.

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

Performs copy-assignment from source.

impl RngCore for RdRand

fn next_u32(&mut self) -> u32

Generate a single random u32 value.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

Panic

This method will retry calling the instruction a few times, however if all the attempts fail, it will panic.

In case panic occurs, the caller should assume that an non-recoverable hardware failure has occured and use another random number genrator instead.

fn next_u64(&mut self) -> u64

Generate a single random u64 value.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

Note, that on 32-bit targets, there’s no underlying instruction to generate a 64-bit number, so it is emulated with the 32-bit version of the instruction.

Panic

This method will retry calling the instruction a few times, however if all the attempts fail, it will panic.

In case panic occurs, the caller should assume that an non-recoverable hardware failure has occured and use another random number genrator instead.

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

Fill a buffer dest with random data.

See try_fill_bytes for a more extensive documentation.

Panic

This method will panic any time try_fill_bytes would return an error.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Fill a buffer dest with random data.

This method will use the most appropriate variant of the instruction available on the machine to achieve the greatest single-core throughput, however it has a slightly higher setup cost than the plain next_u32 or next_u64 methods.

The underlying instruction may fail for variety reasons (such as actual hardware failure or exhausted entropy), however the exact reason for the failure is not usually exposed.

This method will retry calling the instruction a few times, however if all the attempts fail, it will return an error.

If an error is returned, the caller should assume that an non-recoverable hardware failure has occured and use another random number genrator instead.

impl Copy for RdRand

impl CryptoRng for RdRand