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, e.g., one of: 98C<ED25519>, 99C<ED448>, 100C<X25519>, 101C<X448>, 102C<ML-DSA-44>, 103C<ML-DSA-65>, 104C<ML-DSA-87>, 105C<ML-KEM-512>, 106C<ML-KEM-768>, 107or 108C<ML-KEM-1024>. 109I<key> points to the raw private key 110data for this B<EVP_PKEY> which should be of length I<keylen>. The length 111should be appropriate for the type of the key. The public key data will be 112automatically derived from the given private key data (if appropriate for the 113algorithm type). 114 115EVP_PKEY_new_raw_private_key() does the same as 116EVP_PKEY_new_raw_private_key_ex() except that the default library context and 117default property query are used instead. If I<e> is non-NULL then the new 118B<EVP_PKEY> structure is associated with the engine I<e>. The I<type> argument 119indicates what kind of key this is. The value should be a NID for a public key 120algorithm that supports raw private keys, i.e. one of B<EVP_PKEY_X25519>, 121B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 122 123EVP_PKEY_new_raw_private_key_ex() and EVP_PKEY_new_raw_private_key() may also 124be used with most MACs implemented as public key algorithms, so key types such 125as "HMAC", "POLY1305", "SIPHASH", or their NID form B<EVP_PKEY_POLY1305>, 126B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_HMAC> are also accepted. This usage is, 127as mentioned above, discouraged in favor of the L<EVP_MAC(3)> API. 128 129EVP_PKEY_new_raw_public_key_ex() works in the same way as 130EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw 131public key data. The B<EVP_PKEY> structure will be initialised without any 132private key information. Algorithm types that support raw public keys are 133B<ED25519>, 134B<ED448>, 135B<X25519>, 136B<X448>, 137C<ML-DSA-44>, 138C<ML-DSA-65>, 139C<ML-DSA-87>, 140B<ML-KEM-512>, 141B<ML-KEM-768>, 142and 143B<ML-KEM-1024>. 144 145EVP_PKEY_new_raw_public_key() works in the same way as 146EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw public 147key data. 148The B<EVP_PKEY> structure will be initialised without any private key 149information. 150 151EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). 152New applications should use EVP_PKEY_new_raw_private_key() instead. 153 154EVP_PKEY_get_raw_private_key() fills the buffer provided by I<priv> with raw 155private key data. The size of the I<priv> buffer should be in I<*len> on entry 156to the function, and on exit I<*len> is updated with the number of bytes 157actually written. If the buffer I<priv> is NULL then I<*len> is populated with 158the number of bytes required to hold the key. The calling application is 159responsible for ensuring that the buffer is large enough to receive the private 160key data. This function only works for algorithms that support raw private keys. 161These include: 162B<ED25519>, 163B<ED448>, 164B<X25519>, 165B<X448>, 166B<HMAC>, 167B<POLY1305>, 168and 169B<SIPHASH>. 170EVP_PKEY_get_raw_private_key() also works with 171C<ML-DSA-44>, 172C<ML-DSA-65>, 173C<ML-DSA-87>, 174B<ML-KEM-512>, 175B<ML-KEM-768> and 176B<ML-KEM-1024> 177keys, which don't have legacy numeric I<NID> assignments, but their raw form is 178nevertheless available. 179 180 181EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw 182public key data. The size of the I<pub> buffer should be in I<*len> on entry 183to the function, and on exit I<*len> is updated with the number of bytes 184actually written. If the buffer I<pub> is NULL then I<*len> is populated with 185the number of bytes required to hold the key. The calling application is 186responsible for ensuring that the buffer is large enough to receive the public 187key data. This function only works for algorithms that support raw public keys. 188These include: 189B<ED25519>, 190B<ED448>, 191B<X25519>, 192and 193B<X448> 194EVP_PKEY_get_raw_public_key() also works with 195C<ML-DSA-44>, 196C<ML-DSA-65>, 197C<ML-DSA-87>, 198B<ML-KEM-512>, 199B<ML-KEM-768> and 200B<ML-KEM-1024> 201keys, which don't have legacy numeric I<NID> assignments, but their raw form is 202nevertheless available. 203 204EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() 205except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the 206raw private key data, it also takes a cipher algorithm to be used during 207creation of a CMAC in the B<cipher> argument. The cipher should be a standard 208encryption-only cipher. For example AEAD and XTS ciphers should not be used. 209 210Applications should use the L<EVP_MAC(3)> API instead 211and set the B<OSSL_MAC_PARAM_CIPHER> parameter on the B<EVP_MAC_CTX> object 212with the name of the cipher being used. 213 214=head1 NOTES 215 216The B<EVP_PKEY> structure is used by various OpenSSL functions which require a 217general private key without reference to any particular algorithm. 218 219The structure returned by EVP_PKEY_new() is empty. To add a private or public 220key to this empty structure use the appropriate functions described in 221L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or 222L<EVP_PKEY_set1_EC_KEY(3)>. 223 224=head1 RETURN VALUES 225 226EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 227EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly 228allocated B<EVP_PKEY> structure or NULL if an error occurred. 229 230EVP_PKEY_dup() returns the key duplicate or NULL if an error occurred. 231 232EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and 233EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. 234 235=head1 SEE ALSO 236 237L<EVP_PKEY_set1_RSA(3)>, 238L<EVP_PKEY_set1_DSA(3)>, 239L<EVP_PKEY_set1_DH(3)>, 240L<EVP_PKEY_set1_EC_KEY(3)>, 241L<EVP_PKEY-ED25519(7)>, 242L<EVP_PKEY-ED448(7)>. 243L<EVP_PKEY-HMAC(7)>, 244L<EVP_PKEY-Poly1305(7)>, 245L<EVP_PKEY-Siphash(7)>, 246L<EVP_PKEY-X25519(7)>, 247L<EVP_PKEY-X448(7)>, 248L<EVP_PKEY-ML-DSA(7)>, 249L<EVP_PKEY-ML-KEM(7)>. 250 251=head1 HISTORY 252 253The 254EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. 255 256The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. 257 258The 259EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 260EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and 261EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. 262 263The EVP_PKEY_dup(), EVP_PKEY_new_raw_private_key_ex(), and 264EVP_PKEY_new_raw_public_key_ex() 265functions were added in OpenSSL 3.0. 266 267The EVP_PKEY_new_CMAC_key() was deprecated in OpenSSL 3.0. 268 269The documentation of B<EVP_PKEY> was amended in OpenSSL 3.0 to allow there to 270be the private part of the keypair without the public part, where this was 271previously implied to be disallowed. 272 273Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5. 274 275=head1 COPYRIGHT 276 277Copyright 2002-2025 The OpenSSL Project Authors. All Rights Reserved. 278 279Licensed under the Apache License 2.0 (the "License"). You may not use 280this file except in compliance with the License. You can obtain a copy 281in the file LICENSE in the source distribution or at 282L<https://www.openssl.org/source/license.html>. 283 284=cut 285