Skip to content

life_cycle-pkey

NAME

life_cycle-pkey - The PKEY algorithm life-cycle

DESCRIPTION

All public keys (PKEYs) go through a number of stages in their life-cycle:

  • start

    This state represents the PKEY before it has been allocated. It is the starting state for any life-cycle transitions.

  • newed

    This state represents the PKEY after it has been allocated.

  • decapsulate

    This state represents the PKEY when it is ready to perform a private key decapsulation operation.

  • decrypt

    This state represents the PKEY when it is ready to decrypt some ciphertext.

  • derive

    This state represents the PKEY when it is ready to derive a shared secret.

  • digest sign

    This state represents the PKEY when it is ready to perform a private key signature operation.

  • encapsulate

    This state represents the PKEY when it is ready to perform a public key encapsulation operation.

  • encrypt

    This state represents the PKEY when it is ready to encrypt some plaintext.

  • key generation

    This state represents the PKEY when it is ready to generate a new public/private key.

  • parameter generation

    This state represents the PKEY when it is ready to generate key parameters.

  • verify

    This state represents the PKEY when it is ready to verify a public key signature.

  • verify recover

    This state represents the PKEY when it is ready to recover a public key signature data.

  • freed

    This state is entered when the PKEY is freed. It is the terminal state for all life-cycle transitions.

State Transition Diagram

The usual life-cycle of a PKEY object is illustrated:

Formal State Transitions

This section defines all of the legal state transitions. This is the canonical list.

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

NOTES

At some point the EVP layer will begin enforcing the transitions described herein.

SEE ALSO

EVP_PKEY_new(3), EVP_PKEY_decapsulate(3), EVP_PKEY_decrypt(3), EVP_PKEY_encapsulate(3), EVP_PKEY_encrypt(3), EVP_PKEY_derive(3), EVP_PKEY_keygen(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3)

HISTORY

The provider PKEY interface was introduced in OpenSSL 3.0.

Copyright 2021-2023 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 https://www.openssl.org/source/license.html.