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