module Rng:`sig`

..`end`

Secure random number generation.

There are several parts of this module:

- The signature of generator modules, together with a facility to convert such modules into actual generators, and functions that operate on this representation.
- A global generator instance, implemented by Fortuna. This is the default generator, used when one is not explicitly supplied.
- The signature of modules for randomly generating a particular
numeric type, a functor to produce them, and instances for
`int`

,`int32`

,`int64`

, and`Z.t`

. - Several specialized functions for e.g. primes.

`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 entropy sources are provided by sub-libraries nocrypto.unix, nocrypto.lwt and nocrypto.xen. 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.

`type `

g

A generator (PRNG) with its state.

`exception Unseeded_generator`

Thrown when using an uninitialized generator.

module S:`sig`

..`end`

Module signatures.

module Generators:`sig`

..`end`

Ready-to-use RNG algorithms.

`val create : ``?g:'a ->`

?seed:Cstruct.t ->

?strict:bool ->

(module Nocrypto.Rng.S.Generator with type g = 'a) -> g

`create 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.

`val generator : ``g Pervasives.ref`

Default generator. Functions in this module use this generator when not
explicitly supplied one.

Swapping the `generator`

is a way to subvert the random-generation process
e.g. to make it fully deterministic.

`generator`

defaults to Fortuna.

`val generate : ``?g:g -> int -> Cstruct.t`

`val block : ``g option -> int`

module Make_N:

Creates a suite of generating functions over a numeric type.

module Int:`S.N`

`with type t = int`

module Int32:`S.N`

`with type t = int32`

module Int64:`S.N`

`with type t = int64`

module Z:`S.N`

`with type t = Z.t`

`val prime : ``?g:g -> ?msb:int -> int -> Z.t`

`prime ~g ~msb bits`

generates a prime smaller than `2^bits`

, with `msb`

most significant bits set.
`prime ~g ~msb:1 bits`

(the default) yields a prime in the interval
`[2^(bits - 1), 2^bits - 1]`

.

`val safe_prime : ``?g:g -> int -> Z.t * Z.t`

`safe_prime ~g bits`

gives a prime pair `(g, p)`

such that `p = 2g + 1`

and `p`

has `bits`

significant bits.
Generating a random 13-byte `Cstruct.t`

:

`let cs = Rng.generate 13`

Generating a list of `Cstruct.t`

s, 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`

and an `int64`

in the range `[3, 7]`

:

`let f2 ?g () = Rng.(Z.gen ?g ~$10, Int64.gen_r 3L 8L)`

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
```

Generating a 17-bit prime with two leading bits set:

`let p = Rng.prime ~msb:2 17`

Fisher-Yates shuffle:

```
let f4 ?g arr =
let n = Array.length arr in
arr |> Array.iter @@ fun i ->
let j = Rng.Int.gen_r ?g i n in
let (a, b) = (arr.(i), arr.(j)) in
arr.(i) <- b ; arr.(j) <- a
```

type`buffer =`

`Cstruct.t`

Type definition to satisfy MirageOS RANDOM signature