1=pod 2 3=head1 NAME 4 5EVP_PKEY_new, 6EVP_PKEY_up_ref, 7EVP_PKEY_free, 8EVP_PKEY_new_raw_private_key, 9EVP_PKEY_new_raw_public_key, 10EVP_PKEY_new_CMAC_key, 11EVP_PKEY_new_mac_key, 12EVP_PKEY_get_raw_private_key, 13EVP_PKEY_get_raw_public_key 14- public/private key allocation and raw key handling functions 15 16=head1 SYNOPSIS 17 18 #include <openssl/evp.h> 19 20 EVP_PKEY *EVP_PKEY_new(void); 21 int EVP_PKEY_up_ref(EVP_PKEY *key); 22 void EVP_PKEY_free(EVP_PKEY *key); 23 24 EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, 25 const unsigned char *key, size_t keylen); 26 EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, 27 const unsigned char *key, size_t keylen); 28 EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, 29 size_t len, const EVP_CIPHER *cipher); 30 EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, 31 int keylen); 32 33 int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, 34 size_t *len); 35 int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, 36 size_t *len); 37 38=head1 DESCRIPTION 39 40The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is 41used by OpenSSL to store public and private keys. The reference count is set to 42B<1>. 43 44EVP_PKEY_up_ref() increments the reference count of B<key>. 45 46EVP_PKEY_free() decrements the reference count of B<key> and, if the reference 47count is zero, frees it up. If B<key> is NULL, nothing is done. 48 49EVP_PKEY_new_raw_private_key() allocates a new B<EVP_PKEY>. If B<e> is non-NULL 50then the new B<EVP_PKEY> structure is associated with the engine B<e>. The 51B<type> argument indicates what kind of key this is. The value should be a NID 52for a public key algorithm that supports raw private keys, i.e. one of 53B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>, 54B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. B<key> points to the 55raw private key data for this B<EVP_PKEY> which should be of length B<keylen>. 56The length should be appropriate for the type of the key. The public key data 57will be automatically derived from the given private key data (if appropriate 58for the algorithm type). 59 60EVP_PKEY_new_raw_public_key() works in the same way as 61EVP_PKEY_new_raw_private_key() except that B<key> points to the raw public key 62data. The B<EVP_PKEY> structure will be initialised without any private key 63information. Algorithm types that support raw public keys are 64B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 65 66EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key() 67except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the 68raw private key data, it also takes a cipher algorithm to be used during 69creation of a CMAC in the B<cipher> argument. The cipher should be a standard 70encryption only cipher. For example AEAD and XTS ciphers should not be used. 71 72EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). 73New applications should use EVP_PKEY_new_raw_private_key() instead. 74 75EVP_PKEY_get_raw_private_key() fills the buffer provided by B<priv> with raw 76private key data. The size of the B<priv> buffer should be in B<*len> on entry 77to the function, and on exit B<*len> is updated with the number of bytes 78actually written. If the buffer B<priv> is NULL then B<*len> is populated with 79the number of bytes required to hold the key. The calling application is 80responsible for ensuring that the buffer is large enough to receive the private 81key data. This function only works for algorithms that support raw private keys. 82Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, 83B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 84 85EVP_PKEY_get_raw_public_key() fills the buffer provided by B<pub> with raw 86public key data. The size of the B<pub> buffer should be in B<*len> on entry 87to the function, and on exit B<*len> is updated with the number of bytes 88actually written. If the buffer B<pub> is NULL then B<*len> is populated with 89the number of bytes required to hold the key. The calling application is 90responsible for ensuring that the buffer is large enough to receive the public 91key data. This function only works for algorithms that support raw public keys. 92Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or 93B<EVP_PKEY_ED448>. 94 95=head1 NOTES 96 97The B<EVP_PKEY> structure is used by various OpenSSL functions which require a 98general private key without reference to any particular algorithm. 99 100The structure returned by EVP_PKEY_new() is empty. To add a private or public 101key to this empty structure use the appropriate functions described in 102L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or 103L<EVP_PKEY_set1_EC_KEY>. 104 105=head1 RETURN VALUES 106 107EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 108EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly 109allocated B<EVP_PKEY> structure or B<NULL> if an error occurred. 110 111EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and 112EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. 113 114=head1 SEE ALSO 115 116L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or 117L<EVP_PKEY_set1_EC_KEY> 118 119=head1 HISTORY 120 121The 122EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. 123 124The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. 125 126The 127EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 128EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and 129EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. 130 131=head1 COPYRIGHT 132 133Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 134 135Licensed under the OpenSSL license (the "License"). You may not use 136this file except in compliance with the License. You can obtain a copy 137in the file LICENSE in the source distribution or at 138L<https://www.openssl.org/source/license.html>. 139 140=cut 141