From: Pauli Date: Mon, 7 Jun 2021 09:05:54 +0000 (+1000) Subject: doc: add PKEY life cycle documentation X-Git-Tag: openssl-3.0.0-beta1~151 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=95c8a5125207a62362345d85be77531ad9654edd;p=thirdparty%2Fopenssl.git doc: add PKEY life cycle documentation Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/15637) --- diff --git a/doc/man7/img/pkey.png b/doc/man7/img/pkey.png new file mode 100644 index 00000000000..d31b5d3841a Binary files /dev/null and b/doc/man7/img/pkey.png differ diff --git a/doc/man7/life_cycle-pkey.pod b/doc/man7/life_cycle-pkey.pod new file mode 100644 index 00000000000..6768750f481 --- /dev/null +++ b/doc/man7/life_cycle-pkey.pod @@ -0,0 +1,713 @@ +=pod + +=head1 NAME + +life_cycle-pkey - The PKEY algorithm life-cycle + +=head1 DESCRIPTION + +All public keys (PKEYs) go through a number of stages in their life-cycle: + +=over 4 + +=item start + +This state represents the PKEY before it has been allocated. It is the +starting state for any life-cycle transitions. + +=item newed + +This state represents the PKEY after it has been allocated. + +=item decapsulate + +This state represents the PKEY when it is ready to perform a private key decapsulation +opeartion. + +=item decrypt + +This state represents the PKEY when it is ready to decrypt some ciphertext. + +=item derive + +This state represents the PKEY when it is ready to derive a shared secret. + +=item digest sign + +This state represents the PKEY when it is ready to perform a private key signature +operation. + +=item encapsulate + +This state represents the PKEY when it is ready to perform a public key encapsulation +opeartion. + +=item encrypt + +This state represents the PKEY when it is ready to encrypt some plaintext. + +=item key generation + +This state represents the PKEY when it is ready to generate a new public/private key. + +=item parameter generation + +This state represents the PKEY when it is ready to generate key parameters. + +=item verify + +This state represents the PKEY when it is ready to verify a public key signature. + +=item verify recover + +This state represents the PKEY when it is ready to recover a public key signature data. + +=item freed + +This state is entered when the PKEY is freed. It is the terminal state +for all life-cycle transitions. + +=back + +=head2 State Transition Diagram + +The usual life-cycle of a PKEY object is illustrated: + +=begin man + + +-------------+ + | | + | start | + | | + EVP_PKEY_derive +-------------+ + +-------------+ EVP_PKEY_derive_set_peer | +-------------+ + | |----------------------------+ | +----------------------------| | + | derive | | | | EVP_PKEY_verify | verify | + | |<---------------------------+ | +--------------------------->| | + +-------------+ | +-------------+ + ^ | ^ + | EVP_PKEY_derive_init | EVP_PKEY_verify_init | + +---------------------------------------+ | +---------------------------------------+ + | | | + +-------------+ | | | +-------------+ + | |----------------------------+ | | | +----------------------------| | + | digest sign | EVP_PKEY_sign | | | | | EVP_PKEY_verify_recover | verify | + | |<---------------------------+ | | | +--------------------------->| recover | + +-------------+ | | | +-------------+ + ^ | | | ^ + | EVP_PKEY_sign_init | | | EVP_PKEY_verify_recover_init | + +---------------------------------+ | | | +---------------------------------+ + | | | | | + +-------------+ | | | | | +-------------+ + | |----------------------------+ | | | | | +----------------------------| | + | decapsulate | EVP_PKEY_decapsulate | | | | | | | EVP_PKEY_decrypt | decrypt | + | |<---------------------------+ | | v | | +--------------------------->| | + +-------------+ | +-------------+ | +-------------+ + ^ +---| |---+ ^ + | EVP_PKEY_decapsulate_init | | EVP_PKEY_decrypt_init | + +-------------------------------------| newed |-------------------------------------+ + | | + +---| |---+ + +-------------+ | +-------------+ | +-------------+ + | |----------------------------+ | | | | +----------------------------| | + | encapsulate | EVP_PKEY_encapsulate | | | | | | EVP_PKEY_encrypt | encrypt | + | |<---------------------------+ | | | | +--------------------------->| | + +-------------+ | | | | +-------------+ + ^ | | | | ^ + | EVP_PKEY_encapsulate_init | | | | EVP_PKEY_encrypt_init | + +---------------------------------+ | | +---------------------------------+ + | | + +---------------------------------------+ +---------------------------------------+ + | EVP_PKEY_paramgen_init EVP_PKEY_keygen_init | + v v + +-------------+ +-------------+ + | |----------------------------+ +----------------------------| | + | parameter | | | | key | + | generation |<---------------------------+ +--------------------------->| generation | + +-------------+ EVP_PKEY_paramgen EVP_PKEY_keygen +-------------+ + EVP_PKEY_gen EVP_PKEY_gen + + + + - - - - - + +-----------+ + ' ' EVP_PKEY_CTX_free | | + ' any state '------------------->| 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 digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key freed + sign recover generation generation + EVP_PKEY_CTX_new newed + EVP_PKEY_CTX_new_id newed + EVP_PKEY_CTX_new_from_name newed + EVP_PKEY_CTX_new_from_pkey newed + EVP_PKEY_sign_init digest digest digest digest digest digest digest digest digest digest digest + sign sign sign sign sign sign sign sign sign sign sign + EVP_PKEY_sign digest + sign + EVP_PKEY_verify_init verify verify verify verify verify verify verify verify verify verify verify + EVP_PKEY_verify verify + EVP_PKEY_verify_recover_init verify verify verify verify verify verify verify verify verify verify verify + recover recover recover recover recover recover recover recover recover recover recover + EVP_PKEY_verify_recover verify + recover + EVP_PKEY_encrypt_init encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt + EVP_PKEY_encrypt encrypt + EVP_PKEY_decrypt_init decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt + EVP_PKEY_decrypt decrypt + EVP_PKEY_derive_init derive derive derive derive derive derive derive derive derive derive derive + EVP_PKEY_derive_set_peer derive + EVP_PKEY_derive derive + EVP_PKEY_encapsulate_init encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate + EVP_PKEY_encapsulate encapsulate + EVP_PKEY_decapsulate_init decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate + EVP_PKEY_decapsulate decapsulate + EVP_PKEY_paramgen_init parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_paramgen parameter + generation + EVP_PKEY_keygen_init key key key key key key key key key key key + generation generation generation generation generation generation generation generation generation generation generation + EVP_PKEY_keygen key + generation + EVP_PKEY_gen parameter key + generation generation + EVP_PKEY_CTX_get_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_set_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_gettable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_settable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key + sign recover generation generation + EVP_PKEY_CTX_free freed freed freed freed freed freed freed freed freed freed freed freed + +=end man + +=begin html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function CallCurrent State
startneweddigest
sign		verifyverify
recover		encryptdecryptderiveencapsulatedecapsulateparameter
generation		key
generation		freed
EVP_PKEY_CTX_newnewed
EVP_PKEY_CTX_new_idnewed
EVP_PKEY_CTX_new_from_namenewed
EVP_PKEY_CTX_new_from_pkeynewed
EVP_PKEY_sign_initdigest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign		digest
sign
EVP_PKEY_signdigest
sign
EVP_PKEY_verify_initverifyverifyverifyverifyverifyverifyverifyverifyverifyverifyverify
EVP_PKEY_verifyverify
EVP_PKEY_verify_recover_initverify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover		verify
recover
EVP_PKEY_verify_recoververify
recover
EVP_PKEY_encrypt_initencryptencryptencryptencryptencryptencryptencryptencryptencryptencryptencrypt
EVP_PKEY_encryptencrypt
EVP_PKEY_decrypt_initdecryptdecryptdecryptdecryptdecryptdecryptdecryptdecryptdecryptdecryptdecrypt
EVP_PKEY_decryptdecrypt
EVP_PKEY_derive_initderivederivederivederivederivederivederivederivederivederivederive
EVP_PKEY_derive_set_peerderive
EVP_PKEY_derivederive
EVP_PKEY_encapsulate_initencapsulateencapsulateencapsulateencapsulateencapsulateencapsulateencapsulateencapsulateencapsulateencapsulateencapsulate
EVP_PKEY_encapsulateencapsulate
EVP_PKEY_decapsulate_initdecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulatedecapsulate
EVP_PKEY_decapsulatedecapsulate
EVP_PKEY_paramgen_initparameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation		parameter
generation
EVP_PKEY_paramgenparameter
generation
EVP_PKEY_keygen_initkey
generation		key
generation		key
generation		key
generation		key
generation		key
generation		key
generation		key
generation		key
generation		key
generation		key
generation
EVP_PKEY_keygenkey
generation
EVP_PKEY_genparameter
generation		key
generation
EVP_PKEY_CTX_get_paramsneweddigest
sign		verifyverify
recover		encryptdecryptderiveencapsulatedecapsulateparameter
generation		key
generation
EVP_PKEY_CTX_set_paramsneweddigest
sign		verifyverify
recover		encryptdecryptderiveencapsulatedecapsulateparameter
generation		key
generation
EVP_PKEY_CTX_gettable_paramsneweddigest
sign		verifyverify
recover		encryptdecryptderiveencapsulatedecapsulateparameter
generation		key
generation
EVP_PKEY_CTX_settable_paramsneweddigest
sign		verifyverify
recover		encryptdecryptderiveencapsulatedecapsulateparameter
generation		key
generation
EVP_PKEY_CTX_freefreedfreedfreedfreedfreedfreedfreedfreedfreedfreedfreedfreed
+ +=end html + +=head1 NOTES + +At some point the EVP layer will begin enforcing the transitions described +herein. + +=head1 SEE ALSO + +L, +L, L, L, +L, L, L, +L, L, L + +=head1 HISTORY + +The provider PKEY interface was introduced in OpenSSL 3.0. + +=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