From: Pauli Date: Mon, 7 Jun 2021 05:11:28 +0000 (+1000) Subject: doc: add cipher life cycle documentation X-Git-Tag: openssl-3.0.0-beta1~155 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c0fc3fe3496ec02b0cafb252b7764f53cc3ae643;p=thirdparty%2Fopenssl.git doc: add cipher life cycle documentation Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/15637) --- diff --git a/doc/man7/img/cipher.png b/doc/man7/img/cipher.png new file mode 100644 index 00000000000..79b8b621e6a Binary files /dev/null and b/doc/man7/img/cipher.png differ diff --git a/doc/man7/life_cycle-cipher.pod b/doc/man7/life_cycle-cipher.pod new file mode 100644 index 00000000000..227cc18b8d7 --- /dev/null +++ b/doc/man7/life_cycle-cipher.pod @@ -0,0 +1,370 @@ +=pod + +=head1 NAME + +life_cycle-cipher - The cipher algorithm life-cycle + +=head1 DESCRIPTION + +All symmetric ciphers (CIPHERs) go through a number of stages in their +life-cycle: + +=over 4 + +=item start + +This state represents the CIPHER before it has been allocated. It is the +starting state for any life-cycle transitions. + +=item newed + +This state represents the CIPHER after it has been allocated. + +=item initialised + +These states represent the CIPHER when it is set up and capable of processing +input. There are three possible initialised states: + +=over 4 + +=item initialised using EVP_CipherInit + +=item initialised for decryption using EVP_DecryptInit + +=item initialised for encryption using EVP_EncryptInit + +=back + +=item updated + +These states represent the CIPHER when it is set up and capable of processing +additional input or generating output. The three possible states directly +correspond to those for initialised above. The three different streams should +not be mixed. + +=item finaled + +This state represents the CIPHER when it has generated output. + +=item freed + +This state is entered when the CIPHER is freed. It is the terminal state +for all life-cycle transitions. + +=back + +=head2 State Transition Diagram + +The usual life-cycle of a CIPHER is illustrated: + +=begin man + + +---------------------------+ + | | + | start | + | | + +---------------------------+ + - - - - - - - - - - - - - + + | ' any of the initialised ' + | EVP_CIPHER_CTX_new ' updated or finaled states ' + v ' ' + +---------------------------+ + - - - - - - - - - - - - - + + | | | + | newed | | EVP_CIPHER_CTX_reset + | | <----+ + +---------------------------+ + | | | + +---------+ | +---------+ + EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit + v v v + +---------------------------+ +---------------------------+ +---------------------------+ + | | | | | | + | initialised | | initialised | | initialised | + | for decryption | | | | for encryption | + +---------------------------+ +---------------------------+ +---------------------------+ + | | | + | EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate | + | v | + | +---------------------------+ | + | | |--------------------+ | + | | updated | EVP_CipherUpdate | | + | | | <------------------+ | + v +---------------------------+ v + +---------------------------+ | +---------------------------+ + | |---------------------+ | | | + | updated | EVP_DecryptUpdate | | | updated |------+ + | for decryption | <-------------------+ | | for encryption | | + +---------------------------+ | +---------------------------+ | + | EVP_CipherFinal | | ^ | + +-------+ | +--------+ | | + EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+ + v v v EVP_EncryptUpdate + +---------------------------+ + | |-----------------------------+ + | finaled | | + | | <---------------------------+ + +---------------------------+ EVP_CIPHER_CTX_get_params + | (AEAD encryption) + | EVP_CIPHER_CTX_free + v + +---------------------------+ + | | + | freed | + | | + +---------------------------+ + +=end man + +=for html + +=head2 Formal State Transitions + +This section defines all of the legal state transitions. +This is the canonical list. + +=begin man + + Function Call ---------------------------------------------- Current State ----------------------------------------------- + start newed initialised updated finaled initialised updated initialised updated freed + decryption decryption encryption encryption + EVP_CIPHER_CTX_new newed + EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised + EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised + decryption decryption decryption decryption decryption decryption decryption decryption + EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised + encryption encryption encryption encryption encryption encryption encryption encryption + EVP_CipherUpdate updated updated + EVP_DecryptUpdate updated updated + decryption decryption + EVP_EncryptUpdate updated updated + encryption encryption + EVP_CipherFinal finaled + EVP_DecryptFinal finaled + EVP_EncryptFinal finaled + EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed + EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed + EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated + decryption decryption encryption encryption + +=end man + +=begin html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function CallCurrent State
startnewedinitialisedupdatedfinaledinitialised
decryption		updated
decryption		initialised
encryption		updated
encryption		freed
EVP_CIPHER_CTX_newnewed
EVP_CipherInitinitialisedinitialisedinitialisedinitialisedinitialisedinitialisedinitialisedinitialised
EVP_DecryptInitinitialised
decryption		initialised
decryption		initialised
decryption		initialised
decryption		initialised
decryption		initialised
decryption		initialised
decryption		initialised
decryption
EVP_EncryptInitinitialised
encryption		initialised
encryption		initialised
encryption		initialised
encryption		initialised
encryption		initialised
encryption		initialised
encryption		initialised
encryption
EVP_CipherUpdateupdatedupdated
EVP_DecryptUpdateupdated
decryption		updated
decryption
EVP_EncryptUpdateupdated
encryption		updated
encryption
EVP_CipherFinalfinaled
EVP_DecryptFinalfinaled
decryption
EVP_EncryptFinalfinaled
decryption
EVP_CIPHER_CTX_freefreedfreedfreedfreedfreedfreedfreedfreedfreed
EVP_CIPHER_CTX_resetnewednewednewednewednewednewednewed
EVP_CIPHER_CTX_get_paramsnewedinitialisedupdatedinitialised
decryption		updated
decryption		initialised
encryption		updated
encryption
EVP_CIPHER_CTX_set_paramsnewedinitialisedupdatedinitialised
decryption		updated
decryption		initialised
encryption		updated
encryption
EVP_CIPHER_CTX_gettable_paramsnewedinitialisedupdatedinitialised
decryption		updated
decryption		initialised
encryption		updated
encryption
EVP_CIPHER_CTX_settable_paramsnewedinitialisedupdatedinitialised
decryption		updated
decryption		initialised
encryption		updated
encryption
+ +=end html + +=head1 NOTES + +At some point the EVP layer will begin enforcing the transitions described +herein. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut