Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_new.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_NEW 3SSL"
58 .TH EVP_PKEY_NEW 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,
65 EVP_PKEY_new,
66 EVP_PKEY_up_ref,
67 EVP_PKEY_dup,
68 EVP_PKEY_free,
69 EVP_PKEY_new_raw_private_key_ex,
70 EVP_PKEY_new_raw_private_key,
71 EVP_PKEY_new_raw_public_key_ex,
72 EVP_PKEY_new_raw_public_key,
73 EVP_PKEY_new_CMAC_key,
74 EVP_PKEY_new_mac_key,
75 EVP_PKEY_get_raw_private_key,
76 EVP_PKEY_get_raw_public_key
77 \&\- public/private key allocation and raw key handling functions
78 .SH SYNOPSIS
79 .IX Header "SYNOPSIS"
80 .Vb 1
81 \& #include <openssl/evp.h>
82 \&
83 \& typedef evp_pkey_st EVP_PKEY;
84 \&
85 \& EVP_PKEY *EVP_PKEY_new(void);
86 \& int EVP_PKEY_up_ref(EVP_PKEY *key);
87 \& EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key);
88 \& void EVP_PKEY_free(EVP_PKEY *key);
89 \&
90 \& EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx,
91 \& const char *keytype,
92 \& const char *propq,
93 \& const unsigned char *key,
94 \& size_t keylen);
95 \& EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e,
96 \& const unsigned char *key, size_t keylen);
97 \& EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx,
98 \& const char *keytype,
99 \& const char *propq,
100 \& const unsigned char *key,
101 \& size_t keylen);
102 \& EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e,
103 \& const unsigned char *key, size_t keylen);
104 \& EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key,
105 \& int keylen);
106 \&
107 \& int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv,
108 \& size_t *len);
109 \& int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub,
110 \& size_t *len);
111 .Ve
112 .PP
113 The following function has been deprecated since OpenSSL 3.0, and can be
114 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
115 see \fBopenssl_user_macros\fR\|(7):
116 .PP
117 .Vb 2
118 \& EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
119 \& size_t len, const EVP_CIPHER *cipher);
120 .Ve
121 .SH DESCRIPTION
122 .IX Header "DESCRIPTION"
123 \&\fBEVP_PKEY\fR is a generic structure to hold diverse types of asymmetric keys
124 (also known as "key pairs"), and can be used for diverse operations, like
125 signing, verifying signatures, key derivation, etc. The asymmetric keys
126 themselves are often referred to as the "internal key", and are handled by
127 backends, such as providers (through \fBEVP_KEYMGMT\fR\|(3)) or \fBENGINE\fRs.
128 .PP
129 Conceptually, an \fBEVP_PKEY\fR internal key may hold a private key, a public
130 key, or both (a keypair), and along with those, key parameters if the key type
131 requires them. The presence of these components determine what operations can
132 be made; for example, signing normally requires the presence of a private key,
133 and verifying normally requires the presence of a public key.
134 .PP
135 \&\fBEVP_PKEY\fR has also been used for MAC algorithm that were conceived as
136 producing signatures, although not being public key algorithms; "POLY1305",
137 "SIPHASH", "HMAC", "CMAC". This usage is considered legacy and is discouraged
138 in favor of the \fBEVP_MAC\fR\|(3) API.
139 .PP
140 The \fBEVP_PKEY_new()\fR function allocates an empty \fBEVP_PKEY\fR structure which is
141 used by OpenSSL to store public and private keys. The reference count is set to
142 \&\fB1\fR.
143 .PP
144 \&\fBEVP_PKEY_up_ref()\fR increments the reference count of \fIkey\fR.
145 .PP
146 \&\fBEVP_PKEY_dup()\fR duplicates the \fIkey\fR. The \fIkey\fR must not be ENGINE based or
147 a raw key, otherwise the duplication will fail.
148 .PP
149 \&\fBEVP_PKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference
150 count is zero, frees it up. If \fIkey\fR is NULL, nothing is done.
151 .PP
152 \&\fBEVP_PKEY_new_raw_private_key_ex()\fR allocates a new \fBEVP_PKEY\fR. Unless an
153 engine should be used for the key type, a provider for the key is found using
154 the library context \fIlibctx\fR and the property query string \fIpropq\fR. The
155 \&\fIkeytype\fR argument indicates what kind of key this is. The value should be a
156 string for a public key algorithm that supports raw private keys, e.g., one of:
157 \&\f(CW\*(C`ED25519\*(C'\fR,
158 \&\f(CW\*(C`ED448\*(C'\fR,
159 \&\f(CW\*(C`X25519\*(C'\fR,
160 \&\f(CW\*(C`X448\*(C'\fR,
161 \&\f(CW\*(C`ML\-DSA\-44\*(C'\fR,
162 \&\f(CW\*(C`ML\-DSA\-65\*(C'\fR,
163 \&\f(CW\*(C`ML\-DSA\-87\*(C'\fR,
164 \&\f(CW\*(C`ML\-KEM\-512\*(C'\fR,
165 \&\f(CW\*(C`ML\-KEM\-768\*(C'\fR,
166 or
167 \&\f(CW\*(C`ML\-KEM\-1024\*(C'\fR.
168 \&\fIkey\fR points to the raw private key
169 data for this \fBEVP_PKEY\fR which should be of length \fIkeylen\fR. The length
170 should be appropriate for the type of the key. The public key data will be
171 automatically derived from the given private key data (if appropriate for the
172 algorithm type).
173 .PP
174 \&\fBEVP_PKEY_new_raw_private_key()\fR does the same as
175 \&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that the default library context and
176 default property query are used instead. If \fIe\fR is non-NULL then the new
177 \&\fBEVP_PKEY\fR structure is associated with the engine \fIe\fR. The \fItype\fR argument
178 indicates what kind of key this is. The value should be a NID for a public key
179 algorithm that supports raw private keys, i.e. one of \fBEVP_PKEY_X25519\fR,
180 \&\fBEVP_PKEY_ED25519\fR, \fBEVP_PKEY_X448\fR or \fBEVP_PKEY_ED448\fR.
181 .PP
182 \&\fBEVP_PKEY_new_raw_private_key_ex()\fR and \fBEVP_PKEY_new_raw_private_key()\fR may also
183 be used with most MACs implemented as public key algorithms, so key types such
184 as "HMAC", "POLY1305", "SIPHASH", or their NID form \fBEVP_PKEY_POLY1305\fR,
185 \&\fBEVP_PKEY_SIPHASH\fR, \fBEVP_PKEY_HMAC\fR are also accepted. This usage is,
186 as mentioned above, discouraged in favor of the \fBEVP_MAC\fR\|(3) API.
187 .PP
188 \&\fBEVP_PKEY_new_raw_public_key_ex()\fR works in the same way as
189 \&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that \fIkey\fR points to the raw
190 public key data. The \fBEVP_PKEY\fR structure will be initialised without any
191 private key information. Algorithm types that support raw public keys are
192 \&\fBED25519\fR,
193 \&\fBED448\fR,
194 \&\fBX25519\fR,
195 \&\fBX448\fR,
196 \&\f(CW\*(C`ML\-DSA\-44\*(C'\fR,
197 \&\f(CW\*(C`ML\-DSA\-65\*(C'\fR,
198 \&\f(CW\*(C`ML\-DSA\-87\*(C'\fR,
199 \&\fBML\-KEM\-512\fR,
200 \&\fBML\-KEM\-768\fR,
201 and
202 \&\fBML\-KEM\-1024\fR.
203 .PP
204 \&\fBEVP_PKEY_new_raw_public_key()\fR works in the same way as
205 \&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that \fIkey\fR points to the raw public
206 key data.
207 The \fBEVP_PKEY\fR structure will be initialised without any private key
208 information.
209 .PP
210 \&\fBEVP_PKEY_new_mac_key()\fR works in the same way as \fBEVP_PKEY_new_raw_private_key()\fR.
211 New applications should use \fBEVP_PKEY_new_raw_private_key()\fR instead.
212 .PP
213 \&\fBEVP_PKEY_get_raw_private_key()\fR fills the buffer provided by \fIpriv\fR with raw
214 private key data. The size of the \fIpriv\fR buffer should be in \fI*len\fR on entry
215 to the function, and on exit \fI*len\fR is updated with the number of bytes
216 actually written. If the buffer \fIpriv\fR is NULL then \fI*len\fR is populated with
217 the number of bytes required to hold the key. The calling application is
218 responsible for ensuring that the buffer is large enough to receive the private
219 key data. This function only works for algorithms that support raw private keys.
220 These include:
221 \&\fBED25519\fR,
222 \&\fBED448\fR,
223 \&\fBX25519\fR,
224 \&\fBX448\fR,
225 \&\fBHMAC\fR,
226 \&\fBPOLY1305\fR,
227 and
228 \&\fBSIPHASH\fR.
229 \&\fBEVP_PKEY_get_raw_private_key()\fR also works with
230 \&\f(CW\*(C`ML\-DSA\-44\*(C'\fR,
231 \&\f(CW\*(C`ML\-DSA\-65\*(C'\fR,
232 \&\f(CW\*(C`ML\-DSA\-87\*(C'\fR,
233 \&\fBML\-KEM\-512\fR,
234 \&\fBML\-KEM\-768\fR and
235 \&\fBML\-KEM\-1024\fR
236 keys, which don't have legacy numeric \fINID\fR assignments, but their raw form is
237 nevertheless available.
238 .PP
239 \&\fBEVP_PKEY_get_raw_public_key()\fR fills the buffer provided by \fIpub\fR with raw
240 public key data. The size of the \fIpub\fR buffer should be in \fI*len\fR on entry
241 to the function, and on exit \fI*len\fR is updated with the number of bytes
242 actually written. If the buffer \fIpub\fR is NULL then \fI*len\fR is populated with
243 the number of bytes required to hold the key. The calling application is
244 responsible for ensuring that the buffer is large enough to receive the public
245 key data. This function only works for algorithms that support raw public keys.
246 These include:
247 \&\fBED25519\fR,
248 \&\fBED448\fR,
249 \&\fBX25519\fR,
250 and
251 \&\fBX448\fR
252 \&\fBEVP_PKEY_get_raw_public_key()\fR also works with
253 \&\f(CW\*(C`ML\-DSA\-44\*(C'\fR,
254 \&\f(CW\*(C`ML\-DSA\-65\*(C'\fR,
255 \&\f(CW\*(C`ML\-DSA\-87\*(C'\fR,
256 \&\fBML\-KEM\-512\fR,
257 \&\fBML\-KEM\-768\fR and
258 \&\fBML\-KEM\-1024\fR
259 keys, which don't have legacy numeric \fINID\fR assignments, but their raw form is
260 nevertheless available.
261 .PP
262 \&\fBEVP_PKEY_new_CMAC_key()\fR works in the same way as \fBEVP_PKEY_new_raw_private_key()\fR
263 except it is only for the \fBEVP_PKEY_CMAC\fR algorithm type. In addition to the
264 raw private key data, it also takes a cipher algorithm to be used during
265 creation of a CMAC in the \fBcipher\fR argument. The cipher should be a standard
266 encryption-only cipher. For example AEAD and XTS ciphers should not be used.
267 .PP
268 Applications should use the \fBEVP_MAC\fR\|(3) API instead
269 and set the \fBOSSL_MAC_PARAM_CIPHER\fR parameter on the \fBEVP_MAC_CTX\fR object
270 with the name of the cipher being used.
271 .SH NOTES
272 .IX Header "NOTES"
273 The \fBEVP_PKEY\fR structure is used by various OpenSSL functions which require a
274 general private key without reference to any particular algorithm.
275 .PP
276 The structure returned by \fBEVP_PKEY_new()\fR is empty. To add a private or public
277 key to this empty structure use the appropriate functions described in
278 \&\fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_DSA\fR\|(3), \fBEVP_PKEY_set1_DH\fR\|(3) or
279 \&\fBEVP_PKEY_set1_EC_KEY\fR\|(3) for legacy key types implemented in internal
280 OpenSSL providers.
281 .PP
282 For fully provider-managed key types (see \fBprovider\-keymgmt\fR\|(7)),
283 possibly implemented in external providers, use functions such as
284 \&\fBEVP_PKEY_set1_encoded_public_key\fR\|(3) or \fBEVP_PKEY_fromdata\fR\|(3)
285 to populate key data.
286 .PP
287 Generally caution is advised for using an \fBEVP_PKEY\fR structure across
288 different library contexts: In order for an \fBEVP_PKEY\fR to be shared by
289 multiple library contexts the providers associated with the library contexts
290 must have key managers that support the key type and implement the
291 \&\fBOSSL_FUNC_keymgmt_import()\fR and \fBOSSL_FUNC_keymgmt_export()\fR functions.
292 .SH "RETURN VALUES"
293 .IX Header "RETURN VALUES"
294 \&\fBEVP_PKEY_new()\fR, \fBEVP_PKEY_new_raw_private_key()\fR, \fBEVP_PKEY_new_raw_public_key()\fR,
295 \&\fBEVP_PKEY_new_CMAC_key()\fR and \fBEVP_PKEY_new_mac_key()\fR return either the newly
296 allocated \fBEVP_PKEY\fR structure or NULL if an error occurred.
297 .PP
298 \&\fBEVP_PKEY_dup()\fR returns the key duplicate or NULL if an error occurred.
299 .PP
300 \&\fBEVP_PKEY_up_ref()\fR, \fBEVP_PKEY_get_raw_private_key()\fR and
301 \&\fBEVP_PKEY_get_raw_public_key()\fR return 1 for success and 0 for failure.
302 .SH "SEE ALSO"
303 .IX Header "SEE ALSO"
304 \&\fBEVP_PKEY_set1_RSA\fR\|(3),
305 \&\fBEVP_PKEY_set1_DSA\fR\|(3),
306 \&\fBEVP_PKEY_set1_DH\fR\|(3),
307 \&\fBEVP_PKEY_set1_EC_KEY\fR\|(3),
308 \&\fBEVP_PKEY\-ED25519\fR\|(7),
309 \&\fBEVP_PKEY\-ED448\fR\|(7).
310 \&\fBEVP_PKEY\-HMAC\fR\|(7),
311 \&\fBEVP_PKEY\-Poly1305\fR\|(7),
312 \&\fBEVP_PKEY\-Siphash\fR\|(7),
313 \&\fBEVP_PKEY\-X25519\fR\|(7),
314 \&\fBEVP_PKEY\-X448\fR\|(7),
315 \&\fBEVP_PKEY\-ML\-DSA\fR\|(7),
316 \&\fBEVP_PKEY\-ML\-KEM\fR\|(7).
317 .SH HISTORY
318 .IX Header "HISTORY"
319 The
320 \&\fBEVP_PKEY_new()\fR and \fBEVP_PKEY_free()\fR functions exist in all versions of OpenSSL.
321 .PP
322 The \fBEVP_PKEY_up_ref()\fR function was added in OpenSSL 1.1.0.
323 .PP
324 The
325 \&\fBEVP_PKEY_new_raw_private_key()\fR, \fBEVP_PKEY_new_raw_public_key()\fR,
326 \&\fBEVP_PKEY_new_CMAC_key()\fR, \fBEVP_PKEY_new_raw_private_key()\fR and
327 \&\fBEVP_PKEY_get_raw_public_key()\fR functions were added in OpenSSL 1.1.1.
328 .PP
329 The \fBEVP_PKEY_dup()\fR, \fBEVP_PKEY_new_raw_private_key_ex()\fR, and
330 \&\fBEVP_PKEY_new_raw_public_key_ex()\fR
331 functions were added in OpenSSL 3.0.
332 .PP
333 The \fBEVP_PKEY_new_CMAC_key()\fR was deprecated in OpenSSL 3.0.
334 .PP
335 The documentation of \fBEVP_PKEY\fR was amended in OpenSSL 3.0 to allow there to
336 be the private part of the keypair without the public part, where this was
337 previously implied to be disallowed.
338 .PP
339 Support for \fBML-DSA\fR and \fBML-KEM\fR was added in OpenSSL 3.5.
340 .SH COPYRIGHT
341 .IX Header "COPYRIGHT"
342 Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved.
343 .PP
344 Licensed under the Apache License 2.0 (the "License"). You may not use
345 this file except in compliance with the License. You can obtain a copy
346 in the file LICENSE in the source distribution or at
347 <https://www.openssl.org/source/license.html>.