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)> for legacy key types implemented in internal 223OpenSSL providers. 224 225For fully provider-managed key types (see L<provider-keymgmt(7)>), 226possibly implemented in external providers, use functions such as 227L<EVP_PKEY_set1_encoded_public_key(3)> or L<EVP_PKEY_fromdata(3)> 228to populate key data. 229 230Generally caution is advised for using an B<EVP_PKEY> structure across 231different library contexts: In order for an B<EVP_PKEY> to be shared by 232multiple library contexts the providers associated with the library contexts 233must have key managers that support the key type and implement the 234OSSL_FUNC_keymgmt_import() and OSSL_FUNC_keymgmt_export() functions. 235 236=head1 RETURN VALUES 237 238EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 239EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly 240allocated B<EVP_PKEY> structure or NULL if an error occurred. 241 242EVP_PKEY_dup() returns the key duplicate or NULL if an error occurred. 243 244EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and 245EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. 246 247=head1 SEE ALSO 248 249L<EVP_PKEY_set1_RSA(3)>, 250L<EVP_PKEY_set1_DSA(3)>, 251L<EVP_PKEY_set1_DH(3)>, 252L<EVP_PKEY_set1_EC_KEY(3)>, 253L<EVP_PKEY-ED25519(7)>, 254L<EVP_PKEY-ED448(7)>. 255L<EVP_PKEY-HMAC(7)>, 256L<EVP_PKEY-Poly1305(7)>, 257L<EVP_PKEY-Siphash(7)>, 258L<EVP_PKEY-X25519(7)>, 259L<EVP_PKEY-X448(7)>, 260L<EVP_PKEY-ML-DSA(7)>, 261L<EVP_PKEY-ML-KEM(7)>. 262 263=head1 HISTORY 264 265The 266EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. 267 268The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. 269 270The 271EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 272EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and 273EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. 274 275The EVP_PKEY_dup(), EVP_PKEY_new_raw_private_key_ex(), and 276EVP_PKEY_new_raw_public_key_ex() 277functions were added in OpenSSL 3.0. 278 279The EVP_PKEY_new_CMAC_key() was deprecated in OpenSSL 3.0. 280 281The documentation of B<EVP_PKEY> was amended in OpenSSL 3.0 to allow there to 282be the private part of the keypair without the public part, where this was 283previously implied to be disallowed. 284 285Support for B<ML-DSA> and B<ML-KEM> was added in OpenSSL 3.5. 286 287=head1 COPYRIGHT 288 289Copyright 2002-2025 The OpenSSL Project Authors. All Rights Reserved. 290 291Licensed under the Apache License 2.0 (the "License"). You may not use 292this file except in compliance with the License. You can obtain a copy 293in the file LICENSE in the source distribution or at 294L<https://www.openssl.org/source/license.html>. 295 296=cut 297