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