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