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