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. 35 36=item freed 37 38This state is entered when the MD is freed. It is the terminal state 39for all life-cycle transitions. 40 41=back 42 43=head2 State Transition Diagram 44 45The 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 89This section defines all of the legal state transitions. 90This 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 205At some point the EVP layer will begin enforcing the transitions described 206herein. 207 208=head1 SEE ALSO 209 210L<provider-digest(7)>, L<EVP_DigestInit(3)> 211 212=head1 COPYRIGHT 213 214Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. 215 216Licensed under the Apache License 2.0 (the "License"). You may not use 217this file except in compliance with the License. You can obtain a copy 218in the file LICENSE in the source distribution or at 219L<https://www.openssl.org/source/license.html>. 220 221=cut 222
