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_get0_hmac, EVP_PKEY_type, EVP_PKEY_id, 10EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assignment functions 11 12=head1 SYNOPSIS 13 14 #include <openssl/evp.h> 15 16 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); 17 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); 18 int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key); 19 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); 20 21 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); 22 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); 23 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); 24 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); 25 26 const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); 27 RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey); 28 DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey); 29 DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey); 30 EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey); 31 32 int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); 33 int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); 34 int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); 35 int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); 36 37 int EVP_PKEY_id(const EVP_PKEY *pkey); 38 int EVP_PKEY_base_id(const EVP_PKEY *pkey); 39 int EVP_PKEY_type(int type); 40 int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type); 41 42 int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine); 43 44=head1 DESCRIPTION 45 46EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and 47EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>. 48 49EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and 50EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or 51B<NULL> if the key is not of the correct type. 52 53EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), 54EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the 55referenced key in B<pkey> or B<NULL> if the key is not of the 56correct type but the reference count of the returned key is 57B<not> incremented and so must not be freed up after use. 58 59EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() 60and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> 61however these use the supplied B<key> internally and so B<key> 62will be freed when the parent B<pkey> is freed. 63 64EVP_PKEY_base_id() returns the type of B<pkey>. For example 65an RSA key will return B<EVP_PKEY_RSA>. 66 67EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys 68using the same algorithm could use different OIDs. For example an RSA key could 69use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to 70B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of 71alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not 72often seen in practice. 73 74EVP_PKEY_type() returns the underlying type of the NID B<type>. For example 75EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>. 76 77EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It 78must be called after the key algorithm and components are set up. 79If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an 80error occurs. 81 82EVP_PKEY_set_alias_type() allows modifying a EVP_PKEY to use a 83different set of algorithms than the default. This is currently used 84to support SM2 keys, which use an identical encoding to ECDSA. 85 86=head1 NOTES 87 88In accordance with the OpenSSL naming convention the key obtained 89from or assigned to the B<pkey> using the B<1> functions must be 90freed as well as B<pkey>. 91 92EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() 93and EVP_PKEY_assign_EC_KEY() are implemented as macros. 94 95Most applications wishing to know a key type will simply call 96EVP_PKEY_base_id() and will not care about the actual type: 97which will be identical in almost all cases. 98 99Previous versions of this document suggested using EVP_PKEY_type(pkey->type) 100to determine the type of a key. Since B<EVP_PKEY> is now opaque this 101is no longer possible: the equivalent is EVP_PKEY_base_id(pkey). 102 103EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM 104key as part of its routine to load a private key. 105 106=head1 EXAMPLES 107 108After loading an ECC key, it is possible to convert it to using SM2 109algorithms with EVP_PKEY_set_alias_type: 110 111 EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2); 112 113=head1 RETURN VALUES 114 115EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and 116EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. 117 118EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and 119EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if 120an error occurred. 121 122EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() 123and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. 124 125EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key 126type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. 127 128EVP_PKEY_set1_engine() returns 1 for success and 0 for failure. 129 130EVP_PKEY_set_alias_type() returns 1 for success and 0 for error. 131 132=head1 SEE ALSO 133 134L<EVP_PKEY_new(3)> 135 136=head1 COPYRIGHT 137 138Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. 139 140Licensed under the OpenSSL license (the "License"). You may not use 141this file except in compliance with the License. You can obtain a copy 142in the file LICENSE in the source distribution or at 143L<https://www.openssl.org/source/license.html>. 144 145=cut 146