1EVP_PKEY_FROMDATA(3ossl)            OpenSSL           EVP_PKEY_FROMDATA(3ossl)
2
3
4

NAME

6       EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable -
7       functions to create keys and key parameters from user data
8

SYNOPSIS

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

DESCRIPTION

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
21       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
24       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
27       EVP_PKEY_fromdata_init() initializes a public key algorithm context for
28       creating a key or key parameters from user data.
29
30       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
39       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
43       Parameters in the params array that are not among the settable
44       parameters for the given selection are ignored.
45
46   Selections
47       The following constants can be used for selection:
48
49       EVP_PKEY_KEY_PARAMETERS
50           Only key parameters will be selected.
51
52       EVP_PKEY_PUBLIC_KEY
53           Only public key components will be selected. This includes optional
54           key parameters.
55
56       EVP_PKEY_KEYPAIR
57           Any keypair components will be selected. This includes the private
58           key, public key and key parameters.
59

NOTES

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

RETURN VALUES

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

EXAMPLES

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
76   Creating an RSA keypair using raw key data
77        #include <openssl/evp.h>
78
79        /*
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
95        int main()
96        {
97            EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
98            EVP_PKEY *pkey = NULL;
99
100            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
105            /* Do what you want with |pkey| */
106        }
107
108   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
113        /*
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
135        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
144            priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
145
146            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
155            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
165            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
171            exit(exitcode);
172        }
173
174   Finding out params for an unknown key type
175        #include <openssl/evp.h>
176        #include <openssl/core.h>
177
178        /* 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
184            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
190            for (; settable_params->key != NULL; settable_params++) {
191                const char *datatype = NULL;
192
193                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
221       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

SEE ALSO

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

HISTORY

232       These functions were added in OpenSSL 3.0.
233
235       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
236
237       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>.
241
242
243
2443.1.1                             2023-08-31          EVP_PKEY_FROMDATA(3ossl)
Impressum