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