NAME

EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free, EVP_PKEY_new_CMAC_key, EVP_PKEY_new_mac_key — private key allocation functions

SYNOPSIS

#include <openssl/evp.h> EVP_PKEY *
EVP_PKEY_new(void); int
EVP_PKEY_up_ref(EVP_PKEY *key); void
EVP_PKEY_free(EVP_PKEY *key); EVP_PKEY *
EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, size_t len, const EVP_CIPHER *cipher); EVP_PKEY *
EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, int keylen);

DESCRIPTION

The EVP_PKEY structure is used by various OpenSSL functions which require a general private key without reference to any particular algorithm. The EVP_PKEY_new() function allocates an empty EVP_PKEY structure. The reference count is set to 1. To add a private or public key to it, use the functions described in EVP_PKEY_set1_RSA(3). EVP_PKEY_up_ref() increments the reference count of key by 1. EVP_PKEY_free() decrements the reference count of key by 1, and if the reference count reaches zero, frees it up. If key is a NULL pointer, no action occurs. EVP_PKEY_new_CMAC_key() allocates a new EVP_PKEY for the EVP_PKEY_CMAC algorithm type. If e is non-NULL, then the new EVP_PKEY is associated with the engine e. priv points to the raw private key data of length len for this EVP_PKEY. cipher specifies a cipher algorithm to be used during creation of the CMAC. cipher should be a standard encryption only cipher. For example, AEAD and XTS ciphers should not be used. EVP_PKEY_new_mac_key() allocates a new EVP_PKEY. If e is non-NULL, then the new EVP_PKEY structure is associated with the engine e. The type argument indicates what kind of key this is. The value should be a NID for a public key algorithm that supports raw private keys, for example EVP_PKEY_HMAC. key points to the raw private key data for this EVP_PKEY which should be of length keylen. The length should be appropriate for the type of the key. The public key data will be automatically derived from the given private key data (if appropriate for the algorithm type).

RETURN VALUES

EVP_PKEY_new(), EVP_PKEY_new_CMAC_key(), and EVP_PKEY_new_mac_key() return either the newly allocated EVP_PKEY structure or NULL if an error occurred. EVP_PKEY_up_ref() returns 1 for success or 0 for failure.

SEE ALSO

CMAC_Init(3), d2i_PrivateKey(3), evp(3), EVP_PKCS82PKEY(3), EVP_PKEY_add1_attr(3), EVP_PKEY_asn1_new(3), EVP_PKEY_check(3), EVP_PKEY_cmp(3), EVP_PKEY_CTX_new(3), EVP_PKEY_get_default_digest_nid(3), EVP_PKEY_meth_new(3), EVP_PKEY_print_private(3), EVP_PKEY_set1_RSA(3), EVP_PKEY_size(3), X509_get_pubkey_parameters(3)

HISTORY

EVP_PKEY_new() and EVP_PKEY_free() first appeared in SSLeay 0.6.0 and have been available since OpenBSD 2.4. EVP_PKEY_new_CMAC_key() first appeared in OpenSSL 1.1.1 and has been available since OpenBSD 6.9. EVP_PKEY_new_mac_key() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9. EVP_PKEY_up_ref() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3.