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. 70 71EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key(). 72New applications should use EVP_PKEY_new_raw_private_key() instead. 73 74EVP_PKEY_get_raw_private_key() fills the buffer provided by B<priv> with raw 75private key data. The size of the B<priv> buffer should be in B<*len> on entry 76to the function, and on exit B<*len> is updated with the number of bytes 77actually written. If the buffer B<priv> is NULL then B<*len> is populated with 78the number of bytes required to hold the key. The calling application is 79responsible for ensuring that the buffer is large enough to receive the private 80key data. This function only works for algorithms that support raw private keys. 81Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, 82B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>. 83 84EVP_PKEY_get_raw_public_key() fills the buffer provided by B<pub> with raw 85public key data. The size of the B<pub> buffer should be in B<*len> on entry 86to the function, and on exit B<*len> is updated with the number of bytes 87actually written. If the buffer B<pub> is NULL then B<*len> is populated with 88the number of bytes required to hold the key. The calling application is 89responsible for ensuring that the buffer is large enough to receive the public 90key data. This function only works for algorithms that support raw public keys. 91Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or 92B<EVP_PKEY_ED448>. 93 94=head1 NOTES 95 96The B<EVP_PKEY> structure is used by various OpenSSL functions which require a 97general private key without reference to any particular algorithm. 98 99The structure returned by EVP_PKEY_new() is empty. To add a private or public 100key to this empty structure use the appropriate functions described in 101L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or 102L<EVP_PKEY_set1_EC_KEY>. 103 104=head1 RETURN VALUES 105 106EVP_PKEY_new(), EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 107EVP_PKEY_new_CMAC_key() and EVP_PKEY_new_mac_key() return either the newly 108allocated B<EVP_PKEY> structure or B<NULL> if an error occurred. 109 110EVP_PKEY_up_ref(), EVP_PKEY_get_raw_private_key() and 111EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. 112 113=head1 SEE ALSO 114 115L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA>, L<EVP_PKEY_set1_DH> or 116L<EVP_PKEY_set1_EC_KEY> 117 118=head1 HISTORY 119 120The 121EVP_PKEY_new() and EVP_PKEY_free() functions exist in all versions of OpenSSL. 122 123The EVP_PKEY_up_ref() function was added in OpenSSL 1.1.0. 124 125The 126EVP_PKEY_new_raw_private_key(), EVP_PKEY_new_raw_public_key(), 127EVP_PKEY_new_CMAC_key(), EVP_PKEY_new_raw_private_key() and 128EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. 129 130=head1 COPYRIGHT 131 132Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 133 134Licensed under the OpenSSL license (the "License"). You may not use 135this file except in compliance with the License. You can obtain a copy 136in the file LICENSE in the source distribution or at 137L<https://www.openssl.org/source/license.html>. 138 139=cut 140