1=pod 2 3=head1 NAME 4 5EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, 6EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, 7EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, 8EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, 9EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, 10EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, 11EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id, 12EVP_PKEY_set1_engine, EVP_PKEY_get0_engine, 13EVP_PKEY_id, EVP_PKEY_base_id - 14EVP_PKEY assignment functions 15 16=head1 SYNOPSIS 17 18 #include <openssl/evp.h> 19 20 int EVP_PKEY_get_id(const EVP_PKEY *pkey); 21 int EVP_PKEY_get_base_id(const EVP_PKEY *pkey); 22 int EVP_PKEY_type(int type); 23 24 #define EVP_PKEY_id EVP_PKEY_get_id 25 #define EVP_PKEY_base_id EVP_PKEY_get_base_id 26 27The following functions have been deprecated since OpenSSL 3.0, and can be 28hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 29see L<openssl_user_macros(7)>: 30 31 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); 32 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); 33 int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key); 34 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); 35 36 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); 37 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); 38 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); 39 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); 40 41 const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); 42 const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len); 43 const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len); 44 const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey); 45 const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey); 46 const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey); 47 const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey); 48 void *EVP_PKEY_get0(const EVP_PKEY *pkey); 49 50 int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); 51 int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); 52 int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); 53 int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); 54 int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); 55 int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); 56 57 ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey); 58 int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine); 59 60=head1 DESCRIPTION 61 62EVP_PKEY_get_base_id() returns the type of I<pkey>. For example 63an RSA key will return B<EVP_PKEY_RSA>. 64 65EVP_PKEY_get_id() returns the actual NID associated with I<pkey> 66only if the I<pkey> type isn't implemented just in a L<provider(7)>. 67Historically keys using the same algorithm could use different NIDs. 68For example an RSA key could use the NIDs corresponding to 69the NIDs B<NID_rsaEncryption> (equivalent to B<EVP_PKEY_RSA>) or 70B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of 71alternative non-standard NIDs is now rare so B<EVP_PKEY_RSA2> et al are not 72often seen in practice. 73EVP_PKEY_get_id() returns -1 (B<EVP_PKEY_KEYMGMT>) if the I<pkey> is 74only implemented in a L<provider(7)>. 75 76EVP_PKEY_type() returns the underlying type of the NID I<type>. For example 77EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>. 78 79EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and 80EVP_PKEY_set1_EC_KEY() set the key referenced by I<pkey> to I<key>. These 81functions are deprecated. Applications should instead use 82L<EVP_PKEY_fromdata(3)>. 83 84EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), 85EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and 86EVP_PKEY_assign_SIPHASH() set the referenced key to I<key> however these use 87the supplied I<key> internally and so I<key> will be freed when the parent 88I<pkey> is freed. These macros are deprecated. Applications should instead read 89an EVP_PKEY directly using the OSSL_DECODER APIs (see 90L<OSSL_DECODER_CTX_new_for_pkey(3)>), or construct an EVP_PKEY from data using 91L<EVP_PKEY_fromdata(3)>. 92 93EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and 94EVP_PKEY_get1_EC_KEY() return the referenced key in I<pkey> or NULL if the 95key is not of the correct type. The returned key must be freed after use. 96These functions are deprecated. Applications should instead use the EVP_PKEY 97directly where possible. If access to the low level key parameters is required 98then applications should use L<EVP_PKEY_get_params(3)> and other similar 99functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see 100L<OSSL_ENCODER_CTX_new_for_pkey(3)>). 101 102EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), 103EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and 104EVP_PKEY_get0_EC_KEY() return the referenced key in I<pkey> or NULL if the 105key is not of the correct type. The reference count of the returned key is 106B<not> incremented and so the key must not be freed after use. These functions 107are deprecated. Applications should instead use the EVP_PKEY directly where 108possible. If access to the low level key parameters is required then 109applications should use L<EVP_PKEY_get_params(3)> and other similar functions. 110To write an EVP_PKEY out use the OSSL_ENCODER APIs (see 111L<OSSL_ENCODER_CTX_new_for_pkey(3)>). EVP_PKEY_get0() returns a pointer to the 112legacy key or NULL if the key is not legacy. 113 114Note that if an EVP_PKEY was not constructed using one of the deprecated 115functions such as EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() 116or EVP_PKEY_set1_EC_KEY(), or via the similarly named B<EVP_PKEY_assign> macros 117described above then the internal key will be managed by a provider (see 118L<provider(7)>). In that case the key returned by EVP_PKEY_get1_RSA(), 119EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_EC_KEY(), 120EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), 121EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() or 122EVP_PKEY_get0_EC_KEY() will be a cached copy of the provider's key. Subsequent 123updates to the provider's key will not be reflected back in the cached copy, and 124updates made by an application to the returned key will not be reflected back in 125the provider's key. Subsequent calls to EVP_PKEY_get1_RSA(), 126EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() will always 127return the cached copy returned by the first call. 128 129EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I<pkey>. This 130function is deprecated. Applications should use providers instead of engines 131(see L<provider(7)> for details). 132 133EVP_PKEY_set1_engine() sets the ENGINE handling I<pkey> to I<engine>. It 134must be called after the key algorithm and components are set up. 135If I<engine> does not include an B<EVP_PKEY_METHOD> for I<pkey> an 136error occurs. This function is deprecated. Applications should use providers 137instead of engines (see L<provider(7)> for details). 138 139=head1 WARNINGS 140 141The following functions are only reliable with B<EVP_PKEY>s that have 142been assigned an internal key with EVP_PKEY_assign_*(): 143 144EVP_PKEY_get_id(), EVP_PKEY_get_base_id(), EVP_PKEY_type() 145 146For EVP_PKEY key type checking purposes, L<EVP_PKEY_is_a(3)> is more generic. 147 148For purposes of retrieving the name of the B<EVP_PKEY> the function 149L<EVP_PKEY_get0_type_name(3)> is more generally useful. 150 151The keys returned from the functions EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), 152EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() were changed to have a "const" 153return type in OpenSSL 3.0. As described above the keys returned may be cached 154copies of the key held in a provider. Due to this, and unlike in earlier 155versions of OpenSSL, they should be considered read-only copies of the key. 156Updates to these keys will not be reflected back in the provider side key. The 157EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and 158EVP_PKEY_get1_EC_KEY() functions were not changed to have a "const" return type 159in order that applications can "free" the return value. However applications 160should still consider them as read-only copies. 161 162=head1 NOTES 163 164In accordance with the OpenSSL naming convention the key obtained 165from or assigned to the I<pkey> using the B<1> functions must be 166freed as well as I<pkey>. 167 168EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), 169EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() 170and EVP_PKEY_assign_SIPHASH() are implemented as macros. 171 172EVP_PKEY_assign_EC_KEY() looks at the curve name id to determine if 173the passed B<EC_KEY> is an L<SM2(7)> key, and will set the B<EVP_PKEY> 174type to B<EVP_PKEY_SM2> in that case, instead of B<EVP_PKEY_EC>. 175 176Most applications wishing to know a key type will simply call 177EVP_PKEY_get_base_id() and will not care about the actual type: 178which will be identical in almost all cases. 179 180Previous versions of this document suggested using EVP_PKEY_type(pkey->type) 181to determine the type of a key. Since B<EVP_PKEY> is now opaque this 182is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey). 183 184EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM 185key as part of its routine to load a private key. 186 187=head1 RETURN VALUES 188 189EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and 190EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. 191 192EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and 193EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if 194an error occurred. 195 196EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), 197EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() 198and EVP_PKEY_assign_SIPHASH() return 1 for success and 0 for failure. 199 200EVP_PKEY_get_base_id(), EVP_PKEY_get_id() and EVP_PKEY_type() return a key 201type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. 202 203EVP_PKEY_set1_engine() returns 1 for success and 0 for failure. 204 205=head1 SEE ALSO 206 207L<EVP_PKEY_new(3)>, L<SM2(7)> 208 209=head1 HISTORY 210 211The EVP_PKEY_id() and EVP_PKEY_base_id() functions were renamed to 212include C<get> in their names in OpenSSL 3.0, respectively. The old names 213are kept as non-deprecated alias macros. 214 215EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, 216EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, 217EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, 218EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, 219EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, 220EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, 221EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were deprecated in OpenSSL 3.0. 222 223The return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, 224EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0. 225 226The function EVP_PKEY_set_alias_type() was previously documented on this page. 227It was removed in OpenSSL 3.0. 228 229=head1 COPYRIGHT 230 231Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. 232 233Licensed under the Apache License 2.0 (the "License"). You may not use 234this file except in compliance with the License. You can obtain a copy 235in the file LICENSE in the source distribution or at 236L<https://www.openssl.org/source/license.html>. 237 238=cut 239