1=pod 2 3=head1 NAME 4 5life_cycle-cipher - The cipher algorithm life-cycle 6 7=head1 DESCRIPTION 8 9All symmetric ciphers (CIPHERs) go through a number of stages in their 10life-cycle: 11 12=over 4 13 14=item start 15 16This state represents the CIPHER before it has been allocated. It is the 17starting state for any life-cycle transitions. 18 19=item newed 20 21This state represents the CIPHER after it has been allocated. 22 23=item initialised 24 25These states represent the CIPHER when it is set up and capable of processing 26input. 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 40These states represent the CIPHER when it is set up and capable of processing 41additional input or generating output. The three possible states directly 42correspond to those for initialised above. The three different streams should 43not be mixed. 44 45=item finaled 46 47This state represents the CIPHER when it has generated output. 48 49=item freed 50 51This state is entered when the CIPHER is freed. It is the terminal state 52for all life-cycle transitions. 53 54=back 55 56=head2 State Transition Diagram 57 58The 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 121This section defines all of the legal state transitions. 122This 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 354At some point the EVP layer will begin enforcing the transitions described 355herein. 356 357=head1 SEE ALSO 358 359L<provider-cipher(7)>, L<EVP_EncryptInit(3)> 360 361=head1 COPYRIGHT 362 363Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. 364 365Licensed under the Apache License 2.0 (the "License"). You may not use 366this file except in compliance with the License. You can obtain a copy 367in the file LICENSE in the source distribution or at 368L<https://www.openssl.org/source/license.html>. 369 370=cut 371
