1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
.. _random_number_generators:
Random Number Generators
========================================
The base class ``RandomNumberGenerator`` is in the header ``botan/rng.h``.
The major interfaces are
.. cpp:function:: void RandomNumberGenerator::randomize(byte* output_array, size_t length)
Places *length* random bytes into the provided buffer.
.. cpp:function:: void RandomNumberGenerator::add_entropy(const byte* data, size_t length)
Incorporates provided data into the state of the PRNG, if at all
possible. This works for most RNG types, including the system and
TPM RNGs. But if the RNG doesn't support this operation, the data is
dropped, no error is indicated.
.. cpp:function:: void RandomNumberGenerator::randomize_with_input(byte* data, size_t length, \
const byte* ad, size_t ad_len)
Like randomize, but first incorporates the additional input field
into the state of the RNG. The additional input could be anything which
parameterizes this request.
.. cpp:function:: void RandomNumberGenerator::randomize_with_ts_input(byte* data, size_t length)
Creates a buffer with some timestamp values and calls ``randomize_with_input``
.. cpp:function:: byte RandomNumberGenerator::next_byte()
Generates a single random byte and returns it. Note that calling this
function several times is much slower than calling ``randomize`` once
to produce multiple bytes at a time.
RNG Types
----------------------------------------
The following RNG types are included
HMAC_DRBG
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
HMAC DRBG is a random number generator designed by NIST and specified
in SP 800-90A. It seems to be the most conservative generator of the
NIST approved options.
It can be instantiated with any HMAC but is typically used with
SHA-256, SHA-384, or SHA-512, as these are the hash functions approved
for this use by NIST.
System_RNG
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In ``system_rng.h``, objects of ``System_RNG`` reference a single
(process global) reference to the system PRNG (such as
``/dev/urandom`` or ``CryptGenRandom``).
You can also use the function ``system_rng()`` which returns a
reference to the global handle to the system RNG.
AutoSeeded_RNG
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AutoSeeded_RNG is type naming a 'best available' userspace PRNG. The
exact definition of this has changed over time and may change in the
future, fortunately there is no compatability concerns when changing
such an RNG.
Note well: like most other classes in Botan, it is not safe to share
an instance of ``AutoSeeded_RNG`` among multiple threads without
serialization.
The current version uses the HMAC_DRBG with SHA-384. The initial seed
is generated either by the system PRNG (if available) or a default set
of entropy sources. These are also used for periodic reseeding of the
RNG state.
ANSI X9.31
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This generator is deprecated and will be removed in a future release.
``ANSI_X931_PRNG`` is the standard issue X9.31 Appendix A.2.4 PRNG,
though using AES-256 instead of 3DES as the block cipher. This PRNG
implementation has been checked against official X9.31 test vectors.
Internally, the PRNG holds a pointer to another RNG object. This
internal PRNG generates the key and seed used by the X9.31 algorithm,
as well as the date/time vectors. Each time an X9.31 PRNG object
receives entropy, it passes it along to the PRNG it is holding, and
then pulls out some random bits to generate a new key and seed. This
PRNG considers itself seeded as soon as the internal PRNG is seeded.
Entropy Sources
---------------------------------
An ``EntropySource`` is an abstract representation of some method of
gather "real" entropy. This tends to be very system dependent. The
*only* way you should use an ``EntropySource`` is to pass it to a PRNG
that will extract entropy from it -- never use the output directly for
any kind of key or nonce generation!
``EntropySource`` has a pair of functions for getting entropy from
some external source, called ``fast_poll`` and ``slow_poll``. These
pass a buffer of bytes to be written; the functions then return how
many bytes of entropy were gathered.
Note for writers of ``EntropySource`` subclasses: it isn't necessary
to use any kind of cryptographic hash on your output. The data
produced by an EntropySource is only used by an application after it
has been hashed by the ``RandomNumberGenerator`` that asked for the
entropy, thus any hashing you do will be wasteful of both CPU cycles
and entropy.
Fork Safety
---------------------------------
On Unix platforms, the ``fork()`` and ``clone()`` system calls can
be used to spawn a new child process. Fork safety ensures that the
child process doesn't see the same output of random bytes as the
parent process. Botan tries to ensure fork safety by feeding the
process ID into the internal state of the random generator and by
automatically reseeding the random generator if the process ID
changed between two requests of random bytes. However, this does
not protect against PID wrap around. The process ID is usually
implemented as a 16 bit integer. In this scenario, a process will
spawn a new child process, which exits the parent process and
spawns a new child process himself. If the PID wrapped around, the
second child process may get assigned the process ID of it's
grandparent and the fork safety can not be ensured.
Therefore, it is strongly recommended to explicitly reseed the
random generator after forking a new process.
|
