SystemEntropy structv0.1.0

pub struct SystemEntropy {}

Holds nothing: the system's generator needs no handle, no seed and no shutdown. It exists so that code taking a source can be handed the real one.

Constructors

SystemEntropy

pub func SystemEntropy() -> SystemEntropy

The operating system's generator. Takes nothing and cannot fail. Costs nothing to make, so there is no reason to keep one around rather than making one where it is needed. Runs in constant time and allocates nothing.

Returns: the source, which holds no state of its own

Source

Implements EntropySource

SystemEntropy conforms to EntropySource.

Fill

pub func Fill(
    self: &var SystemEntropy,
    buffer: *var opaque,
    length: uint
) -> ! EntropyError

Fills length bytes of buffer from the operating system. Exactly FillFromSource, reached through the interface. Succeeds only when every byte was written. Runs in time proportional to length and allocates nothing. buffer must be writable for length bytes.

Returns: nothing when every byte was written, or why not

Source

Related

MaxEntropyAttempts

pub const MaxEntropyAttempts: uint = 16;

How many times a fill will go back to an interrupted source before giving up. A signal arriving during the call is ordinary and retrying is correct, but a process taking signals steadily must not spin forever inside what its caller believes is one operation. Reaching this reports Interrupted, which says exactly that and leaves trying again to the caller, who knows whether it is worth it.

Source

MaxEntropyRequest

pub const MaxEntropyRequest: uint = 0xFFFFFFFF;

The largest request the source accepts in a single call. Windows takes a 32-bit count, so this is what a portable caller may ask for at once. A larger buffer is filled by asking more than once, which Fill does.

Source

FillFromSource

pub func FillFromSource(
    buffer: *var opaque,
    length: uint
) -> ! EntropyError

Fills length bytes of buffer from the system's generator, in one pass. buffer is borrowed and written; length is read by value. Succeeds only when every byte was written. A zero length succeeds without touching anything. A length past what the source accepts is reported before the buffer is looked at, so an impossible request is refused whatever was passed with it; a null buffer with an ordinary length reports Failed rather than being written through. On Linux and FreeBSD a short count is not a failure, so this loops until the buffer is full; a signal in the middle is retried up to MaxEntropyAttempts times before reporting Interrupted. A kernel with no such call reports Unsupported. On Darwin the source cannot fail. On Windows a request above MaxEntropyRequest reports TooLarge, since the count is passed as 32 bits. Runs in time proportional to length and allocates nothing. buffer must be writable for length bytes. On any failure the buffer is zeroized, so a caller who ignores the result gets zeros rather than a partly random buffer that would pass a glance.

Source

Parameters

Returns: nothing when every byte was written in this one pass, or why not