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