concrete_csprng/lib.rs
1#![deny(rustdoc::broken_intra_doc_links)]
2//! Cryptographically secure pseudo random number generator.
3//!
4//! Welcome to the `concrete-csprng` documentation.
5//!
6//! This crate provides a fast cryptographically secure pseudo-random number generator, suited to
7//! work in a multithreaded setting.
8//!
9//! Random Generators
10//! =================
11//!
12//! The central abstraction of this crate is the [`RandomGenerator`](generators::RandomGenerator)
13//! trait, which is implemented by different types, each supporting a different platform. In
14//! essence, a type implementing [`RandomGenerator`](generators::RandomGenerator) is a type that
15//! outputs a new pseudo-random byte at each call to
16//! [`next_byte`](generators::RandomGenerator::next_byte). Such a generator `g` can be seen as
17//! enclosing a growing index into an imaginary array of pseudo-random bytes:
18//! ```ascii
19//! 0 1 2 3 4 5 6 7 8 9 M-1 │
20//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
21//! ┃ │ │ │ │ │ │ │ │ │ │...│ ┃ │
22//! ┗↥┷━┷━┷━┷━┷━┷━┷━┷━┷━┷━━━┷━┛ │
23//! g │
24//! │
25//! g.next_byte() │
26//! │
27//! 0 1 2 3 4 5 6 7 8 9 M-1 │
28//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
29//! ┃╳│ │ │ │ │ │ │ │ │ │...│ ┃ │
30//! ┗━┷↥┷━┷━┷━┷━┷━┷━┷━┷━┷━━━┷━┛ │
31//! g │
32//! │
33//! g.next_byte() │ legend:
34//! │ -------
35//! 0 1 2 3 4 5 6 7 8 9 M-1 │ ↥ : next byte to be outputted by g
36//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │ │ │: byte not yet outputted by g
37//! ┃╳│╳│ │ │ │ │ │ │ │ │...│ ┃ │ │╳│: byte already outputted by g
38//! ┗━┷━┷↥┷━┷━┷━┷━┷━┷━┷━┷━━━┷━┛ │
39//! g 🭭
40//! ```
41//!
42//! While being large, this imaginary array is still bounded to M = 2¹³² bytes. Consequently, a
43//! generator is always bounded to a maximal index. That is, there is always a max amount of
44//! elements of this array that can be outputted by the generator. By default, generators created
45//! via [`new`](generators::RandomGenerator::new) are always bounded to M-1.
46//!
47//! Tree partition of the pseudo-random stream
48//! ==========================================
49//!
50//! One particularity of this implementation is that you can use the
51//! [`try_fork`](generators::RandomGenerator::try_fork) method to create an arbitrary partition tree
52//! of a region of this array. Indeed, calling `try_fork(nc, nb)` outputs `nc` new generators, each
53//! able to output `nb` bytes. The `try_fork` method ensures that the states and bounds of the
54//! parent and children generators are set so as to prevent the same substream to be outputted
55//! twice:
56//! ```ascii
57//! 0 1 2 3 4 5 6 7 8 9 M │
58//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
59//! ┃P│P│P│P│P│P│P│P│P│P│...│P┃ │
60//! ┗↥┷━┷━┷━┷━┷━┷━┷━┷━┷━┷━━━┷━┛ │
61//! p │
62//! │
63//! (a,b) = p.fork(2,4) │
64//! │
65//! 0 1 2 3 4 5 6 7 8 9 M │
66//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
67//! ┃A│A│A│A│B│B│B│B│P│P│...│P┃ │
68//! ┗↥┷━┷━┷━┷↥┷━┷━┷━┷↥┷━┷━━━┷━┛ │
69//! a b p │
70//! │ legend:
71//! (c,d) = b.fork(2, 1) │ -------
72//! │ ↥ : next byte to be outputted by p
73//! 0 1 2 3 4 5 6 7 8 9 M │ │P│: byte to be outputted by p
74//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │ │╳│: byte already outputted
75//! ┃A│A│A│A│C│D│B│B│P│P│...│P┃ │
76//! ┗↥┷━┷━┷━┷↥┷↥┷↥┷━┷↥┷━┷━━━┷━┛ │
77//! a c d b p 🭭
78//! ```
79//!
80//! This makes it possible to consume the stream at different places. This is particularly useful in
81//! a multithreaded setting, in which we want to use the same generator from different independent
82//! threads:
83//!
84//! ```ascii
85//! 0 1 2 3 4 5 6 7 8 9 M │
86//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
87//! ┃A│A│A│A│C│D│B│B│P│P│...│P┃ │
88//! ┗↥┷━┷━┷━┷↥┷↥┷↥┷━┷↥┷━┷━━━┷━┛ │
89//! a c d b p │
90//! │
91//! a.next_byte() │
92//! │
93//! 0 1 2 3 4 5 6 7 8 9 M │
94//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │
95//! ┃╳│A│A│A│C│D│B│B│P│P│...│P┃ │
96//! ┗━┷↥┷━┷━┷↥┷↥┷↥┷━┷↥┷━┷━━━┷━┛ │
97//! a c d b p │
98//! │ legend:
99//! b.next_byte() │ -------
100//! │ ↥ : next byte to be outputted by p
101//! 0 1 2 3 4 5 6 7 8 9 M │ │P│: byte to be outputted by p
102//! ┏━┯━┯━┯━┯━┯━┯━┯━┯━┯━┯━━━┯━┓ │ │╳│: byte already outputted
103//! ┃╳│A│A│A│C│D│╳│B│P│P│...│P┃ │
104//! ┗━┷↥┷━┷━┷↥┷↥┷━┷↥┷↥┷━┷━━━┷━┛ │
105//! a c d b p 🭭
106//! ```
107//!
108//! Implementation
109//! ==============
110//!
111//! The implementation is based on the AES blockcipher used in counter (CTR) mode, as presented
112//! in the ISO/IEC 18033-4 document.
113pub mod generators;
114pub mod seeders;