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