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