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