5 EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable
6 - functions to create keys and key parameters from user data
10 #include <openssl/evp.h>
12 int EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx);
13 int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection,
15 const OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection);
19 The functions described here are used to create new keys from user
20 provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
23 These functions use an B<EVP_PKEY_CTX> context, which should primarily
24 be created with L<EVP_PKEY_CTX_new_from_name(3)> or
25 L<EVP_PKEY_CTX_new_id(3)>.
27 The exact key data that the user can pass depends on the key type.
28 These are passed as an L<OSSL_PARAM(3)> array.
30 EVP_PKEY_fromdata_init() initializes a public key algorithm context
31 for creating a key or key parameters from user data.
33 EVP_PKEY_fromdata() creates the structure to store a key or key parameters,
34 given data from I<params>, I<selection> and a context that's been initialized
35 with EVP_PKEY_fromdata_init(). The result is written to I<*ppkey>.
36 I<selection> is described in L</Selections>.
37 The parameters that can be used for various types of key are as described by the
38 diverse "Common parameters" sections of the
39 L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
40 L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
41 L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
42 L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
43 L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
44 L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
45 L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
46 and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
48 =for comment the awful list of links above is made this way so we get nice
49 rendering as a man-page while still getting proper links in HTML
51 EVP_PKEY_fromdata_settable() gets a constant B<OSSL_PARAM> array that describes
52 the settable parameters that can be used with EVP_PKEY_fromdata().
53 I<selection> is described in L</Selections>.
54 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
58 The following constants can be used for I<selection>:
62 =item B<EVP_PKEY_KEY_PARAMETERS>
64 Only key parameters will be selected.
66 =item B<EVP_PKEY_PUBLIC_KEY>
68 Only public key components will be selected. This includes optional key
71 =item B<EVP_PKEY_KEYPAIR>
73 Any keypair components will be selected. This includes the private key,
74 public key and key parameters.
80 These functions only work with key management methods coming from a provider.
81 This is the mirror function to L<EVP_PKEY_todata(3)>.
83 =for comment We may choose to make this available for legacy methods too...
87 EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or
88 a negative value for failure. In particular a return value of -2 indicates the
89 operation is not supported by the public key algorithm.
93 These examples are very terse for the sake of staying on topic, which
94 is the EVP_PKEY_fromdata() set of functions. In real applications,
95 BIGNUMs would be handled and converted to byte arrays with
96 BN_bn2nativepad(), but that's off topic here.
100 TODO Write a set of cookbook documents and link to them.
104 =head2 Creating an RSA keypair using raw key data
106 #include <openssl/evp.h>
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.
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),
126 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
127 EVP_PKEY *pkey = NULL;
130 || EVP_PKEY_fromdata_init(ctx) <= 0
131 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
134 /* Do what you want with |pkey| */
137 =head2 Creating an ECC keypair using raw key data
139 #include <openssl/evp.h>
140 #include <openssl/param_build.h>
143 * Fixed data to represent the private and public key.
145 const unsigned char priv_data[] = {
146 0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
147 0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
148 0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
149 0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
151 /* UNCOMPRESSED FORMAT */
152 const unsigned char pub_data[] = {
153 POINT_CONVERSION_UNCOMPRESSED,
154 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
155 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
156 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
157 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
158 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
159 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
160 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
161 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
163 const OSSL_PARAM params[] = {
164 OSSL_PARAM_utf8_string("group", "prime256v1"),
165 OSSL_PARAM_BN("priv", priv, sizeof(priv)),
166 OSSL_PARAM_BN("pub", pub, sizeof(pub)),
173 EVP_PKEY *pkey = NULL;
175 OSSL_PARAM_BLD *param_bld;
176 OSSL_PARAM *params = NULL;
179 priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
181 param_bld = OSSL_PARAM_BLD_new();
182 if (priv != NULL && param_bld != NULL
183 && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
185 && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv);
186 && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
187 pub_data, sizeof(pub_data)))
188 params = OSSL_PARAM_BLD_to_param(param_bld);
190 ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
193 || EVP_PKEY_fromdata_init(ctx) <= 0
194 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
197 /* Do what you want with |pkey| */
201 EVP_PKEY_CTX_free(ctx);
202 OSSL_PARAM_free(params);
203 OSSL_PARAM_BLD_free(param_bld);
209 =head2 Finding out params for an unknown key type
211 #include <openssl/evp.h>
213 /* Program expects a key type as first argument */
214 int main(int argc, char *argv[])
216 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
217 const *OSSL_PARAM *settable_params = NULL;
221 settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
222 if (settable_params == NULL)
225 for (; settable_params->key != NULL; settable_params++) {
226 const char *datatype = NULL;
228 switch (settable_params->data_type) {
229 case OSSL_PARAM_INTEGER:
230 datatype = "integer";
232 case OSSL_PARAM_UNSIGNED_INTEGER:
233 datatype = "unsigned integer";
235 case OSSL_PARAM_UTF8_STRING:
236 datatype = "printable string (utf-8 encoding expected)";
238 case OSSL_PARAM_UTF8_PTR:
239 datatype = "printable string pointer (utf-8 encoding expected)";
241 case OSSL_PARAM_OCTET_STRING:
242 datatype = "octet string";
244 case OSSL_PARAM_OCTET_PTR:
245 datatype = "octet string pointer";
248 printf("%s : %s ", settable_params->key, datatype);
249 if (settable_params->data_size == 0)
250 printf("(unlimited size)");
252 printf("(maximum size %zu)", settable_params->data_size);
256 The descriptor L<OSSL_PARAM(3)> returned by
257 EVP_PKEY_fromdata_settable() may also be used programmatically, for
258 example with L<OSSL_PARAM_allocate_from_text(3)>.
262 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
263 L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
264 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
265 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
266 L<EVP_PKEY-ED25519(7)>
270 These functions were added in OpenSSL 3.0.
274 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
276 Licensed under the Apache License 2.0 (the "License"). You may not use
277 this file except in compliance with the License. You can obtain a copy
278 in the file LICENSE in the source distribution or at
279 L<https://www.openssl.org/source/license.html>.