List of all items

Structs

Error

Functions

getrandom

Function getrandom::getrandom

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

Expand description

Fill dest with random bytes from the system’s preferred random number -source.

This function returns an error on any failure, including partial reads. We -make no guarantees regarding the contents of dest on error. If dest is -empty, getrandom immediately returns success, making no calls to the -underlying operating system.

Blocking is possible, at least during early boot; see module documentation.

In general, getrandom will be fast enough for interactive usage, though -significantly slower than a user-space CSPRNG; for the latter consider -rand::thread_rng.

Crate getrandom

source · [−]

Expand description

Interface to the operating system’s random number generator.

Supported targets

- - - - - - - - - - - - - - - - - - - - - -

Target	Target Triple	Implementation
Linux, Android	`‑linux‑`	`getrandom` system call if available, otherwise `/dev/urandom` after successfully polling `/dev/random`
Windows	`‑windows‑`	`BCryptGenRandom`
macOS	`*‑apple‑darwin`	`getentropy` if available, otherwise `/dev/random` (identical to `/dev/urandom`)
iOS	`*‑apple‑ios`	`SecRandomCopyBytes`
FreeBSD	`*‑freebsd`	`getrandom` if available, otherwise `kern.arandom`
OpenBSD	`*‑openbsd`	`getentropy`
NetBSD	`*‑netbsd`	`kern.arandom`
Dragonfly BSD	`*‑dragonfly`	`getrandom` if available, otherwise `/dev/random`
Solaris, illumos	`‑solaris`, `‑illumos`	`getrandom` if available, otherwise `/dev/random`
Fuchsia OS	`*‑fuchsia`	`cprng_draw`
Redox	`*‑redox`	`/dev/urandom`
Haiku	`*‑haiku`	`/dev/random` (identical to `/dev/urandom`)
Hermit	`x86_64-*-hermit`	`RDRAND`
SGX	`x86_64‑*‑sgx`	`RDRAND`
VxWorks	`‑wrs‑vxworks‑`	`randABytes` after checking entropy pool initialization with `randSecure`
ESP-IDF	`*‑espidf`	`esp_fill_random`
Emscripten	`*‑emscripten`	`/dev/random` (identical to `/dev/urandom`)
WASI	`wasm32‑wasi`	`random_get`
Web Browser and Node.js	`wasm32‑*‑unknown`	`Crypto.getRandomValues` if available, then `crypto.randomFillSync` if on Node.js, see WebAssembly support
SOLID	`-kmc-solid_`	`SOLID_RNG_SampleRandomBytes`
Nintendo 3DS	`armv6k-nintendo-3ds`	`getrandom`

There is no blanket implementation on unix targets that reads from -/dev/urandom. This ensures all supported targets are using the recommended -interface and respect maximum buffer sizes.

Pull Requests that add support for new targets to getrandom are always welcome.

Unsupported targets

By default, getrandom will not compile on unsupported targets, but certain -features allow a user to select a “fallback” implementation if no supported -implementation exists.

All of the below mechanisms only affect unsupported -targets. Supported targets will always use their supported implementations. -This prevents a crate from overriding a secure source of randomness -(either accidentally or intentionally).

RDRAND on x86

If the rdrand Cargo feature is enabled, getrandom will fallback to using -the RDRAND instruction to get randomness on no_std x86/x86_64 -targets. This feature has no effect on other CPU architectures.

WebAssembly support

This crate fully supports the -wasm32-wasi and -wasm32-unknown-emscripten -targets. However, the wasm32-unknown-unknown target (i.e. the target used -by wasm-pack) is not automatically -supported since, from the target name alone, we cannot deduce which -JavaScript interface is in use (or if JavaScript is available at all).

Instead, if the js Cargo feature is enabled, this crate will assume -that you are building for an environment containing JavaScript, and will -call the appropriate methods. Both web browser (main window and Web Workers) -and Node.js environments are supported, invoking the methods -described above using the wasm-bindgen toolchain.

To enable the js Cargo feature, add the following to the dependencies -section in your Cargo.toml file:

[dependencies]
-getrandom = { version = "0.2", features = ["js"] }
-

This can be done even if getrandom is not a direct dependency. Cargo -allows crates to enable features for indirect dependencies.

This feature should only be enabled for binary, test, or benchmark crates. -Library crates should generally not enable this feature, leaving such a -decision to users of their library. Also, libraries should not introduce -their own js features just to enable getrandom’s js feature.

This feature has no effect on targets other than wasm32-unknown-unknown.

Node.js ES module support

Node.js supports both CommonJS modules and ES modules. Due to -limitations in wasm-bindgen’s module support, we cannot directly -support ES Modules running on Node.js. However, on Node v15 and later, the -module author can add a simple shim to support the Web Cryptography API:

import { webcrypto } from 'node:crypto'
-globalThis.crypto = webcrypto
-

This crate will then use the provided webcrypto implementation.

Custom implementations

The [register_custom_getrandom!] macro allows a user to mark their own -function as the backing implementation for getrandom. See the macro’s -documentation for more information about writing and registering your own -custom implementations.

