libdecaf_spongerng (libdecaf v3.0.0)
View SourceExplicitly seeded pseudorandom byte streams using SpongeRNG.
For automatically seeded random bytes, use libdecaf:strong_rand_bytes/1.
Initialize from seed bytes, a file, or the operating system's random source.
next/2 and stir/2 return new immutable states. Keep the returned state to
advance the generator; reusing an earlier deterministic state repeats its output.
For reproducible output, pass true as Deterministic and use the same seed and
sequence of calls with the same library version. The requested length is part of
each generation operation: one 32-byte request differs from two 16-byte requests,
and even a zero-byte request advances the state.
S0 = libdecaf_spongerng:init_from_buffer(<<>>, true),
{S1, First} = libdecaf_spongerng:next(S0, 16),
<<"2ED664354AA87699BE93C3B62715A256">> = binary:encode_hex(First),
{_S2, Second} = libdecaf_spongerng:next(S1, 16),
true = First =/= Second,
{_RepeatedState, First} = libdecaf_spongerng:next(S0, 16).For random output, initialize with init_from_dev_urandom/0. Passing false
to the other initializers allows upstream to mix in platform-dependent CPU data;
the seed supplied to those initializers is still the caller's responsibility.
State resources are released and erased when no references remain.
Summary
Types
Whether to disable upstream's additional CPU data and produce reproducible output.
Seed or additional data accepted as iodata.
An immutable wrapped native PRNG state. Retain returned states to advance it.
Functions
Initialize from seed bytes, including an empty seed.
With Deterministic = true, the same seed and subsequent calls reproduce the
same output. With false, upstream can mix CPU data into generation operations.
This function does not read the operating system's random source.
Initialize a nondeterministic PRNG from 64 bytes of operating-system randomness.
Upstream reads /dev/urandom, or uses its platform equivalent on Windows.
Failure to obtain the seed raises an exception.
Initialize by reading exactly InputLength bytes from the start of a file.
Filename is a nonempty path expressed as native filename bytes (iodata), and
InputLength must be positive. Failure to open or read enough bytes raises an
exception. Deterministic has the same meaning as in init_from_buffer/2.
Generate OutputLength bytes and return the next state with the output.
The input state remains unchanged. Request lengths and call boundaries affect
future output; a zero-length request returns <<>> and still advances the state.
Mix additional seed bytes into a new state without returning output.
The input state remains unchanged. Stirring even an empty input changes the state.
The caller supplies any entropy in Seed.
Types
Functions
-spec init_from_buffer(Seed, Deterministic) -> State when Seed :: seed(), Deterministic :: deterministic(), State :: state().
Initialize from seed bytes, including an empty seed.
With Deterministic = true, the same seed and subsequent calls reproduce the
same output. With false, upstream can mix CPU data into generation operations.
This function does not read the operating system's random source.
S0 = libdecaf_spongerng:init_from_buffer([<<"seed">>, <<" bytes">>], true),
{_S1, Bytes} = libdecaf_spongerng:next(S0, 32),
32 = byte_size(Bytes).-spec init_from_dev_urandom() -> State when State :: state().
Initialize a nondeterministic PRNG from 64 bytes of operating-system randomness.
Upstream reads /dev/urandom, or uses its platform equivalent on Windows.
Failure to obtain the seed raises an exception.
S0 = libdecaf_spongerng:init_from_dev_urandom(),
{_S1, Bytes} = libdecaf_spongerng:next(S0, 32),
32 = byte_size(Bytes).-spec init_from_file(Filename, InputLength, Deterministic) -> State when Filename :: iodata(), InputLength :: pos_integer(), Deterministic :: deterministic(), State :: state().
Initialize by reading exactly InputLength bytes from the start of a file.
Filename is a nonempty path expressed as native filename bytes (iodata), and
InputLength must be positive. Failure to open or read enough bytes raises an
exception. Deterministic has the same meaning as in init_from_buffer/2.
ok = file:write_file("sponge-seed.bin", <<"example seed">>),
S0 = libdecaf_spongerng:init_from_file("sponge-seed.bin", 12, true),
{_S1, Bytes} = libdecaf_spongerng:next(S0, 16),
16 = byte_size(Bytes),
ok = file:delete("sponge-seed.bin").-spec next(State, OutputLength) -> {NextState, Output} when State :: state(), OutputLength :: non_neg_integer(), NextState :: state(), Output :: binary().
Generate OutputLength bytes and return the next state with the output.
The input state remains unchanged. Request lengths and call boundaries affect
future output; a zero-length request returns <<>> and still advances the state.
S0 = libdecaf_spongerng:init_from_buffer(<<"seed">>, true),
{S1, First} = libdecaf_spongerng:next(S0, 16),
{_S2, Second} = libdecaf_spongerng:next(S1, 16),
16 = byte_size(First),
16 = byte_size(Second).Mix additional seed bytes into a new state without returning output.
The input state remains unchanged. Stirring even an empty input changes the state.
The caller supplies any entropy in Seed.
S0 = libdecaf_spongerng:init_from_buffer(<<"seed">>, true),
S1 = libdecaf_spongerng:stir(S0, [<<"additional">>, <<" seed">>]),
{_S2, Bytes} = libdecaf_spongerng:next(S1, 16),
16 = byte_size(Bytes).