Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_fromdata.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_FROMDATA 3SSL"
58 .TH EVP_PKEY_FROMDATA 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_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable
65 \&\- functions to create keys and key parameters from user data
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/evp.h>
70 \&
71 \& int EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx);
72 \& int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection,
73 \& OSSL_PARAM params[]);
74 \& const OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection);
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 The functions described here are used to create new keys from user
79 provided key data, such as \fIn\fR, \fIe\fR and \fId\fR for a minimal RSA
80 keypair.
81 .PP
82 These functions use an \fBEVP_PKEY_CTX\fR context, which should primarily
83 be created with \fBEVP_PKEY_CTX_new_from_name\fR\|(3) or
84 \&\fBEVP_PKEY_CTX_new_id\fR\|(3).
85 .PP
86 The exact key data that the user can pass depends on the key type.
87 These are passed as an \fBOSSL_PARAM\fR\|(3) array.
88 .PP
89 \&\fBEVP_PKEY_fromdata_init()\fR initializes a public key algorithm context
90 for creating a key or key parameters from user data.
91 .PP
92 \&\fBEVP_PKEY_fromdata()\fR creates the structure to store a key or key parameters,
93 given data from \fIparams\fR, \fIselection\fR and a context that's been initialized
94 with \fBEVP_PKEY_fromdata_init()\fR. The result is written to \fI*ppkey\fR.
95 \&\fIselection\fR is described in "Selections".
96 The parameters that can be used for various types of key are as described by
97 the various "Common parameters" sections of the
98 \&\fBEVP_PKEY\-RSA\fR(7),
99 \&\fBEVP_PKEY\-DSA\fR(7),
100 \&\fBEVP_PKEY\-DH\fR(7),
101 \&\fBEVP_PKEY\-EC\fR(7),
102 \&\fBEVP_PKEY\-ED448\fR(7),
103 \&\fBEVP_PKEY\-X25519\fR(7),
104 \&\fBEVP_PKEY\-X448\fR(7),
105 \&\fBEVP_PKEY\-ED25519\fR(7),
106 \&\fBEVP_PKEY\-ML\-DSA\|(7)\fR
107 and
108 \&\fBEVP_PKEY\-ML\-KEM\|(7)\fR
109 pages.
110 .PP
111 \&\fBEVP_PKEY_fromdata_settable()\fR gets a constant \fBOSSL_PARAM\fR\|(3) array that describes
112 the settable parameters that can be used with \fBEVP_PKEY_fromdata()\fR.
113 \&\fIselection\fR is described in "Selections".
114 .PP
115 Parameters in the \fIparams\fR array that are not among the settable parameters
116 for the given \fIselection\fR are ignored.
117 .SS Selections
118 .IX Subsection "Selections"
119 The following constants can be used for \fIselection\fR:
120 .IP \fBEVP_PKEY_KEY_PARAMETERS\fR 4
121 .IX Item "EVP_PKEY_KEY_PARAMETERS"
122 Only key parameters will be selected.
123 .IP \fBEVP_PKEY_PUBLIC_KEY\fR 4
124 .IX Item "EVP_PKEY_PUBLIC_KEY"
125 Only public key components will be selected. This includes optional key
126 parameters.
127 .IP \fBEVP_PKEY_KEYPAIR\fR 4
128 .IX Item "EVP_PKEY_KEYPAIR"
129 Any keypair components will be selected. This includes the private key,
130 public key and key parameters.
131 .SH NOTES
132 .IX Header "NOTES"
133 These functions only work with key management methods coming from a provider.
134 This is the mirror function to \fBEVP_PKEY_todata\fR\|(3).
135 .PP
136 LMS support is disabled by default at compile-time.
137 To enable, specify the \fBenable-lms\fR build configuration option.
138 .SH "RETURN VALUES"
139 .IX Header "RETURN VALUES"
140 \&\fBEVP_PKEY_fromdata_init()\fR and \fBEVP_PKEY_fromdata()\fR return 1 for success and 0 or
141 a negative value for failure. In particular a return value of \-2 indicates the
142 operation is not supported by the public key algorithm.
143 .SH EXAMPLES
144 .IX Header "EXAMPLES"
145 These examples are very terse for the sake of staying on topic, which
146 is the \fBEVP_PKEY_fromdata()\fR set of functions. In real applications,
147 BIGNUMs would be handled and converted to byte arrays with
148 \&\fBBN_bn2nativepad()\fR, but that's off topic here.
149 .SS "Creating an RSA keypair using raw key data"
150 .IX Subsection "Creating an RSA keypair using raw key data"
151 .Vb 1
152 \& #include <openssl/evp.h>
153 \&
154 \& /*
155 \& * These are extremely small to make this example simple. A real
156 \& * and secure application will not use such small numbers. A real
157 \& * and secure application is expected to use BIGNUMs, and to build
158 \& * this array dynamically.
159 \& */
160 \& unsigned long rsa_n = 0xbc747fc5;
161 \& unsigned long rsa_e = 0x10001;
162 \& unsigned long rsa_d = 0x7b133399;
163 \& OSSL_PARAM params[] = {
164 \& OSSL_PARAM_ulong("n", &rsa_n),
165 \& OSSL_PARAM_ulong("e", &rsa_e),
166 \& OSSL_PARAM_ulong("d", &rsa_d),
167 \& OSSL_PARAM_END
168 \& };
169 \&
170 \& int main()
171 \& {
172 \& EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
173 \& EVP_PKEY *pkey = NULL;
174 \&
175 \& if (ctx == NULL
176 \& || EVP_PKEY_fromdata_init(ctx) <= 0
177 \& || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
178 \& exit(1);
179 \&
180 \& /* Do what you want with |pkey| */
181 \& }
182 .Ve
183 .SS "Creating an ECC keypair using raw key data"
184 .IX Subsection "Creating an ECC keypair using raw key data"
185 .Vb 3
186 \& #include <openssl/evp.h>
187 \& #include <openssl/param_build.h>
188 \& #include <openssl/ec.h>
189 \&
190 \& /*
191 \& * Fixed data to represent the private and public key.
192 \& */
193 \& const unsigned char priv_data[] = {
194 \& 0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
195 \& 0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
196 \& 0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
197 \& 0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
198 \& };
199 \& /* UNCOMPRESSED FORMAT */
200 \& const unsigned char pub_data[] = {
201 \& POINT_CONVERSION_UNCOMPRESSED,
202 \& 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
203 \& 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
204 \& 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
205 \& 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
206 \& 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
207 \& 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
208 \& 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
209 \& 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
210 \& };
211 \&
212 \& int main()
213 \& {
214 \& EVP_PKEY_CTX *ctx;
215 \& EVP_PKEY *pkey = NULL;
216 \& BIGNUM *priv;
217 \& OSSL_PARAM_BLD *param_bld;
218 \& OSSL_PARAM *params = NULL;
219 \& int exitcode = 0;
220 \&
221 \& priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
222 \&
223 \& param_bld = OSSL_PARAM_BLD_new();
224 \& if (priv != NULL && param_bld != NULL
225 \& && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
226 \& "prime256v1", 0)
227 \& && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv)
228 \& && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
229 \& pub_data, sizeof(pub_data)))
230 \& params = OSSL_PARAM_BLD_to_param(param_bld);
231 \&
232 \& ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
233 \& if (ctx == NULL
234 \& || params == NULL
235 \& || EVP_PKEY_fromdata_init(ctx) <= 0
236 \& || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
237 \& exitcode = 1;
238 \& } else {
239 \& /* Do what you want with |pkey| */
240 \& }
241 \&
242 \& EVP_PKEY_free(pkey);
243 \& EVP_PKEY_CTX_free(ctx);
244 \& OSSL_PARAM_free(params);
245 \& OSSL_PARAM_BLD_free(param_bld);
246 \& BN_free(priv);
247 \&
248 \& exit(exitcode);
249 \& }
250 .Ve
251 .SS "Finding out params for an unknown key type"
252 .IX Subsection "Finding out params for an unknown key type"
253 .Vb 2
254 \& #include <openssl/evp.h>
255 \& #include <openssl/core.h>
256 \&
257 \& /* Program expects a key type as first argument */
258 \& int main(int argc, char *argv[])
259 \& {
260 \& EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
261 \& const OSSL_PARAM *settable_params = NULL;
262 \&
263 \& if (ctx == NULL)
264 \& exit(1);
265 \& settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
266 \& if (settable_params == NULL)
267 \& exit(1);
268 \&
269 \& for (; settable_params\->key != NULL; settable_params++) {
270 \& const char *datatype = NULL;
271 \&
272 \& switch (settable_params\->data_type) {
273 \& case OSSL_PARAM_INTEGER:
274 \& datatype = "integer";
275 \& break;
276 \& case OSSL_PARAM_UNSIGNED_INTEGER:
277 \& datatype = "unsigned integer";
278 \& break;
279 \& case OSSL_PARAM_UTF8_STRING:
280 \& datatype = "printable string (utf\-8 encoding expected)";
281 \& break;
282 \& case OSSL_PARAM_UTF8_PTR:
283 \& datatype = "printable string pointer (utf\-8 encoding expected)";
284 \& break;
285 \& case OSSL_PARAM_OCTET_STRING:
286 \& datatype = "octet string";
287 \& break;
288 \& case OSSL_PARAM_OCTET_PTR:
289 \& datatype = "octet string pointer";
290 \& break;
291 \& }
292 \& printf("%s : %s ", settable_params\->key, datatype);
293 \& if (settable_params\->data_size == 0)
294 \& printf("(unlimited size)\en");
295 \& else
296 \& printf("(maximum size %zu)\en", settable_params\->data_size);
297 \& }
298 \& }
299 .Ve
300 .PP
301 The descriptor \fBOSSL_PARAM\fR\|(3) returned by
302 \&\fBEVP_PKEY_fromdata_settable()\fR may also be used programmatically, for
303 example with \fBOSSL_PARAM_allocate_from_text\fR\|(3).
304 .SH "SEE ALSO"
305 .IX Header "SEE ALSO"
306 \&\fBEVP_PKEY_CTX_new\fR\|(3),
307 \&\fBEVP_PKEY_todata\fR\|(3),
308 \&\fBEVP_PKEY_gettable_params\fR\|(3),
309 \&\fBOSSL_PARAM\fR\|(3),
310 \&\fBprovider\fR\|(7),
311 \&\fBEVP_PKEY\-RSA\fR\|(7),
312 \&\fBEVP_PKEY\-EC\fR\|(7),
313 \&\fBEVP_PKEY\-ED25519\fR\|(7),
314 \&\fBEVP_PKEY\-ED448\fR\|(7),
315 \&\fBEVP_PKEY\-LMS\fR\|(7),
316 \&\fBEVP_PKEY\-DSA\fR\|(7),
317 \&\fBEVP_PKEY\-DH\fR\|(7),
318 \&\fBEVP_PKEY\-X25519\fR\|(7),
319 \&\fBEVP_PKEY\-X448\fR\|(7),
320 \&\fBEVP_PKEY\-ML\-DSA\fR\|(7),
321 \&\fBEVP_PKEY\-ML\-KEM\fR\|(7),
322 \&\fBEVP_PKEY\-SLH\-DSA\fR\|(7).
323 .SH HISTORY
324 .IX Header "HISTORY"
325 These functions were added in OpenSSL 3.0.
326 .PP
327 Support for \fBML-DSA\fR, \fBML-KEM\fR and \fBSLH-DSA\fR was added in OpenSSL 3.5.
328 .PP
329 Support for \fBLMS\fR was added in OpenSSL 3.6.
330 .SH COPYRIGHT
331 .IX Header "COPYRIGHT"
332 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
333 .PP
334 Licensed under the Apache License 2.0 (the "License"). You may not use
335 this file except in compliance with the License. You can obtain a copy
336 in the file LICENSE in the source distribution or at
337 <https://www.openssl.org/source/license.html>.