Note that registering a custom implementation only has an effect on targets -that would otherwise not compile. Any supported targets (including those -using rdrand and js Cargo features) continue using their normal -implementations even if a function is registered.

Early boot

Sometimes, early in the boot process, the OS has not collected enough -entropy to securely seed its RNG. This is especially common on virtual -machines, where standard “random” events are hard to come by.

Some operating system interfaces always block until the RNG is securely -seeded. This can take anywhere from a few seconds to more than a minute. -A few (Linux, NetBSD and Solaris) offer a choice between blocking and -getting an error; in these cases, we always choose to block.

On Linux (when the getrandom system call is not available), reading from -/dev/urandom never blocks, even when the OS hasn’t collected enough -entropy yet. To avoid returning low-entropy bytes, we first poll -/dev/random and only switch to /dev/urandom once this has succeeded.

On OpenBSD, this kind of entropy accounting isn’t available, and on -NetBSD, blocking on it is discouraged. On these platforms, nonblocking -interfaces are used, even when reliable entropy may not be available. -On the platforms where it is used, the reliability of entropy accounting -itself isn’t free from controversy. This library provides randomness -sourced according to the platform’s best practices, but each platform has -its own limits on the grade of randomness it can promise in environments -with few sources of entropy.

Error handling

We always choose failure over returning known insecure “random” bytes. In -general, on supported platforms, failure is highly unlikely, though not -impossible. If an error does occur, then it is likely that it will occur -on every call to getrandom, hence after the first successful call one -can be reasonably confident that no errors will occur.

Structs

Error

A small and no_std compatible error type

Functions

getrandom

Fill dest with random bytes from the system’s preferred random number -source.

Struct getrandom::Error

source · [−]

pub struct Error(_);

Expand description

A small and no_std compatible error type

The Error::raw_os_error() will indicate if the error is from the OS, and -if so, which error code the OS gave the application. If such an error is -encountered, please consult with your system documentation.

Internally this type is a NonZeroU32, with certain values reserved for -certain purposes, see Error::INTERNAL_START and Error::CUSTOM_START.

If this crate’s "std" Cargo feature is enabled, then:

getrandom::Error implements -std::error::Error
std::io::Error implements -From<getrandom::Error>.

List of all items

Structs

Functions

Function getrandom::getrandom

Crate getrandom

Struct getrandom::Error

Implementations

impl Error

pub const UNSUPPORTED: Error = _

pub const ERRNO_NOT_POSITIVE: Error = _

pub const IOS_SEC_RANDOM: Error = _

pub const WINDOWS_RTL_GEN_RANDOM: Error = _

pub const FAILED_RDRAND: Error = _

pub const NO_RDRAND: Error = _

pub const WEB_CRYPTO: Error = _

pub const WEB_GET_RANDOM_VALUES: Error = _

pub const VXWORKS_RAND_SECURE: Error = _

pub const NODE_CRYPTO: Error = _

pub const NODE_RANDOM_FILL_SYNC: Error = _

pub const NODE_ES_MODULE: Error = _

pub const INTERNAL_START: u32 = 2_147_483_648u32

pub const CUSTOM_START: u32 = 3_221_225_472u32

pub fn raw_os_error(self) -> Option<i32>

pub const fn code(self) -> NonZeroU32

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

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

impl Debug for Error

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

impl Display for Error

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

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

fn description(&self) -> &str

fn cause(&self) -> Option<&dyn Error>

fn provide(&'a self, demand: &mut Demand<'a>)

impl From<Error> for Error

fn from(err: Error) -> Self

impl From<NonZeroU32> for Error

fn from(code: NonZeroU32) -> Self

impl PartialEq<Error> for Error

fn eq(&self, other: &Error) -> bool

fn ne(&self, other: &Rhs) -> bool

impl Copy for Error

impl Eq for Error

impl StructuralEq for Error

impl StructuralPartialEq for Error

Auto Trait Implementations

impl RefUnwindSafe for Error

impl Send for Error

impl Sync for Error

impl Unpin for Error

impl UnwindSafe for Error

Blanket Implementations

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

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

impl<T> From<T> for T

fn from(t: T) -> T

impl<T, U> Into<U> for Twhere U: From<T>,

fn into(self) -> U

impl<E> Provider for Ewhere E: Error + ?Sized,

fn provide(&'a self, demand: &mut Demand<'a>)

impl<T> ToOwned for Twhere T: Clone,

type Owned = T

fn to_owned(&self) -> T

fn clone_into(&self, target: &mut T)

impl<T> ToString for Twhere T: Display + ?Sized,

default fn to_string(&self) -> String

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = Infallible

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

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

impl<T> Any for Twhere
T: 'static + ?Sized,

impl<T> Borrow<T> for Twhere
T: ?Sized,

impl<T> BorrowMut<T> for Twhere
T: ?Sized,

impl<T, U> Into<U> for Twhere
U: From<T>,

impl<E> Provider for Ewhere
E: Error + ?Sized,

impl<T> ToOwned for Twhere
T: Clone,

impl<T> ToString for Twhere
T: Display + ?Sized,

impl<T, U> TryFrom<U> for Twhere
U: Into<T>,

impl<T, U> TryInto<U> for Twhere
U: TryFrom<T>,