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