doc/man7/life_cycle-digest.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 life_cycle-digest - The digest algorithm life-cycle
   6
   7 =head1 DESCRIPTION
   8
   9 All message digests (MDs) go through a number of stages in their life-cycle:
  10
  11 =over 4
  12
  13 =item start
  14
  15 This state represents the MD before it has been allocated.  It is the
  16 starting state for any life-cycle transitions.
  17
  18 =item newed
  19
  20 This state represents the MD after it has been allocated.
  21
  22 =item initialised
  23
  24 This state represents the MD when it is set up and capable of processing
  25 input.
  26
  27 =item updated
  28
  29 This state represents the MD when it is set up and capable of processing
  30 additional input or generating output.
  31
  32 =item finaled
  33
  34 This state represents the MD when it has generated output.
  35
  36 =item freed
  37
  38 This state is entered when the MD is freed.  It is the terminal state
  39 for all life-cycle transitions.
  40
  41 =back
  42
  43 =head2 State Transition Diagram
  44
  45 The usual life-cycle of a MD is illustrated:
  46
  47 =begin man
  48
  49                      +-------------------+
  50                      |       start       |
  51                      +-------------------+
  52                        |
  53                        | EVP_MD_CTX_new
  54                        v
  55                      +-------------------+         EVP_MD_CTX_reset
  56                      |       newed       | <------------------------------+
  57                      +-------------------+                                |
  58                        |                                                  |
  59                        | EVP_DigestInit                                   |
  60                        v                                                  |
  61                      +-------------------+                                |
  62                 +--> |    initialised    | <+ EVP_DigestInit              |
  63                 |    +-------------------+  |                             |
  64                 |      |                    |      EVP_DigestUpdate       |
  65                 |      | EVP_DigestUpdate   |    +------------------+     |
  66                 |      v                    |    v                  |     |
  67                 |    +------------------------------------------------+   |
  68  EVP_DigestInit |    |                    updated                     | --+
  69                 |    +------------------------------------------------+   |
  70                 |      |                    |                             |
  71                 |      | EVP_DigestFinal    | EVP_DigestFinalXOF          |
  72                 |      v                    v                             |
  73                 |    +------------------------------------------------+   |
  74                 +--- |                    finaled                     | --+
  75                      +------------------------------------------------+
  76                        |
  77                        | EVP_MD_CTX_free
  78                        v
  79                      +-------------------+
  80                      |       freed       |
  81                      +-------------------+
  82
  83 =end man
  84
  85 =for html <img src="img/digest.png">
  86
  87 =head2 Formal State Transitions
  88
  89 This section defines all of the legal state transitions.
  90 This is the canonical list.
  91
  92 =begin man
  93
  94  Function Call                --------------------- Current State ----------------------
  95                               start   newed    initialised   updated     finaled   freed
  96  EVP_MD_CTX_new               newed
  97  EVP_DigestInit                    initialised initialised initialised initialised
  98  EVP_DigestUpdate                                updated     updated
  99  EVP_DigestFinal                                             finaled
 100  EVP_DigestFinalXOF                                          finaled
 101  EVP_MD_CTX_free              freed   freed       freed       freed       freed
 102  EVP_MD_CTX_reset                     newed       newed       newed       newed
 103  EVP_MD_CTX_get_params                newed    initialised   updated
 104  EVP_MD_CTX_set_params                newed    initialised   updated
 105  EVP_MD_CTX_gettable_params           newed    initialised   updated
 106  EVP_MD_CTX_settable_params           newed    initialised   updated
 107
 108 =end man
 109
 110 =begin html
 111
 112 <table style="border:1px solid; border-collapse:collapse">
 113 <tr><th style="border:1px solid" align="left">Function Call</th>
 114     <th style="border:1px solid" colspan="6">Current State</th></tr>
 115 <tr><th style="border:1px solid"></th>
 116     <th style="border:1px solid" align="center">start</th>
 117     <th style="border:1px solid" align="center">newed</th>
 118     <th style="border:1px solid" align="center">initialised</th>
 119     <th style="border:1px solid" align="center">updated</th>
 120     <th style="border:1px solid" align="center">finaled</th>
 121     <th style="border:1px solid" align="center">freed</th></tr>
 122 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_new</th>
 123     <td style="border:1px solid" align="center">newed</td>
 124     <td style="border:1px solid" align="center"></td>
 125     <td style="border:1px solid" align="center"></td>
 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"></td></tr>
 129 <tr><th style="border:1px solid" align="left">EVP_DigestInit</th>
 130     <td style="border:1px solid" align="center"></td>
 131     <td style="border:1px solid" align="center">initialised</td>
 132     <td style="border:1px solid" align="center">initialised</td>
 133     <td style="border:1px solid" align="center">initialised</td>
 134     <td style="border:1px solid" align="center">initialised</td>
 135     <td style="border:1px solid" align="center"></td></tr>
 136 <tr><th style="border:1px solid" align="left">EVP_DigestUpdate</th>
 137     <td style="border:1px solid" align="center"></td>
 138     <td style="border:1px solid" align="center"></td>
 139     <td style="border:1px solid" align="center">updated</td>
 140     <td style="border:1px solid" align="center">updated</td>
 141     <td style="border:1px solid" align="center"></td>
 142     <td style="border:1px solid" align="center"></td></tr>
 143 <tr><th style="border:1px solid" align="left">EVP_DigestFinal</th>
 144     <td style="border:1px solid" align="center"></td>
 145     <td style="border:1px solid" align="center"></td>
 146     <td style="border:1px solid" align="center"></td>
 147     <td style="border:1px solid" align="center">finaled</td>
 148     <td style="border:1px solid" align="center"></td>
 149     <td style="border:1px solid" align="center"></td></tr>
 150 <tr><th style="border:1px solid" align="left">EVP_DigestFinalXOF</th>
 151     <td style="border:1px solid" align="center"></td>
 152     <td style="border:1px solid" align="center"></td>
 153     <td style="border:1px solid" align="center"></td>
 154     <td style="border:1px solid" align="center">finaled</td>
 155     <td style="border:1px solid" align="center"></td>
 156     <td style="border:1px solid" align="center"></td></tr>
 157 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_free</th>
 158     <td style="border:1px solid" align="center">freed</td>
 159     <td style="border:1px solid" align="center">freed</td>
 160     <td style="border:1px solid" align="center">freed</td>
 161     <td style="border:1px solid" align="center">freed</td>
 162     <td style="border:1px solid" align="center">freed</td>
 163     <td style="border:1px solid" align="center"></td></tr>
 164 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_reset</th>
 165     <td style="border:1px solid" align="center"></td>
 166     <td style="border:1px solid" align="center">newed</td>
 167     <td style="border:1px solid" align="center">newed</td>
 168     <td style="border:1px solid" align="center">newed</td>
 169     <td style="border:1px solid" align="center">newed</td>
 170     <td style="border:1px solid" align="center"></td></tr>
 171 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_get_params</th>
 172     <td style="border:1px solid" align="center"></td>
 173     <td style="border:1px solid" align="center">newed</td>
 174     <td style="border:1px solid" align="center">initialised</td>
 175     <td style="border:1px solid" align="center">updated</td>
 176     <td style="border:1px solid" align="center"></td>
 177     <td style="border:1px solid" align="center"></td></tr>
 178 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_set_params</th>
 179     <td style="border:1px solid" align="center"></td>
 180     <td style="border:1px solid" align="center">newed</td>
 181     <td style="border:1px solid" align="center">initialised</td>
 182     <td style="border:1px solid" align="center">updated</td>
 183     <td style="border:1px solid" align="center"></td>
 184     <td style="border:1px solid" align="center"></td></tr>
 185 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_gettable_params</th>
 186     <td style="border:1px solid" align="center"></td>
 187     <td style="border:1px solid" align="center">newed</td>
 188     <td style="border:1px solid" align="center">initialised</td>
 189     <td style="border:1px solid" align="center">updated</td>
 190     <td style="border:1px solid" align="center"></td>
 191     <td style="border:1px solid" align="center"></td></tr>
 192 <tr><th style="border:1px solid" align="left">EVP_MD_CTX_settable_params</th>
 193     <td style="border:1px solid" align="center"></td>
 194     <td style="border:1px solid" align="center">newed</td>
 195     <td style="border:1px solid" align="center">initialised</td>
 196     <td style="border:1px solid" align="center">updated</td>
 197     <td style="border:1px solid" align="center"></td>
 198     <td style="border:1px solid" align="center"></td></tr>
 199 </table>
 200
 201 =end html
 202
 203 =head1 NOTES
 204
 205 At some point the EVP layer will begin enforcing the transitions described
 206 herein.
 207
 208 =head1 SEE ALSO
 209
 210 L<provider-digest(7)>, L<EVP_DigestInit(3)>
 211
 212 =head1 COPYRIGHT
 213
 214 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
 215
 216 Licensed under the Apache License 2.0 (the "License").  You may not use
 217 this file except in compliance with the License.  You can obtain a copy
 218 in the file LICENSE in the source distribution or at
 219 L<https://www.openssl.org/source/license.html>.
 220
 221 =cut