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 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
44   Selections
45       The following constants can be used for selection:
46
47       EVP_PKEY_KEY_PARAMETERS
48           Only key parameters will be selected.
49
50       EVP_PKEY_PUBLIC_KEY
51           Only public key components will be selected. This includes optional
52           key parameters.
53
54       EVP_PKEY_KEYPAIR
55           Any keypair components will be selected. This includes the private
56           key, public key and key parameters.
57

NOTES

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

RETURN VALUES

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

EXAMPLES

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
74   Creating an RSA keypair using raw key data
75        #include <openssl/evp.h>
76
77        /*
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
93        int main()
94        {
95            EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
96            EVP_PKEY *pkey = NULL;
97
98            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
103            /* Do what you want with |pkey| */
104        }
105
106   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
111        /*
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
133        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
142            priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
143
144            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
153            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
163            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
169            exit(exitcode);
170        }
171
172   Finding out params for an unknown key type
173        #include <openssl/evp.h>
174        #include <openssl/core.h>
175
176        /* 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
182            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
188            for (; settable_params->key != NULL; settable_params++) {
189                const char *datatype = NULL;
190
191                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
219       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

SEE ALSO

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

HISTORY

230       These functions were added in OpenSSL 3.0.
231
233       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
234
235       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>.
239
240
241
2423.0.5                             2022-11-01          EVP_PKEY_FROMDATA(3ossl)
Impressum