doc/man7/life_cycle-rand.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 life_cycle-rand - The RAND algorithm life-cycle
   6
   7 =head1 DESCRIPTION
   8
   9 All random number generator (RANDs)
  10 go through a number of stages in their life-cycle:
  11
  12 =over 4
  13
  14 =item start
  15
  16 This state represents the RAND before it has been allocated.  It is the
  17 starting state for any life-cycle transitions.
  18
  19 =item newed
  20
  21 This state represents the RAND after it has been allocated but unable to
  22 generate any output.
  23
  24 =item instantiated
  25
  26 This state represents the RAND when it is set up and capable of generating
  27 output.
  28
  29 =item uninstantiated
  30
  31 This state represents the RAND when it has been shutdown and it is no longer
  32 capable of generating output.
  33
  34 =item freed
  35
  36 This state is entered when the RAND is freed.  It is the terminal state
  37 for all life-cycle transitions.
  38
  39 =back
  40
  41 =head2 State Transition Diagram
  42
  43 The 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
  83 This section defines all of the legal state transitions.
  84 This 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
 173 At some point the EVP layer will begin enforcing the transitions described
 174 herein.
 175
 176 =head1 SEE ALSO
 177
 178 L<provider-rand(7)>, L<EVP_RAND(3)>.
 179
 180 =head1 HISTORY
 181
 182 The provider RAND interface was introduced in OpenSSL 3.0.
 183
 184 =head1 COPYRIGHT
 185
 186 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
 187
 188 Licensed under the Apache License 2.0 (the "License").  You may not use
 189 this file except in compliance with the License.  You can obtain a copy
 190 in the file LICENSE in the source distribution or at
 191 L<https://www.openssl.org/source/license.html>.
 192
 193 =cut