1=pod 2 3=head1 NAME 4 5EVP_PKEY, 6EVP_PKEY_new, 7EVP_PKEY_up_ref, 8EVP_PKEY_dup, 9EVP_PKEY_free, 10EVP_PKEY_new_raw_private_key_ex, 11EVP_PKEY_new_raw_private_key, 12EVP_PKEY_new_raw_public_key_ex, 13EVP_PKEY_new_raw_public_key, 14EVP_PKEY_new_CMAC_key, 15EVP_PKEY_new_mac_key, 16EVP_PKEY_get_raw_private_key, 17EVP_PKEY_get_raw_public_key 18- public/private key allocation and raw key handling functions 19 20=head1 SYNOPSIS 21 22 #include <openssl/evp.h> 23 24 typedef evp_pkey_st EVP_PKEY; 25 26 EVP_PKEY *EVP_PKEY_new(void); 27 int EVP_PKEY_up_ref(EVP_PKEY *key); 28 EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key); 29 void EVP_PKEY_free(EVP_PKEY *key); 30 31 EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx, 32 const char *keytype, 33 const char *propq, 34 const unsigned char *key, 35 size_t keylen); 36 EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, 37 const unsigned char *key, size_t keylen); 38 EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx, 39 const char *keytype, 40 const char *propq, 41 const unsigned char *key, 42 size_t keylen); 43 EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, 44 const unsigned char *key, size_t keylen); 45 EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, 46 int keylen); 47 48 int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, 49 size_t *len); 50 int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, 51 size_t *len); 52 53The following function has been deprecated since OpenSSL 3.0, and can be 54hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 55see L<openssl_user_macros(7)>: 56 57 EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, 58 size_t len, const EVP_CIPHER *cipher); 59 60=head1 DESCRIPTION 61 62B<EVP_PKEY> is a generic structure to hold diverse types of asymmetric keys 63(also known as "key pairs"), and can be used for diverse operations, like 64signing, verifying signatures, key derivation, etc. The asymmetric keys 65themselves are often referred to as the "internal key", and are handled by 66backends, such as providers (through L<EVP_KEYMGMT(3)>) or B<ENGINE>s. 67 68Conceptually, an B<EVP_PKEY> internal key may hold a private key, a public 69key, or both (a keypair), and along with those, key parameters if the key type 70requires them. The presence of these components determine what operations can 71be made; for example, signing normally requires the presence of a private key, 72and verifying normally requires the presence of a public key. 73 74=for comment ED signature require both the private and public key... 75 76B<EVP_PKEY> has also been used for MAC algorithm that were conceived as 77producing signatures, although not being public key algorithms; "POLY1305", 78"SIPHASH", "HMAC", "CMAC". This usage is considered legacy and is discouraged 79in favor of the L<EVP_MAC(3)> API. 80 81The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is 82used by OpenSSL to store public and private keys. The reference count is set to 83B<1>. 84 85EVP_PKEY_up_ref() increments the reference count of I<key>. 86 87EVP_PKEY_dup() duplicates the I<key>. The I<key> must not be ENGINE based or 88a raw key, otherwise the duplication will fail. 89 90EVP_PKEY_free() decrements the reference count of I<key> and, if the reference 91count is zero, frees it up. If I<key> is NULL, nothing is done. 92 93EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless an 94engine should be used for the key type, a provider for the key is found using 95the library context I<libctx> and the property query string I<propq>. The 96I<keytype> argument indicates what kind of key this is. The value should be a 97string for a public key algorithm that supports raw private keys, i.e one of 98"X25519", "ED25519", "X448" or "ED448". I<key> points to the raw private key 99data for this B<EVP_PKEY> which should be of length I<keylen>. The length 100should be appropriate for the type of the key. The public key data will be 101automatically derived from the given private key data (if appropriate for the 102algorithm type). 103 104EVP_PKEY_new_raw_private_key() does the same as 105EVP_PKEY_new_raw_private_key_ex() except that the default library context and 106default property query are used instead. If I<e> is non-NULL then the new 107B<EVP_PKEY> structure is associated with the engine I<e>. The I<type> argument 108indicates what kind of key this is. The value should be a NID for a public key 109algorithm that supports raw private keys, i.e. one of B<EVP_PKEY_X25519>, 110B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 111 112EVP_PKEY_new_raw_private_key_ex() and EVP_PKEY_new_raw_private_key() may also 113be used with most MACs implemented as public key algorithms, so key types such 114as "HMAC", "POLY1305", "SIPHASH", or their NID form B<EVP_PKEY_POLY1305>, 115B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_HMAC> are also accepted. This usage is, 116as mentioned above, discouraged in favor of the L<EVP_MAC(3)> API. 117 118EVP_PKEY_new_raw_public_key_ex() works in the same way as 119EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw 120public key data. The B<EVP_PKEY> structure will be initialised without any 121private key information. Algorithm types that support raw public keys are 122"X25519", "ED25519", "X448" or "ED448". 123 124EVP_PKEY_new_raw_public_key() works in the same way as 125EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key 126data. The B<EVP_PKEY> structure will be initialised without any private key 127information. Algorithm types that support raw public keys are 128B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 129 130EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). 131New applications should use EVP_PKEY_new_raw_private_key() instead. 132 133EVP_PKEY_get_raw_private_key() fills the buffer provided by I<priv> with raw 134private key data. The size of the I<priv> buffer should be in I<*len> on entry 135to the function, and on exit I<*len> is updated with the number of bytes 136actually written. If the buffer I<priv> is NULL then I<*len> is populated with 137the number of bytes required to hold the key. The calling application is 138responsible for ensuring that the buffer is large enough to receive the private 139key data. This function only works for algorithms that support raw private keys. 140Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, 141B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 142 143EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw 144public key data. The size of the I<pub> buffer should be in I<*len> on entry 145to the function, and on exit I<*len> is updated with the number of bytes 146actually written. If the buffer I<pub> is NULL then I<*len> is populated with 147the number of bytes required to hold the key. The calling application is 148responsible for ensuring that the buffer is large enough to receive the public 149key data. This function only works for algorithms that support raw public keys. 150Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or 151B<EVP_PKEY_ED448>. 152 153EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() 154except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the 155raw private key data, it also takes a cipher algorithm to be used during 156creation of a CMAC in the B<cipher> argument. The cipher should be a standard 157encryption-only cipher. For example AEAD and XTS ciphers should not be used. 158 159Applications should use the L<EVP_MAC(3)> API instead 160and set the B<OSSL_MAC_PARAM_CIPHER> parameter on the B<EVP_MAC_CTX> object 161with the name of the cipher being used. 162 163=head1 NOTES 164 165The B<EVP_PKEY> structure is used by various OpenSSL functions which require a 166general private key without reference to any particular algorithm. 167 168The structure returned by EVP_PKEY_new() is empty. To add a private or public 169key to this empty structure use the appropriate functions described in 170L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or 171L<EVP_PKEY_set1_EC_KEY(3)>. 172 173=head1 RETURN VALUES 174 175EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 176EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly 177allocated B<EVP_PKEY> structure or NULL if an error occurred. 178 179EVP_PKEY_dup() returns the key duplicate or NULL if an error occurred. 180 181EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and 182EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. 183 184=head1 SEE ALSO 185 186L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or 187L<EVP_PKEY_set1_EC_KEY(3)> 188 189=head1 HISTORY 190 191The 192EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. 193 194The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. 195 196The 197EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 198EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and 199EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. 200 201The EVP_PKEY_dup(), EVP_PKEY_new_raw_private_key_ex(), and 202EVP_PKEY_new_raw_public_key_ex() 203functions were added in OpenSSL 3.0. 204 205The EVP_PKEY_new_CMAC_key() was deprecated in OpenSSL 3.0. 206 207The documentation of B<EVP_PKEY> was amended in OpenSSL 3.0 to allow there to 208be the private part of the keypair without the public part, where this was 209previously implied to be disallowed. 210 211=head1 COPYRIGHT 212 213Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. 214 215Licensed under the Apache License 2.0 (the "License"). You may not use 216this file except in compliance with the License. You can obtain a copy 217in the file LICENSE in the source distribution or at 218L<https://www.openssl.org/source/license.html>. 219 220=cut 221