Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_set1_RSA.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_SET1_RSA 3SSL"
58 .TH EVP_PKEY_SET1_RSA 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
65 EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
66 EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
67 EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
68 EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
69 EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
70 EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id,
71 EVP_PKEY_set1_engine, EVP_PKEY_get0_engine,
72 EVP_PKEY_id, EVP_PKEY_base_id \-
73 EVP_PKEY assignment functions
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& #include <openssl/evp.h>
78 \&
79 \& int EVP_PKEY_get_id(const EVP_PKEY *pkey);
80 \& int EVP_PKEY_get_base_id(const EVP_PKEY *pkey);
81 \& int EVP_PKEY_type(int type);
82 \&
83 \& #define EVP_PKEY_id EVP_PKEY_get_id
84 \& #define EVP_PKEY_base_id EVP_PKEY_get_base_id
85 .Ve
86 .PP
87 The following functions have been deprecated since OpenSSL 3.0, and can be
88 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
89 see \fBopenssl_user_macros\fR\|(7):
90 .PP
91 .Vb 4
92 \& int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
93 \& int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
94 \& int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
95 \& int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
96 \&
97 \& RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
98 \& DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
99 \& DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
100 \& EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
101 \&
102 \& const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
103 \& const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
104 \& const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
105 \& const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);
106 \& const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);
107 \& const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);
108 \& const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);
109 \& void *EVP_PKEY_get0(const EVP_PKEY *pkey);
110 \&
111 \& int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
112 \& int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
113 \& int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
114 \& int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
115 \& int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
116 \& int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
117 \&
118 \& ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
119 \& int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
120 .Ve
121 .SH DESCRIPTION
122 .IX Header "DESCRIPTION"
123 \&\fBEVP_PKEY_get_base_id()\fR returns the type of \fIpkey\fR. For example
124 an RSA key will return \fBEVP_PKEY_RSA\fR.
125 .PP
126 \&\fBEVP_PKEY_get_id()\fR returns the actual NID associated with \fIpkey\fR
127 only if the \fIpkey\fR type isn't implemented just in a \fBprovider\fR\|(7).
128 Historically keys using the same algorithm could use different NIDs.
129 For example an RSA key could use the NIDs corresponding to
130 the NIDs \fBNID_rsaEncryption\fR (equivalent to \fBEVP_PKEY_RSA\fR) or
131 \&\fBNID_rsa\fR (equivalent to \fBEVP_PKEY_RSA2\fR). The use of
132 alternative non-standard NIDs is now rare so \fBEVP_PKEY_RSA2\fR et al are not
133 often seen in practice.
134 \&\fBEVP_PKEY_get_id()\fR returns \-1 (\fBEVP_PKEY_KEYMGMT\fR) if the \fIpkey\fR is
135 only implemented in a \fBprovider\fR\|(7).
136 .PP
137 \&\fBEVP_PKEY_type()\fR returns the underlying type of the NID \fItype\fR. For example
138 EVP_PKEY_type(EVP_PKEY_RSA2) will return \fBEVP_PKEY_RSA\fR.
139 .PP
140 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
141 \&\fBEVP_PKEY_set1_EC_KEY()\fR set the key referenced by \fIpkey\fR to \fIkey\fR. These
142 functions are deprecated. Applications should instead use
143 \&\fBEVP_PKEY_fromdata\fR\|(3).
144 .PP
145 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
146 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR and
147 \&\fBEVP_PKEY_assign_SIPHASH()\fR set the referenced key to \fIkey\fR however these use
148 the supplied \fIkey\fR internally and so \fIkey\fR will be freed when the parent
149 \&\fIpkey\fR is freed. These macros are deprecated. Applications should instead read
150 an EVP_PKEY directly using the OSSL_DECODER APIs (see
151 \&\fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3)), or construct an EVP_PKEY from data using
152 \&\fBEVP_PKEY_fromdata\fR\|(3).
153 .PP
154 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
155 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key in \fIpkey\fR or NULL if the
156 key is not of the correct type. The returned key must be freed after use.
157 These functions are deprecated. Applications should instead use the EVP_PKEY
158 directly where possible. If access to the low level key parameters is required
159 then applications should use \fBEVP_PKEY_get_params\fR\|(3) and other similar
160 functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
161 \&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3)).
162 .PP
163 \&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR,
164 \&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR and
165 \&\fBEVP_PKEY_get0_EC_KEY()\fR return the referenced key in \fIpkey\fR or NULL if the
166 key is not of the correct type. The reference count of the returned key is
167 \&\fBnot\fR incremented and so the key must not be freed after use. These functions
168 are deprecated. Applications should instead use the EVP_PKEY directly where
169 possible. If access to the low level key parameters is required then
170 applications should use \fBEVP_PKEY_get_params\fR\|(3) and other similar functions.
171 To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
172 \&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3)). \fBEVP_PKEY_get0()\fR returns a pointer to the
173 legacy key or NULL if the key is not legacy.
174 .PP
175 Note that if an EVP_PKEY was not constructed using one of the deprecated
176 functions such as \fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR
177 or \fBEVP_PKEY_set1_EC_KEY()\fR, or via the similarly named \fBEVP_PKEY_assign\fR macros
178 described above then the internal key will be managed by a provider (see
179 \&\fBprovider\fR\|(7)). In that case the key returned by \fBEVP_PKEY_get1_RSA()\fR,
180 \&\fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_EC_KEY()\fR,
181 \&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR,
182 \&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR or
183 \&\fBEVP_PKEY_get0_EC_KEY()\fR will be a cached copy of the provider's key. Subsequent
184 updates to the provider's key will not be reflected back in the cached copy, and
185 updates made by an application to the returned key will not be reflected back in
186 the provider's key. Subsequent calls to \fBEVP_PKEY_get1_RSA()\fR,
187 \&\fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and \fBEVP_PKEY_get1_EC_KEY()\fR will always
188 return the cached copy returned by the first call.
189 .PP
190 \&\fBEVP_PKEY_get0_engine()\fR returns a reference to the ENGINE handling \fIpkey\fR. This
191 function is deprecated. Applications should use providers instead of engines
192 (see \fBprovider\fR\|(7) for details).
193 .PP
194 \&\fBEVP_PKEY_set1_engine()\fR sets the ENGINE handling \fIpkey\fR to \fIengine\fR. It
195 must be called after the key algorithm and components are set up.
196 If \fIengine\fR does not include an \fBEVP_PKEY_METHOD\fR for \fIpkey\fR an
197 error occurs. This function is deprecated. Applications should use providers
198 instead of engines (see \fBprovider\fR\|(7) for details).
199 .SH WARNINGS
200 .IX Header "WARNINGS"
201 The following functions are only reliable with \fBEVP_PKEY\fRs that have
202 been assigned an internal key with EVP_PKEY_assign_*():
203 .PP
204 \&\fBEVP_PKEY_get_id()\fR, \fBEVP_PKEY_get_base_id()\fR, \fBEVP_PKEY_type()\fR
205 .PP
206 For EVP_PKEY key type checking purposes, \fBEVP_PKEY_is_a\fR\|(3) is more generic.
207 .PP
208 For purposes of retrieving the name of the \fBEVP_PKEY\fR the function
209 \&\fBEVP_PKEY_get0_type_name\fR\|(3) is more generally useful.
210 .PP
211 The keys returned from the functions \fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR,
212 \&\fBEVP_PKEY_get0_DH()\fR and \fBEVP_PKEY_get0_EC_KEY()\fR were changed to have a "const"
213 return type in OpenSSL 3.0. As described above the keys returned may be cached
214 copies of the key held in a provider. Due to this, and unlike in earlier
215 versions of OpenSSL, they should be considered read-only copies of the key.
216 Updates to these keys will not be reflected back in the provider side key. The
217 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
218 \&\fBEVP_PKEY_get1_EC_KEY()\fR functions were not changed to have a "const" return type
219 in order that applications can "free" the return value. However applications
220 should still consider them as read-only copies.
221 .SH NOTES
222 .IX Header "NOTES"
223 In accordance with the OpenSSL naming convention the key obtained
224 from or assigned to the \fIpkey\fR using the \fB1\fR functions must be
225 freed as well as \fIpkey\fR.
226 .PP
227 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
228 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
229 and \fBEVP_PKEY_assign_SIPHASH()\fR are implemented as macros.
230 .PP
231 \&\fBEVP_PKEY_assign_EC_KEY()\fR looks at the curve name id to determine if
232 the passed \fBEC_KEY\fR is an \fBSM2\fR\|(7) key, and will set the \fBEVP_PKEY\fR
233 type to \fBEVP_PKEY_SM2\fR in that case, instead of \fBEVP_PKEY_EC\fR.
234 .PP
235 Most applications wishing to know a key type will simply call
236 \&\fBEVP_PKEY_get_base_id()\fR and will not care about the actual type:
237 which will be identical in almost all cases.
238 .PP
239 Previous versions of this document suggested using EVP_PKEY_type(pkey\->type)
240 to determine the type of a key. Since \fBEVP_PKEY\fR is now opaque this
241 is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey).
242 .PP
243 \&\fBEVP_PKEY_set1_engine()\fR is typically used by an ENGINE returning an HSM
244 key as part of its routine to load a private key.
245 .SH "RETURN VALUES"
246 .IX Header "RETURN VALUES"
247 \&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and
248 \&\fBEVP_PKEY_set1_EC_KEY()\fR return 1 for success or 0 for failure.
249 .PP
250 \&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and
251 \&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key or NULL if
252 an error occurred.
253 .PP
254 \&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR,
255 \&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR
256 and \fBEVP_PKEY_assign_SIPHASH()\fR return 1 for success and 0 for failure.
257 .PP
258 \&\fBEVP_PKEY_get_base_id()\fR, \fBEVP_PKEY_get_id()\fR and \fBEVP_PKEY_type()\fR return a key
259 type or \fBNID_undef\fR (equivalently \fBEVP_PKEY_NONE\fR) on error.
260 .PP
261 \&\fBEVP_PKEY_set1_engine()\fR returns 1 for success and 0 for failure.
262 .SH "SEE ALSO"
263 .IX Header "SEE ALSO"
264 \&\fBEVP_PKEY_new\fR\|(3), \fBSM2\fR\|(7)
265 .SH HISTORY
266 .IX Header "HISTORY"
267 The \fBEVP_PKEY_id()\fR and \fBEVP_PKEY_base_id()\fR functions were renamed to
268 include \f(CW\*(C`get\*(C'\fR in their names in OpenSSL 3.0, respectively. The old names
269 are kept as non-deprecated alias macros.
270 .PP
271 EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
272 EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
273 EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
274 EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
275 EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
276 EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
277 EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were deprecated in OpenSSL 3.0.
278 .PP
279 The return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH,
280 EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0.
281 .PP
282 The function \fBEVP_PKEY_set_alias_type()\fR was previously documented on this page.
283 It was removed in OpenSSL 3.0.
284 .SH COPYRIGHT
285 .IX Header "COPYRIGHT"
286 Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
287 .PP
288 Licensed under the Apache License 2.0 (the "License"). You may not use
289 this file except in compliance with the License. You can obtain a copy
290 in the file LICENSE in the source distribution or at
291 <https://www.openssl.org/source/license.html>.