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