xref: /freebsd/crypto/openssl/doc/man7/life_cycle-rand.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre Pronchery=pod
2*b077aed3SPierre Pronchery
3*b077aed3SPierre Pronchery=head1 NAME
4*b077aed3SPierre Pronchery
5*b077aed3SPierre Proncherylife_cycle-rand - The RAND algorithm life-cycle
6*b077aed3SPierre Pronchery
7*b077aed3SPierre Pronchery=head1 DESCRIPTION
8*b077aed3SPierre Pronchery
9*b077aed3SPierre ProncheryAll random number generator (RANDs)
10*b077aed3SPierre Proncherygo through a number of stages in their life-cycle:
11*b077aed3SPierre Pronchery
12*b077aed3SPierre Pronchery=over 4
13*b077aed3SPierre Pronchery
14*b077aed3SPierre Pronchery=item start
15*b077aed3SPierre Pronchery
16*b077aed3SPierre ProncheryThis state represents the RAND before it has been allocated.  It is the
17*b077aed3SPierre Proncherystarting state for any life-cycle transitions.
18*b077aed3SPierre Pronchery
19*b077aed3SPierre Pronchery=item newed
20*b077aed3SPierre Pronchery
21*b077aed3SPierre ProncheryThis state represents the RAND after it has been allocated but unable to
22*b077aed3SPierre Proncherygenerate any output.
23*b077aed3SPierre Pronchery
24*b077aed3SPierre Pronchery=item instantiated
25*b077aed3SPierre Pronchery
26*b077aed3SPierre ProncheryThis state represents the RAND when it is set up and capable of generating
27*b077aed3SPierre Proncheryoutput.
28*b077aed3SPierre Pronchery
29*b077aed3SPierre Pronchery=item uninstantiated
30*b077aed3SPierre Pronchery
31*b077aed3SPierre ProncheryThis state represents the RAND when it has been shutdown and it is no longer
32*b077aed3SPierre Proncherycapable of generating output.
33*b077aed3SPierre Pronchery
34*b077aed3SPierre Pronchery=item freed
35*b077aed3SPierre Pronchery
36*b077aed3SPierre ProncheryThis state is entered when the RAND is freed.  It is the terminal state
37*b077aed3SPierre Proncheryfor all life-cycle transitions.
38*b077aed3SPierre Pronchery
39*b077aed3SPierre Pronchery=back
40*b077aed3SPierre Pronchery
41*b077aed3SPierre Pronchery=head2 State Transition Diagram
42*b077aed3SPierre Pronchery
43*b077aed3SPierre ProncheryThe usual life-cycle of a RAND is illustrated:
44*b077aed3SPierre Pronchery
45*b077aed3SPierre Pronchery=begin man
46*b077aed3SPierre Pronchery
47*b077aed3SPierre Pronchery                        +-------------------------+
48*b077aed3SPierre Pronchery                        |          start          |
49*b077aed3SPierre Pronchery                        +-------------------------+
50*b077aed3SPierre Pronchery                          |
51*b077aed3SPierre Pronchery                          | EVP_RAND_CTX_new
52*b077aed3SPierre Pronchery                          v
53*b077aed3SPierre Pronchery                        +-------------------------+
54*b077aed3SPierre Pronchery                        |          newed          |
55*b077aed3SPierre Pronchery                        +-------------------------+
56*b077aed3SPierre Pronchery                          |
57*b077aed3SPierre Pronchery                          | EVP_RAND_instantiate
58*b077aed3SPierre Pronchery                          v
59*b077aed3SPierre Pronchery    EVP_RAND_generate   +-------------------------+
60*b077aed3SPierre Pronchery  +-------------------- |                         |
61*b077aed3SPierre Pronchery  |                     |      instantiated       |
62*b077aed3SPierre Pronchery  +-------------------> |                         | <+
63*b077aed3SPierre Pronchery                        +-------------------------+  '
64*b077aed3SPierre Pronchery                          |                          '
65*b077aed3SPierre Pronchery                          | EVP_RAND_uninstantiate   ' EVP_RAND_instantiate
66*b077aed3SPierre Pronchery                          v                          '
67*b077aed3SPierre Pronchery                        +-------------------------+  '
68*b077aed3SPierre Pronchery                        |     uninstantiated      | -+
69*b077aed3SPierre Pronchery                        +-------------------------+
70*b077aed3SPierre Pronchery                          |
71*b077aed3SPierre Pronchery                          | EVP_RAND_CTX_free
72*b077aed3SPierre Pronchery                          v
73*b077aed3SPierre Pronchery                        +-------------------------+
74*b077aed3SPierre Pronchery                        |          freed          |
75*b077aed3SPierre Pronchery                        +-------------------------+
76*b077aed3SPierre Pronchery
77*b077aed3SPierre Pronchery=end man
78*b077aed3SPierre Pronchery
79*b077aed3SPierre Pronchery=for html <img src="img/rand.png">
80*b077aed3SPierre Pronchery
81*b077aed3SPierre Pronchery=head2 Formal State Transitions
82*b077aed3SPierre Pronchery
83*b077aed3SPierre ProncheryThis section defines all of the legal state transitions.
84*b077aed3SPierre ProncheryThis is the canonical list.
85*b077aed3SPierre Pronchery
86*b077aed3SPierre Pronchery=begin man
87*b077aed3SPierre Pronchery
88*b077aed3SPierre Pronchery Function Call              ------------------ Current State ------------------
89*b077aed3SPierre Pronchery                            start   newed   instantiated  uninstantiated  freed
90*b077aed3SPierre Pronchery EVP_RAND_CTX_new           newed
91*b077aed3SPierre Pronchery EVP_RAND_instantiate            instantiated
92*b077aed3SPierre Pronchery EVP_RAND_generate                          instantiated
93*b077aed3SPierre Pronchery EVP_RAND_uninstantiate                    uninstantiated
94*b077aed3SPierre Pronchery EVP_RAND_CTX_free          freed   freed      freed          freed
95*b077aed3SPierre Pronchery EVP_RAND_CTX_get_params            newed   instantiated  uninstantiated  freed
96*b077aed3SPierre Pronchery EVP_RAND_CTX_set_params            newed   instantiated  uninstantiated  freed
97*b077aed3SPierre Pronchery EVP_RAND_CTX_gettable_params       newed   instantiated  uninstantiated  freed
98*b077aed3SPierre Pronchery EVP_RAND_CTX_settable_params       newed   instantiated  uninstantiated  freed
99*b077aed3SPierre Pronchery
100*b077aed3SPierre Pronchery=end man
101*b077aed3SPierre Pronchery
102*b077aed3SPierre Pronchery=begin html
103*b077aed3SPierre Pronchery
104*b077aed3SPierre Pronchery<table style="border:1px solid; border-collapse:collapse">
105*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">Function Call</th>
106*b077aed3SPierre Pronchery    <th style="border:1px solid" colspan="5">Current State</th></tr>
107*b077aed3SPierre Pronchery<tr><th style="border:1px solid"></th>
108*b077aed3SPierre Pronchery    <th style="border:1px solid" align="center">start</th>
109*b077aed3SPierre Pronchery    <th style="border:1px solid" align="center">newed</th>
110*b077aed3SPierre Pronchery    <th style="border:1px solid" align="center">instantiated</th>
111*b077aed3SPierre Pronchery    <th style="border:1px solid" align="center">uninstantiated</th>
112*b077aed3SPierre Pronchery    <th style="border:1px solid" align="center">freed</th></tr>
113*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_new</th>
114*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">newed</td>
115*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
116*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
117*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
118*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
119*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_instantiate</th>
120*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
121*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
122*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
123*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
124*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
125*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_generate</th>
126*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
127*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
128*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
129*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
130*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
131*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_uninstantiate</th>
132*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
133*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
134*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">uninstantiated</td>
135*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
136*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
137*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_free</th>
138*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">freed</td>
139*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">freed</td>
140*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">freed</td>
141*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">freed</td>
142*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
143*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_get_params</th>
144*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
145*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">newed</td>
146*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
147*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">uninstantiated</td>
148*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
149*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_set_params</th>
150*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
151*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">newed</td>
152*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
153*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">uninstantiated</td>
154*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
155*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_gettable_params</th>
156*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
157*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">newed</td>
158*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
159*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">uninstantiated</td>
160*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
161*b077aed3SPierre Pronchery<tr><th style="border:1px solid" align="left">EVP_RAND_CTX_settable_params</th>
162*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td>
163*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">newed</td>
164*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">instantiated</td>
165*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center">uninstantiated</td>
166*b077aed3SPierre Pronchery    <td style="border:1px solid" align="center"></td></tr>
167*b077aed3SPierre Pronchery</table>
168*b077aed3SPierre Pronchery
169*b077aed3SPierre Pronchery=end html
170*b077aed3SPierre Pronchery
171*b077aed3SPierre Pronchery=head1 NOTES
172*b077aed3SPierre Pronchery
173*b077aed3SPierre ProncheryAt some point the EVP layer will begin enforcing the transitions described
174*b077aed3SPierre Proncheryherein.
175*b077aed3SPierre Pronchery
176*b077aed3SPierre Pronchery=head1 SEE ALSO
177*b077aed3SPierre Pronchery
178*b077aed3SPierre ProncheryL<provider-rand(7)>, L<EVP_RAND(3)>.
179*b077aed3SPierre Pronchery
180*b077aed3SPierre Pronchery=head1 HISTORY
181*b077aed3SPierre Pronchery
182*b077aed3SPierre ProncheryThe provider RAND interface was introduced in OpenSSL 3.0.
183*b077aed3SPierre Pronchery
184*b077aed3SPierre Pronchery=head1 COPYRIGHT
185*b077aed3SPierre Pronchery
186*b077aed3SPierre ProncheryCopyright 2021 The OpenSSL Project Authors. All Rights Reserved.
187*b077aed3SPierre Pronchery
188*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
189*b077aed3SPierre Proncherythis file except in compliance with the License.  You can obtain a copy
190*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at
191*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>.
192*b077aed3SPierre Pronchery
193*b077aed3SPierre Pronchery=cut
194