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
