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