=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 Call | Current State | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
start | newed | digest sign |
verify | verify recover |
encrypt | decrypt | derive | encapsulate | decapsulate | parameter generation |
key generation |
freed | |
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 sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest sign |
digest 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 recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify recover |
verify 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 generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
parameter generation |
||
EVP_PKEY_paramgen | parameter generation |
||||||||||||
EVP_PKEY_keygen_init | key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
key generation |
||
EVP_PKEY_keygen | key generation |
||||||||||||
EVP_PKEY_gen | parameter generation |
key generation |
|||||||||||
EVP_PKEY_CTX_get_params | newed | digest sign |
verify | verify recover |
encrypt | decrypt | derive | encapsulate | decapsulate | parameter generation |
key generation |
||
EVP_PKEY_CTX_set_params | newed | digest sign |
verify | verify recover |
encrypt | decrypt | derive | encapsulate | decapsulate | parameter generation |
key generation |
||
EVP_PKEY_CTX_gettable_params | newed | digest sign |
verify | verify recover |
encrypt | decrypt | derive | encapsulate | decapsulate | parameter generation |
key generation |
||
EVP_PKEY_CTX_settable_params | newed | digest sign |
verify | verify recover |
encrypt | decrypt | derive | encapsulate | decapsulate | parameter generation |
key generation |
||
EVP_PKEY_CTX_free | freed | freed | freed | freed | freed | freed | freed | freed | freed | freed | freed | freed |