EntropySource interfacev0.1.0

pub interface EntropySource {
    func Fill(
        self: &var Self,
        buffer: *var opaque,
        length: uint
    ) -> ! EntropyError;
}

Implemented by SystemEntropy for the operating system's generator, and by a test for a source that fails on demand. An implementation either fills the whole buffer and succeeds, or fails with why it did not.

Requirements

Fill

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

Fills length bytes of buffer with unpredictable bytes. buffer is borrowed and written; length is read by value. Succeeds only when every byte was written. An implementation may write part of the buffer before failing — the caller is what guarantees nothing partial survives. buffer must be writable for length bytes.

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

Source

Implementations

Related

FillFrom

pub func FillFrom(
    source: &var EntropySource,
    buffer: *var opaque,
    length: uint
) -> ! EntropyError

Fills length bytes of buffer from source, in as many calls as it takes. source is borrowed for the call; buffer is borrowed and written; length is read by value. Succeeds only when every byte was written, and otherwise fails with what the source reported. A request larger than a single call accepts is split, so a caller need not know what that limit is. A failure part-way through a split request is a failure of the whole request: there is no state in which some of a buffer is unpredictable and the rest is not, because nothing downstream could act on the difference. Runs in time proportional to length and allocates nothing. buffer must be writable for length bytes. On any failure the whole buffer is zeroized, including the parts an earlier call filled successfully.

Source

Parameters

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

FillWithRetries

pub func FillWithRetries(
    source: &var EntropySource,
    buffer: *var opaque,
    length: uint,
    attempts: uint
) -> ! EntropyError

Fills length bytes of buffer from source, trying again while the failure says trying again might work. source is borrowed for the call; buffer is borrowed and written; length and attempts are read by value. attempts is how many extra tries to make, so zero is one attempt and behaves exactly like FillFrom. Only a transient failure is retried — Interrupted, which says a signal arrived rather than that anything is wrong. A system with no source and a provider that refused are both reported at once, because repeating them would only take longer to reach the same answer. Runs in time proportional to length times the attempts made, and allocates nothing. buffer must be writable for length bytes. Every failed attempt zeroizes the buffer, so a failure that exhausts the attempts leaves zeros.

Source

Parameters

Returns: nothing when every byte was written, or why not — Interrupted after attempts tries