1=pod 2 3=head1 NAME 4 5EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable 6- functions to create keys and key parameters from user data 7 8=head1 SYNOPSIS 9 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 17=head1 DESCRIPTION 18 19The functions described here are used to create new keys from user 20provided key data, such as I<n>, I<e> and I<d> for a minimal RSA 21keypair. 22 23These functions use an B<EVP_PKEY_CTX> context, which should primarily 24be created with L<EVP_PKEY_CTX_new_from_name(3)> or 25L<EVP_PKEY_CTX_new_id(3)>. 26 27The exact key data that the user can pass depends on the key type. 28These are passed as an L<OSSL_PARAM(3)> array. 29 30EVP_PKEY_fromdata_init() initializes a public key algorithm context 31for creating a key or key parameters from user data. 32 33EVP_PKEY_fromdata() creates the structure to store a key or key parameters, 34given data from I<params>, I<selection> and a context that's been initialized 35with EVP_PKEY_fromdata_init(). The result is written to I<*ppkey>. 36I<selection> is described in L</Selections>. 37The parameters that can be used for various types of key are as described by 38the various "Common parameters" sections of the 39L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>, 40L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>, 41L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>, 42L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>, 43L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>, 44L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>, 45L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>, 46L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters>, 47L<B<EVP_PKEY-ML-DSA(7)>|EVP_PKEY-ML-DSA(7)/Common parameters> 48and 49L<B<EVP_PKEY-ML-KEM(7)>|EVP_PKEY-ML-KEM(7)/Common parameters> 50pages. 51 52=for comment the awful list of links above is made this way so we get nice 53rendering as a man-page while still getting proper links in HTML 54 55EVP_PKEY_fromdata_settable() gets a constant L<OSSL_PARAM(3)> array that describes 56the settable parameters that can be used with EVP_PKEY_fromdata(). 57I<selection> is described in L</Selections>. 58 59Parameters in the I<params> array that are not among the settable parameters 60for the given I<selection> are ignored. 61 62=head2 Selections 63 64The following constants can be used for I<selection>: 65 66=over 4 67 68=item B<EVP_PKEY_KEY_PARAMETERS> 69 70Only key parameters will be selected. 71 72=item B<EVP_PKEY_PUBLIC_KEY> 73 74Only public key components will be selected. This includes optional key 75parameters. 76 77=item B<EVP_PKEY_KEYPAIR> 78 79Any keypair components will be selected. This includes the private key, 80public key and key parameters. 81 82=back 83 84=head1 NOTES 85 86These functions only work with key management methods coming from a provider. 87This is the mirror function to L<EVP_PKEY_todata(3)>. 88 89=for comment We may choose to make this available for legacy methods too... 90 91=head1 RETURN VALUES 92 93EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or 94a negative value for failure. In particular a return value of -2 indicates the 95operation is not supported by the public key algorithm. 96 97=head1 EXAMPLES 98 99These examples are very terse for the sake of staying on topic, which 100is the EVP_PKEY_fromdata() set of functions. In real applications, 101BIGNUMs would be handled and converted to byte arrays with 102BN_bn2nativepad(), but that's off topic here. 103 104=begin comment 105 106TODO Write a set of cookbook documents and link to them. 107 108=end comment 109 110=head2 Creating an RSA keypair using raw key data 111 112 #include <openssl/evp.h> 113 114 /* 115 * These are extremely small to make this example simple. A real 116 * and secure application will not use such small numbers. A real 117 * and secure application is expected to use BIGNUMs, and to build 118 * this array dynamically. 119 */ 120 unsigned long rsa_n = 0xbc747fc5; 121 unsigned long rsa_e = 0x10001; 122 unsigned long rsa_d = 0x7b133399; 123 OSSL_PARAM params[] = { 124 OSSL_PARAM_ulong("n", &rsa_n), 125 OSSL_PARAM_ulong("e", &rsa_e), 126 OSSL_PARAM_ulong("d", &rsa_d), 127 OSSL_PARAM_END 128 }; 129 130 int main() 131 { 132 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); 133 EVP_PKEY *pkey = NULL; 134 135 if (ctx == NULL 136 || EVP_PKEY_fromdata_init(ctx) <= 0 137 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) 138 exit(1); 139 140 /* Do what you want with |pkey| */ 141 } 142 143=head2 Creating an ECC keypair using raw key data 144 145 #include <openssl/evp.h> 146 #include <openssl/param_build.h> 147 #include <openssl/ec.h> 148 149 /* 150 * Fixed data to represent the private and public key. 151 */ 152 const unsigned char priv_data[] = { 153 0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68, 154 0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2, 155 0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54, 156 0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d 157 }; 158 /* UNCOMPRESSED FORMAT */ 159 const unsigned char pub_data[] = { 160 POINT_CONVERSION_UNCOMPRESSED, 161 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e, 162 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58, 163 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb, 164 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5, 165 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff, 166 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25, 167 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f, 168 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47 169 }; 170 171 int main() 172 { 173 EVP_PKEY_CTX *ctx; 174 EVP_PKEY *pkey = NULL; 175 BIGNUM *priv; 176 OSSL_PARAM_BLD *param_bld; 177 OSSL_PARAM *params = NULL; 178 int exitcode = 0; 179 180 priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL); 181 182 param_bld = OSSL_PARAM_BLD_new(); 183 if (priv != NULL && param_bld != NULL 184 && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group", 185 "prime256v1", 0) 186 && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv) 187 && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub", 188 pub_data, sizeof(pub_data))) 189 params = OSSL_PARAM_BLD_to_param(param_bld); 190 191 ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 192 if (ctx == NULL 193 || params == NULL 194 || EVP_PKEY_fromdata_init(ctx) <= 0 195 || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) { 196 exitcode = 1; 197 } else { 198 /* Do what you want with |pkey| */ 199 } 200 201 EVP_PKEY_free(pkey); 202 EVP_PKEY_CTX_free(ctx); 203 OSSL_PARAM_free(params); 204 OSSL_PARAM_BLD_free(param_bld); 205 BN_free(priv); 206 207 exit(exitcode); 208 } 209 210=head2 Finding out params for an unknown key type 211 212 #include <openssl/evp.h> 213 #include <openssl/core.h> 214 215 /* Program expects a key type as first argument */ 216 int main(int argc, char *argv[]) 217 { 218 EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL); 219 const OSSL_PARAM *settable_params = NULL; 220 221 if (ctx == NULL) 222 exit(1); 223 settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR); 224 if (settable_params == NULL) 225 exit(1); 226 227 for (; settable_params->key != NULL; settable_params++) { 228 const char *datatype = NULL; 229 230 switch (settable_params->data_type) { 231 case OSSL_PARAM_INTEGER: 232 datatype = "integer"; 233 break; 234 case OSSL_PARAM_UNSIGNED_INTEGER: 235 datatype = "unsigned integer"; 236 break; 237 case OSSL_PARAM_UTF8_STRING: 238 datatype = "printable string (utf-8 encoding expected)"; 239 break; 240 case OSSL_PARAM_UTF8_PTR: 241 datatype = "printable string pointer (utf-8 encoding expected)"; 242 break; 243 case OSSL_PARAM_OCTET_STRING: 244 datatype = "octet string"; 245 break; 246 case OSSL_PARAM_OCTET_PTR: 247 datatype = "octet string pointer"; 248 break; 249 } 250 printf("%s : %s ", settable_params->key, datatype); 251 if (settable_params->data_size == 0) 252 printf("(unlimited size)\n"); 253 else 254 printf("(maximum size %zu)\n", settable_params->data_size); 255 } 256 } 257 258The descriptor L<OSSL_PARAM(3)> returned by 259EVP_PKEY_fromdata_settable() may also be used programmatically, for 260example with L<OSSL_PARAM_allocate_from_text(3)>. 261 262=head1 SEE ALSO 263 264L<EVP_PKEY_CTX_new(3)>, 265L<EVP_PKEY_todata(3)>, 266L<EVP_PKEY_gettable_params(3)>, 267L<OSSL_PARAM(3)>, 268L<provider(7)>, 269L<EVP_PKEY-RSA(7)>, 270L<EVP_PKEY-EC(7)>, 271L<EVP_PKEY-ED25519(7)>, 272L<EVP_PKEY-ED448(7)>, 273L<EVP_PKEY-DSA(7)>, 274L<EVP_PKEY-DH(7)>, 275L<EVP_PKEY-X25519(7)>, 276L<EVP_PKEY-X448(7)>, 277L<EVP_PKEY-ML-DSA(7)>, 278L<EVP_PKEY-ML-KEM(7)>, 279L<EVP_PKEY-SLH-DSA(7)>. 280 281=head1 HISTORY 282 283These functions were added in OpenSSL 3.0. 284 285Support for B<ML-DSA>, B<ML-KEM> and B<SLH-DSA> was added in OpenSSL 3.5. 286 287=head1 COPYRIGHT 288 289Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 290 291Licensed under the Apache License 2.0 (the "License"). You may not use 292this file except in compliance with the License. You can obtain a copy 293in the file LICENSE in the source distribution or at 294L<https://www.openssl.org/source/license.html>. 295 296=cut 297 298