Library
Module
Module type
Parameter
Class
Class type
Secure random number generation.
There are several parts of this module:
set_default_generator
.TL;DR Don't forget to seed; don't maintain your own g
.
The RNGs here are merely the deterministic part of a full random number generation suite. For proper operation, they need to be seeded with a high-quality entropy source.
Suitable generators are provided by sub-libraries mirage-crypto-rng.lwt (for Lwt), mirage-crypto-rng.mirage (for MirageOS), and mirage-crypto-rng.unix. Although this module exposes a more fine-grained interface, allowing manual seeding of generators, this is intended either for implementing entropy-harvesting modules, or very specialized purposes. Users of this library should almost certainly use one of the above entropy libraries, and avoid manually managing the generator seeding.
Similarly, although it is possible to swap the default generator and gain control over the random stream, this is also intended for specialized applications such as testing or similar scenarios where the RNG needs to be fully deterministic, or as a component of deterministic algorithms which internally rely on pseudorandom streams.
In the general case, users should not maintain their local instances of g. All of the generators in a process have to compete for entropy, and it is likely that the overall result will have lower effective unpredictability.
The recommended way to use these functions is either to accept an optional generator and pass it down, or to ignore the generator altogether, as illustrated in the examples.
Thrown when using an uninitialized generator.
module Entropy : sig ... end
Entropy sources and collection
module type Generator = sig ... end
A single PRNG algorithm.
Ready-to-use RNG algorithms.
module Hmac_drbg (H : Mirage_crypto.Hash.S) : Generator
HMAC_DRBG: A NIST-specified RNG based on HMAC construction over the provided hash.
val create :
?g:'a ->
?seed:Cstruct.t ->
?strict:bool ->
?time:(unit -> int64) ->
(module Generator with type g = 'a) ->
g
create ~g ~seed ~strict ~time module
uses a module conforming to the Generator signature to instantiate the generic generator g.
g
is the state to use, otherwise a fresh one is created.
seed
can be provided to immediately reseed the generator with.
strict
puts the generator into a more standards-conformant, but slighty slower mode. Useful if the outputs need to match published test-vectors.
time
is used to limit the amount of reseedings. Fortuna uses at most once every second.
val default_generator : unit -> g
default_generator ()
is the default generator. Functions in this module use this generator when not explicitly supplied one.
val set_default_generator : g -> unit
set_default_generator g
sets the default generator to g
. This function must be called once.
val generate : ?g:g -> int -> Cstruct.t
Invoke generate on g
or default generator.
val block : g option -> int
Block size of g
or default generator.
Generating a random 13-byte Cstruct.t
:
let cs = Rng.generate 13
Generating a list of Cstruct.t
, passing down an optional generator:
let rec f1 ?g ~n i =
if i < 1 then [] else Rng.generate ?g n :: f1 ?g ~n (i - 1)
Generating a Z.t
smaller than 10
:
let f2 ?g () = Mirage_crypto_pk.Z_extra.gen ?g Z.(~$10)
Creating a local Fortuna instance and using it as a key-derivation function:
let f3 secret =
let g = Rng.(create ~seed:secret (module Generators.Fortuna)) in
Rng.generate ~g 32