1EVP_PKEY_FROMDATA(3ossl) OpenSSL EVP_PKEY_FROMDATA(3ossl)
2
6 EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable -
7 functions to create keys and key parameters from user data
8
10 #include <openssl/evp.h>
11 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
18 The functions described here are used to create new keys from user
19 provided key data, such as n, e and d for a minimal RSA keypair.
20 These functions use an EVP_PKEY_CTX context, which should primarily be
22 created with EVP_PKEY_CTX_new_from_name(3) or EVP_PKEY_CTX_new_id(3).
23 The exact key data that the user can pass depends on the key type.
25 These are passed as an OSSL_PARAM(3) array.
26 EVP_PKEY_fromdata_init() initializes a public key algorithm context for
28 creating a key or key parameters from user data.
29 EVP_PKEY_fromdata() creates the structure to store a key or key
31 parameters, given data from params, selection and a context that's been
32 initialized with EVP_PKEY_fromdata_init(). The result is written to
33 *ppkey. selection is described in "Selections". The parameters that
34 can be used for various types of key are as described by the diverse
35 "Common parameters" sections of the EVP_PKEY-RSA(7), EVP_PKEY-DSA(7),
36 EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-ED448(7), EVP_PKEY-X25519(7),
37 EVP_PKEY-X448(7), and EVP_PKEY-ED25519(7) pages.
38 EVP_PKEY_fromdata_settable() gets a constant OSSL_PARAM(3) array that
40 describes the settable parameters that can be used with
41 EVP_PKEY_fromdata(). selection is described in "Selections".
42 Parameters in the params array that are not among the settable
44 parameters for the given selection are ignored.
45 Selections
47 The following constants can be used for selection:
48 EVP_PKEY_KEY_PARAMETERS
50 Only key parameters will be selected.
51 EVP_PKEY_PUBLIC_KEY
53 Only public key components will be selected. This includes optional
54 key parameters.
55 EVP_PKEY_KEYPAIR
57 Any keypair components will be selected. This includes the private
58 key, public key and key parameters.
59
61 These functions only work with key management methods coming from a
62 provider. This is the mirror function to EVP_PKEY_todata(3).
63
65 EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success
66 and 0 or a negative value for failure. In particular a return value of
67 -2 indicates the operation is not supported by the public key
68 algorithm.
69
71 These examples are very terse for the sake of staying on topic, which
72 is the EVP_PKEY_fromdata() set of functions. In real applications,
73 BIGNUMs would be handled and converted to byte arrays with
74 BN_bn2nativepad(), but that's off topic here.
75 Creating an RSA keypair using raw key data
77 #include <openssl/evp.h>
78 /*
80 * These are extremely small to make this example simple. A real
81 * and secure application will not use such small numbers. A real
82 * and secure application is expected to use BIGNUMs, and to build
83 * this array dynamically.
84 */
85 unsigned long rsa_n = 0xbc747fc5;
86 unsigned long rsa_e = 0x10001;
87 unsigned long rsa_d = 0x7b133399;
88 OSSL_PARAM params[] = {
89 OSSL_PARAM_ulong("n", &rsa_n),
90 OSSL_PARAM_ulong("e", &rsa_e),
91 OSSL_PARAM_ulong("d", &rsa_d),
92 OSSL_PARAM_END
93 };
94 int main()
96 {
97 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
98 EVP_PKEY *pkey = NULL;
99 if (ctx == NULL
101 || EVP_PKEY_fromdata_init(ctx) <= 0
102 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
103 exit(1);
104 /* Do what you want with |pkey| */
106 }
107 Creating an ECC keypair using raw key data
109 #include <openssl/evp.h>
110 #include <openssl/param_build.h>
111 #include <openssl/ec.h>
112 /*
114 * Fixed data to represent the private and public key.
115 */
116 const unsigned char priv_data[] = {
117 0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
118 0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
119 0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
120 0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
121 };
122 /* UNCOMPRESSED FORMAT */
123 const unsigned char pub_data[] = {
124 POINT_CONVERSION_UNCOMPRESSED,
125 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
126 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
127 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
128 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
129 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
130 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
131 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
132 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
133 };
134 int main()
136 {
137 EVP_PKEY_CTX *ctx;
138 EVP_PKEY *pkey = NULL;
139 BIGNUM *priv;
140 OSSL_PARAM_BLD *param_bld;
141 OSSL_PARAM *params = NULL;
142 int exitcode = 0;
143 priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
145 param_bld = OSSL_PARAM_BLD_new();
147 if (priv != NULL && param_bld != NULL
148 && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
149 "prime256v1", 0)
150 && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv)
151 && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
152 pub_data, sizeof(pub_data)))
153 params = OSSL_PARAM_BLD_to_param(param_bld);
154 ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
156 if (ctx == NULL
157 || params == NULL
158 || EVP_PKEY_fromdata_init(ctx) <= 0
159 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
160 exitcode = 1;
161 } else {
162 /* Do what you want with |pkey| */
163 }
164 EVP_PKEY_free(pkey);
166 EVP_PKEY_CTX_free(ctx);
167 OSSL_PARAM_free(params);
168 OSSL_PARAM_BLD_free(param_bld);
169 BN_free(priv);
170 exit(exitcode);
172 }
173 Finding out params for an unknown key type
175 #include <openssl/evp.h>
176 #include <openssl/core.h>
177 /* Program expects a key type as first argument */
179 int main(int argc, char *argv[])
180 {
181 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
182 const OSSL_PARAM *settable_params = NULL;
183 if (ctx == NULL)
185 exit(1);
186 settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
187 if (settable_params == NULL)
188 exit(1);
189 for (; settable_params->key != NULL; settable_params++) {
191 const char *datatype = NULL;
192 switch (settable_params->data_type) {
194 case OSSL_PARAM_INTEGER:
195 datatype = "integer";
196 break;
197 case OSSL_PARAM_UNSIGNED_INTEGER:
198 datatype = "unsigned integer";
199 break;
200 case OSSL_PARAM_UTF8_STRING:
201 datatype = "printable string (utf-8 encoding expected)";
202 break;
203 case OSSL_PARAM_UTF8_PTR:
204 datatype = "printable string pointer (utf-8 encoding expected)";
205 break;
206 case OSSL_PARAM_OCTET_STRING:
207 datatype = "octet string";
208 break;
209 case OSSL_PARAM_OCTET_PTR:
210 datatype = "octet string pointer";
211 break;
212 }
213 printf("%s : %s ", settable_params->key, datatype);
214 if (settable_params->data_size == 0)
215 printf("(unlimited size)\n");
216 else
217 printf("(maximum size %zu)\n", settable_params->data_size);
218 }
219 }
220 The descriptor OSSL_PARAM(3) returned by EVP_PKEY_fromdata_settable()
222 may also be used programmatically, for example with
223 OSSL_PARAM_allocate_from_text(3).
224
226 EVP_PKEY_CTX_new(3), provider(7), EVP_PKEY_gettable_params(3),
227 OSSL_PARAM(3), EVP_PKEY_todata(3), EVP_PKEY-RSA(7), EVP_PKEY-DSA(7),
228 EVP_PKEY-DH(7), EVP_PKEY-EC(7), EVP_PKEY-ED448(7), EVP_PKEY-X25519(7),
229 EVP_PKEY-X448(7), EVP_PKEY-ED25519(7)
230
232 These functions were added in OpenSSL 3.0.
233
235 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
236 Licensed under the Apache License 2.0 (the "License"). You may not use
238 this file except in compliance with the License. You can obtain a copy
239 in the file LICENSE in the source distribution or at
240 <https://www.openssl.org/source/license.html>.
2413.1.1 2023-08-31 EVP_PKEY_FROMDATA(3ossl)