1=pod
2
3=head1 NAME
4
5EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable
6- functions to create keys and key parameters from user data
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx);
13 int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection,
14                       OSSL_PARAM params[]);
15 const OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection);
16
17=head1 DESCRIPTION
18
19The functions described here are used to create new keys from user
20provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
21keypair.
22
23These functions use an B<EVP_PKEY_CTX> context, which should primarily
24be created with L<EVP_PKEY_CTX_new_from_name(3)> or
25L<EVP_PKEY_CTX_new_id(3)>.
26
27The exact key data that the user can pass depends on the key type.
28These are passed as an L<OSSL_PARAM(3)> array.
29
30EVP_PKEY_fromdata_init() initializes a public key algorithm context
31for creating a key or key parameters from user data.
32
33EVP_PKEY_fromdata() creates the structure to store a key or key parameters,
34given data from I<params>, I<selection> and a context that's been initialized
35with EVP_PKEY_fromdata_init().  The result is written to I<*ppkey>.
36I<selection> is described in L</Selections>.
37The parameters that can be used for various types of key are as described by
38the various "Common parameters" sections of the
39L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
40L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
41L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
42L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
43L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
44L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
45L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
46L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
47L<B<EVP_PKEY-ML-DSA(7)>|EVP_PKEY-ML-DSA(7)/Common parameters>
48and
49L<B<EVP_PKEY-ML-KEM(7)>|EVP_PKEY-ML-KEM(7)/Common parameters>
50pages.
51
52=for comment the awful list of links above is made this way so we get nice
53rendering as a man-page while still getting proper links in HTML
54
55EVP_PKEY_fromdata_settable() gets a constant L<OSSL_PARAM(3)> array that describes
56the settable parameters that can be used with EVP_PKEY_fromdata().
57I<selection> is described in L</Selections>.
58
59Parameters in the I<params> array that are not among the settable parameters
60for the given I<selection> are ignored.
61
62=head2 Selections
63
64The following constants can be used for I<selection>:
65
66=over 4
67
68=item B<EVP_PKEY_KEY_PARAMETERS>
69
70Only key parameters will be selected.
71
72=item B<EVP_PKEY_PUBLIC_KEY>
73
74Only public key components will be selected. This includes optional key
75parameters.
76
77=item B<EVP_PKEY_KEYPAIR>
78
79Any keypair components will be selected. This includes the private key,
80public key and key parameters.
81
82=back
83
84=head1 NOTES
85
86These functions only work with key management methods coming from a provider.
87This is the mirror function to L<EVP_PKEY_todata(3)>.
88
89LMS support is disabled by default at compile-time.
90To enable, specify the B<enable-lms> build configuration option.
91
92=for comment We may choose to make this available for legacy methods too...
93
94=head1 RETURN VALUES
95
96EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or
97a negative value for failure.  In particular a return value of -2 indicates the
98operation is not supported by the public key algorithm.
99
100=head1 EXAMPLES
101
102These examples are very terse for the sake of staying on topic, which
103is the EVP_PKEY_fromdata() set of functions.  In real applications,
104BIGNUMs would be handled and converted to byte arrays with
105BN_bn2nativepad(), but that's off topic here.
106
107=begin comment
108
109TODO Write a set of cookbook documents and link to them.
110
111=end comment
112
113=head2 Creating an RSA keypair using raw key data
114
115 #include <openssl/evp.h>
116
117 /*
118  * These are extremely small to make this example simple.  A real
119  * and secure application will not use such small numbers.  A real
120  * and secure application is expected to use BIGNUMs, and to build
121  * this array dynamically.
122  */
123 unsigned long rsa_n = 0xbc747fc5;
124 unsigned long rsa_e = 0x10001;
125 unsigned long rsa_d = 0x7b133399;
126 OSSL_PARAM params[] = {
127     OSSL_PARAM_ulong("n", &rsa_n),
128     OSSL_PARAM_ulong("e", &rsa_e),
129     OSSL_PARAM_ulong("d", &rsa_d),
130     OSSL_PARAM_END
131 };
132
133 int main()
134 {
135     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
136     EVP_PKEY *pkey = NULL;
137
138     if (ctx == NULL
139         || EVP_PKEY_fromdata_init(ctx) <= 0
140         || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
141         exit(1);
142
143     /* Do what you want with |pkey| */
144 }
145
146=head2 Creating an ECC keypair using raw key data
147
148 #include <openssl/evp.h>
149 #include <openssl/param_build.h>
150 #include <openssl/ec.h>
151
152 /*
153  * Fixed data to represent the private and public key.
154  */
155 const unsigned char priv_data[] = {
156     0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
157     0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
158     0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
159     0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
160 };
161 /* UNCOMPRESSED FORMAT */
162 const unsigned char pub_data[] = {
163     POINT_CONVERSION_UNCOMPRESSED,
164     0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
165     0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
166     0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
167     0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
168     0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
169     0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
170     0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
171     0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
172 };
173
174 int main()
175 {
176     EVP_PKEY_CTX *ctx;
177     EVP_PKEY *pkey = NULL;
178     BIGNUM *priv;
179     OSSL_PARAM_BLD *param_bld;
180     OSSL_PARAM *params = NULL;
181     int exitcode = 0;
182
183     priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
184
185     param_bld = OSSL_PARAM_BLD_new();
186     if (priv != NULL && param_bld != NULL
187         && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
188                                            "prime256v1", 0)
189         && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv)
190         && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
191                                             pub_data, sizeof(pub_data)))
192         params = OSSL_PARAM_BLD_to_param(param_bld);
193
194     ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
195     if (ctx == NULL
196         || params == NULL
197         || EVP_PKEY_fromdata_init(ctx) <= 0
198         || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
199         exitcode = 1;
200     } else {
201         /* Do what you want with |pkey| */
202     }
203
204     EVP_PKEY_free(pkey);
205     EVP_PKEY_CTX_free(ctx);
206     OSSL_PARAM_free(params);
207     OSSL_PARAM_BLD_free(param_bld);
208     BN_free(priv);
209
210     exit(exitcode);
211 }
212
213=head2 Finding out params for an unknown key type
214
215 #include <openssl/evp.h>
216 #include <openssl/core.h>
217
218 /* Program expects a key type as first argument */
219 int main(int argc, char *argv[])
220 {
221     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
222     const OSSL_PARAM *settable_params = NULL;
223
224     if (ctx == NULL)
225        exit(1);
226    settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
227    if (settable_params == NULL)
228         exit(1);
229
230     for (; settable_params->key != NULL; settable_params++) {
231         const char *datatype = NULL;
232
233         switch (settable_params->data_type) {
234         case OSSL_PARAM_INTEGER:
235             datatype = "integer";
236             break;
237         case OSSL_PARAM_UNSIGNED_INTEGER:
238             datatype = "unsigned integer";
239             break;
240         case OSSL_PARAM_UTF8_STRING:
241             datatype = "printable string (utf-8 encoding expected)";
242             break;
243         case OSSL_PARAM_UTF8_PTR:
244             datatype = "printable string pointer (utf-8 encoding expected)";
245             break;
246         case OSSL_PARAM_OCTET_STRING:
247             datatype = "octet string";
248             break;
249         case OSSL_PARAM_OCTET_PTR:
250             datatype = "octet string pointer";
251             break;
252         }
253         printf("%s : %s ", settable_params->key, datatype);
254         if (settable_params->data_size == 0)
255             printf("(unlimited size)\n");
256         else
257             printf("(maximum size %zu)\n", settable_params->data_size);
258     }
259 }
260
261The descriptor L<OSSL_PARAM(3)> returned by
262EVP_PKEY_fromdata_settable() may also be used programmatically, for
263example with L<OSSL_PARAM_allocate_from_text(3)>.
264
265=head1 SEE ALSO
266
267L<EVP_PKEY_CTX_new(3)>,
268L<EVP_PKEY_todata(3)>,
269L<EVP_PKEY_gettable_params(3)>,
270L<OSSL_PARAM(3)>,
271L<provider(7)>,
272L<EVP_PKEY-RSA(7)>,
273L<EVP_PKEY-EC(7)>,
274L<EVP_PKEY-ED25519(7)>,
275L<EVP_PKEY-ED448(7)>,
276L<EVP_PKEY-LMS(7)>,
277L<EVP_PKEY-DSA(7)>,
278L<EVP_PKEY-DH(7)>,
279L<EVP_PKEY-X25519(7)>,
280L<EVP_PKEY-X448(7)>,
281L<EVP_PKEY-ML-DSA(7)>,
282L<EVP_PKEY-ML-KEM(7)>,
283L<EVP_PKEY-SLH-DSA(7)>.
284
285=head1 HISTORY
286
287These functions were added in OpenSSL 3.0.
288
289Support for B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5.
290
291Support for B<LMS> was added in OpenSSL 3.6.
292
293=head1 COPYRIGHT
294
295Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.
296
297Licensed under the Apache License 2.0 (the "License").  You may not use
298this file except in compliance with the License.  You can obtain a copy
299in the file LICENSE in the source distribution or at
300L<https://www.openssl.org/source/license.html>.
301
302=cut
303
304