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