doc/man7/life_cycle-cipher.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 life_cycle-cipher - The cipher algorithm life-cycle
   6
   7 =head1 DESCRIPTION
   8
   9 All symmetric ciphers (CIPHERs) go through a number of stages in their
  10 life-cycle:
  11
  12 =over 4
  13
  14 =item start
  15
  16 This state represents the CIPHER 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 CIPHER after it has been allocated.
  22
  23 =item initialised
  24
  25 These states represent the CIPHER when it is set up and capable of processing
  26 input.  There are three possible initialised states:
  27
  28 =over 4
  29
  30 =item initialised using EVP_CipherInit
  31
  32 =item initialised for decryption using EVP_DecryptInit
  33
  34 =item initialised for encryption using EVP_EncryptInit
  35
  36 =back
  37
  38 =item updated
  39
  40 These states represent the CIPHER when it is set up and capable of processing
  41 additional input or generating output.  The three possible states directly
  42 correspond to those for initialised above.  The three different streams should
  43 not be mixed.
  44
  45 =item finaled
  46
  47 This state represents the CIPHER when it has generated output.
  48
  49 =item freed
  50
  51 This state is entered when the CIPHER is freed.  It is the terminal state
  52 for all life-cycle transitions.
  53
  54 =back
  55
  56 =head2 State Transition Diagram
  57
  58 The usual life-cycle of a CIPHER is illustrated:
  59
  60 =begin man
  61
  62                                  +---------------------------+
  63                                  |                           |
  64                                  |           start           |
  65                                  |                           |
  66                                  +---------------------------+   + - - - - - - - - - - - - - +
  67                                        |                         '  any of the initialised   '
  68                                        | EVP_CIPHER_CTX_new      ' updated or finaled states '
  69                                        v                         '                           '
  70                                  +---------------------------+   + - - - - - - - - - - - - - +
  71                                  |                           |      |
  72                                  |           newed           |      | EVP_CIPHER_CTX_reset
  73                                  |                           | <----+
  74                                  +---------------------------+
  75                                     |   |                 |
  76                           +---------+   |                 +---------+
  77           EVP_DecryptInit |             | EVP_CipherInit            | EVP_EncryptInit
  78                           v             v                           v
  79  +---------------------------+   +---------------------------+   +---------------------------+
  80  |                           |   |                           |   |                           |
  81  |        initialised        |   |        initialised        |   |        initialised        |
  82  |       for decryption      |   |                           |   |       for encryption      |
  83  +---------------------------+   +---------------------------+   +---------------------------+
  84    |                                   |                                                   |
  85    | EVP_DecryptUpdate                 | EVP_CipherUpdate                EVP_EncryptUpdate |
  86    |                                   v                                                   |
  87    |                             +---------------------------+                             |
  88    |                             |                           |--------------------+        |
  89    |                             |          updated          |   EVP_CipherUpdate |        |
  90    |                             |                           | <------------------+        |
  91    v                             +---------------------------+                             v
  92  +---------------------------+                         |         +---------------------------+
  93  |                           |---------------------+   |         |                           |
  94  |          updated          |   EVP_DecryptUpdate |   |         |          updated          |------+
  95  |       for decryption      | <-------------------+   |         |       for encryption      |      |
  96  +---------------------------+                         |         +---------------------------+      |
  97                           |            EVP_CipherFinal |            |           ^                   |
  98                           +-------+                    |   +--------+           |                   |
  99                  EVP_DecryptFinal |                    |   | EVP_EncryptFinal   +-------------------+
 100                                   v                    v   v                      EVP_EncryptUpdate
 101                                  +---------------------------+
 102                                  |                           |-----------------------------+
 103                                  |          finaled          |                             |
 104                                  |                           | <---------------------------+
 105                                  +---------------------------+   EVP_CIPHER_CTX_get_params
 106                                        |                             (AEAD encryption)
 107                                        | EVP_CIPHER_CTX_free
 108                                        v
 109                                  +---------------------------+
 110                                  |                           |
 111                                  |           freed           |
 112                                  |                           |
 113                                  +---------------------------+
 114
 115 =end man
 116
 117 =for html <img src="img/cipher.png">
 118
 119 =head2 Formal State Transitions
 120
 121 This section defines all of the legal state transitions.
 122 This is the canonical list.
 123
 124 =begin man
 125
 126  Function Call                ---------------------------------------------- Current State -----------------------------------------------
 127                               start   newed    initialised   updated     finaled   initialised   updated    initialised   updated    freed
 128                                                                                     decryption  decryption   encryption  encryption
 129  EVP_CIPHER_CTX_new           newed
 130  EVP_CipherInit                    initialised initialised initialised initialised initialised initialised  initialised initialised
 131  EVP_DecryptInit                   initialised initialised initialised initialised initialised initialised  initialised initialised
 132                                     decryption  decryption  decryption  decryption  decryption  decryption  decryption  decryption
 133  EVP_EncryptInit                   initialised initialised initialised initialised initialised initialised  initialised initialised
 134                                     encryption  encryption  encryption  encryption  encryption  encryption  encryption  encryption
 135  EVP_CipherUpdate                                updated     updated
 136  EVP_DecryptUpdate                                                                   updated     updated
 137                                                                                     decryption  decryption
 138  EVP_EncryptUpdate                                                                                            updated     updated
 139                                                                                                              encryption  encryption
 140  EVP_CipherFinal                                             finaled
 141  EVP_DecryptFinal                                                                                finaled
 142  EVP_EncryptFinal                                                                                                         finaled
 143  EVP_CIPHER_CTX_free          freed   freed       freed       freed       freed       freed       freed        freed       freed
 144  EVP_CIPHER_CTX_reset                 newed       newed       newed       newed       newed       newed        newed       newed
 145  EVP_CIPHER_CTX_get_params            newed    initialised   updated               initialised   updated    initialised   updated
 146                                                                                     decryption  decryption   encryption  encryption
 147  EVP_CIPHER_CTX_set_params            newed    initialised   updated               initialised   updated    initialised   updated
 148                                                                                     decryption  decryption   encryption  encryption
 149  EVP_CIPHER_CTX_gettable_params       newed    initialised   updated               initialised   updated    initialised   updated
 150                                                                                     decryption  decryption   encryption  encryption
 151  EVP_CIPHER_CTX_settable_params       newed    initialised   updated               initialised   updated    initialised   updated
 152                                                                                     decryption  decryption   encryption  encryption
 153
 154 =end man
 155
 156 =begin html
 157
 158 <table style="border:1px solid; border-collapse:collapse">
 159 <tr><th style="border:1px solid" align="left">Function Call</th>
 160     <th style="border:1px solid" colspan="10">Current State</th></tr>
 161 <tr><th style="border:1px solid"></th>
 162     <th style="border:1px solid" align="center">start</th>
 163     <th style="border:1px solid" align="center">newed</th>
 164     <th style="border:1px solid" align="center">initialised</th>
 165     <th style="border:1px solid" align="center">updated</th>
 166     <th style="border:1px solid" align="center">finaled</th>
 167     <th style="border:1px solid" align="center">initialised<br>decryption</th>
 168     <th style="border:1px solid" align="center">updated<br>decryption</th>
 169     <th style="border:1px solid" align="center">initialised<br>encryption</th>
 170     <th style="border:1px solid" align="center">updated<br>encryption</th>
 171     <th style="border:1px solid" align="center">freed</th></tr>
 172 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_new</th>
 173     <td style="border:1px solid" align="center">newed</td>
 174     <td style="border:1px solid" align="center"></td>
 175     <td style="border:1px solid" align="center"></td>
 176     <td style="border:1px solid" align="center"></td>
 177     <td style="border:1px solid" align="center"></td>
 178     <td style="border:1px solid" align="center"></td>
 179     <td style="border:1px solid" align="center"></td>
 180     <td style="border:1px solid" align="center"></td>
 181     <td style="border:1px solid" align="center"></td>
 182     <td style="border:1px solid" align="center"></td></tr>
 183 <tr><th style="border:1px solid" align="left">EVP_CipherInit</th>
 184     <td style="border:1px solid" align="center"></td>
 185     <td style="border:1px solid" align="center">initialised</td>
 186     <td style="border:1px solid" align="center">initialised</td>
 187     <td style="border:1px solid" align="center">initialised</td>
 188     <td style="border:1px solid" align="center">initialised</td>
 189     <td style="border:1px solid" align="center">initialised</td>
 190     <td style="border:1px solid" align="center">initialised</td>
 191     <td style="border:1px solid" align="center">initialised</td>
 192     <td style="border:1px solid" align="center">initialised</td>
 193     <td style="border:1px solid" align="center"></td></tr>
 194 <tr><th style="border:1px solid" align="left">EVP_DecryptInit</th>
 195     <td style="border:1px solid" align="center"></td>
 196     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 197     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 198     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 199     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 200     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 201     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 202     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 203     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 204     <td style="border:1px solid" align="center"></td></tr>
 205 <tr><th style="border:1px solid" align="left">EVP_EncryptInit</th>
 206     <td style="border:1px solid" align="center"></td>
 207     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 208     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 209     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 210     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 211     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 212     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 213     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 214     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 215     <td style="border:1px solid" align="center"></td></tr>
 216 <tr><th style="border:1px solid" align="left">EVP_CipherUpdate</th>
 217     <td style="border:1px solid" align="center"></td>
 218     <td style="border:1px solid" align="center"></td>
 219     <td style="border:1px solid" align="center">updated</td>
 220     <td style="border:1px solid" align="center">updated</td>
 221     <td style="border:1px solid" align="center"></td>
 222     <td style="border:1px solid" align="center"></td>
 223     <td style="border:1px solid" align="center"></td>
 224     <td style="border:1px solid" align="center"></td>
 225     <td style="border:1px solid" align="center"></td>
 226     <td style="border:1px solid" align="center"></td></tr>
 227 <tr><th style="border:1px solid" align="left">EVP_DecryptUpdate</th>
 228     <td style="border:1px solid" align="center"></td>
 229     <td style="border:1px solid" align="center"></td>
 230     <td style="border:1px solid" align="center"></td>
 231     <td style="border:1px solid" align="center"></td>
 232     <td style="border:1px solid" align="center"></td>
 233     <td style="border:1px solid" align="center">updated<br>decryption</td>
 234     <td style="border:1px solid" align="center">updated<br>decryption</td>
 235     <td style="border:1px solid" align="center"></td>
 236     <td style="border:1px solid" align="center"></td>
 237     <td style="border:1px solid" align="center"></td></tr>
 238 <tr><th style="border:1px solid" align="left">EVP_EncryptUpdate</th>
 239     <td style="border:1px solid" align="center"></td>
 240     <td style="border:1px solid" align="center"></td>
 241     <td style="border:1px solid" align="center"></td>
 242     <td style="border:1px solid" align="center"></td>
 243     <td style="border:1px solid" align="center"></td>
 244     <td style="border:1px solid" align="center"></td>
 245     <td style="border:1px solid" align="center"></td>
 246     <td style="border:1px solid" align="center">updated<br>encryption</td>
 247     <td style="border:1px solid" align="center">updated<br>encryption</td>
 248     <td style="border:1px solid" align="center"></td></tr>
 249 <tr><th style="border:1px solid" align="left">EVP_CipherFinal</th>
 250     <td style="border:1px solid" align="center"></td>
 251     <td style="border:1px solid" align="center"></td>
 252     <td style="border:1px solid" align="center"></td>
 253     <td style="border:1px solid" align="center">finaled</td>
 254     <td style="border:1px solid" align="center"></td>
 255     <td style="border:1px solid" align="center"></td>
 256     <td style="border:1px solid" align="center"></td>
 257     <td style="border:1px solid" align="center"></td>
 258     <td style="border:1px solid" align="center"></td>
 259     <td style="border:1px solid" align="center"></td></tr>
 260 <tr><th style="border:1px solid" align="left">EVP_DecryptFinal</th>
 261     <td style="border:1px solid" align="center"></td>
 262     <td style="border:1px solid" align="center"></td>
 263     <td style="border:1px solid" align="center"></td>
 264     <td style="border:1px solid" align="center"></td>
 265     <td style="border:1px solid" align="center"></td>
 266     <td style="border:1px solid" align="center"></td>
 267     <td style="border:1px solid" align="center">finaled<br>decryption</td>
 268     <td style="border:1px solid" align="center"></td>
 269     <td style="border:1px solid" align="center"></td>
 270     <td style="border:1px solid" align="center"></td></tr>
 271 <tr><th style="border:1px solid" align="left">EVP_EncryptFinal</th>
 272     <td style="border:1px solid" align="center"></td>
 273     <td style="border:1px solid" align="center"></td>
 274     <td style="border:1px solid" align="center"></td>
 275     <td style="border:1px solid" align="center"></td>
 276     <td style="border:1px solid" align="center"></td>
 277     <td style="border:1px solid" align="center"></td>
 278     <td style="border:1px solid" align="center"></td>
 279     <td style="border:1px solid" align="center"></td>
 280     <td style="border:1px solid" align="center">finaled<br>decryption</td>
 281     <td style="border:1px solid" align="center"></td></tr>
 282 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_free</th>
 283     <td style="border:1px solid" align="center">freed</td>
 284     <td style="border:1px solid" align="center">freed</td>
 285     <td style="border:1px solid" align="center">freed</td>
 286     <td style="border:1px solid" align="center">freed</td>
 287     <td style="border:1px solid" align="center">freed</td>
 288     <td style="border:1px solid" align="center">freed</td>
 289     <td style="border:1px solid" align="center">freed</td>
 290     <td style="border:1px solid" align="center">freed</td>
 291     <td style="border:1px solid" align="center">freed</td>
 292     <td style="border:1px solid" align="center"></td></tr>
 293 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_reset</th>
 294     <td style="border:1px solid" align="center"></td>
 295     <td style="border:1px solid" align="center"></td>
 296     <td style="border:1px solid" align="center">newed</td>
 297     <td style="border:1px solid" align="center">newed</td>
 298     <td style="border:1px solid" align="center">newed</td>
 299     <td style="border:1px solid" align="center">newed</td>
 300     <td style="border:1px solid" align="center">newed</td>
 301     <td style="border:1px solid" align="center">newed</td>
 302     <td style="border:1px solid" align="center">newed</td>
 303     <td style="border:1px solid" align="center"></td></tr>
 304 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_get_params</th>
 305     <td style="border:1px solid" align="center"></td>
 306     <td style="border:1px solid" align="center">newed</td>
 307     <td style="border:1px solid" align="center">initialised</td>
 308     <td style="border:1px solid" align="center">updated</td>
 309     <td style="border:1px solid" align="center"></td>
 310     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 311     <td style="border:1px solid" align="center">updated<br>decryption</td>
 312     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 313     <td style="border:1px solid" align="center">updated<br>encryption</td>
 314     <td style="border:1px solid" align="center"></td></tr>
 315 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_set_params</th>
 316     <td style="border:1px solid" align="center"></td>
 317     <td style="border:1px solid" align="center">newed</td>
 318     <td style="border:1px solid" align="center">initialised</td>
 319     <td style="border:1px solid" align="center">updated</td>
 320     <td style="border:1px solid" align="center"></td>
 321     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 322     <td style="border:1px solid" align="center">updated<br>decryption</td>
 323     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 324     <td style="border:1px solid" align="center">updated<br>encryption</td>
 325     <td style="border:1px solid" align="center"></td></tr>
 326 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_gettable_params</th>
 327     <td style="border:1px solid" align="center"></td>
 328     <td style="border:1px solid" align="center">newed</td>
 329     <td style="border:1px solid" align="center">initialised</td>
 330     <td style="border:1px solid" align="center">updated</td>
 331     <td style="border:1px solid" align="center"></td>
 332     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 333     <td style="border:1px solid" align="center">updated<br>decryption</td>
 334     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 335     <td style="border:1px solid" align="center">updated<br>encryption</td>
 336     <td style="border:1px solid" align="center"></td></tr>
 337 <tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_settable_params</th>
 338     <td style="border:1px solid" align="center"></td>
 339     <td style="border:1px solid" align="center">newed</td>
 340     <td style="border:1px solid" align="center">initialised</td>
 341     <td style="border:1px solid" align="center">updated</td>
 342     <td style="border:1px solid" align="center"></td>
 343     <td style="border:1px solid" align="center">initialised<br>decryption</td>
 344     <td style="border:1px solid" align="center">updated<br>decryption</td>
 345     <td style="border:1px solid" align="center">initialised<br>encryption</td>
 346     <td style="border:1px solid" align="center">updated<br>encryption</td>
 347     <td style="border:1px solid" align="center"></td></tr>
 348 </table>
 349
 350 =end html
 351
 352 =head1 NOTES
 353
 354 At some point the EVP layer will begin enforcing the transitions described
 355 herein.
 356
 357 =head1 SEE ALSO
 358
 359 L<provider-cipher(7)>, L<EVP_EncryptInit(3)>
 360
 361 =head1 COPYRIGHT
 362
 363 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
 364
 365 Licensed under the Apache License 2.0 (the "License").  You may not use
 366 this file except in compliance with the License.  You can obtain a copy
 367 in the file LICENSE in the source distribution or at
 368 L<https://www.openssl.org/source/license.html>.
 369
 370 =cut