1=pod 2 3=head1 NAME 4 5EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - key and parameter generation functions 6 7=head1 SYNOPSIS 8 9 #include <openssl/evp.h> 10 11 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); 12 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); 13 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); 14 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); 15 16 typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); 17 18 void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); 19 EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); 20 21 int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); 22 23 void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); 24 void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); 25 26=head1 DESCRIPTION 27 28The EVP_PKEY_keygen_init() function initializes a public key algorithm 29context using key B<pkey> for a key genration operation. 30 31The EVP_PKEY_keygen() function performs a key generation operation, the 32generated key is written to B<ppkey>. 33 34The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar 35except parameters are generated. 36 37The function EVP_PKEY_set_cb() sets the key or parameter generation callback 38to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter 39generation callback. 40 41The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated 42with the generation operation. If B<idx> is -1 the total number of 43parameters available is returned. Any non negative value returns the value of 44that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for 45B<idx> should only be called within the generation callback. 46 47If the callback returns 0 then the key genration operation is aborted and an 48error occurs. This might occur during a time consuming operation where 49a user clicks on a "cancel" button. 50 51The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set 52and retrieve an opaque pointer. This can be used to set some application 53defined value which can be retrieved in the callback: for example a handle 54which is used to update a "progress dialog". 55 56=head1 NOTES 57 58After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm 59specific control operations can be performed to set any appropriate parameters 60for the operation. 61 62The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than 63once on the same context if several operations are performed using the same 64parameters. 65 66The meaning of the parameters passed to the callback will depend on the 67algorithm and the specifiic implementation of the algorithm. Some might not 68give any useful information at all during key or parameter generation. Others 69might not even call the callback. 70 71The operation performed by key or parameter generation depends on the algorithm 72used. In some cases (e.g. EC with a supplied named curve) the "generation" 73option merely sets the appropriate fields in an EVP_PKEY structure. 74 75In OpenSSL an EVP_PKEY structure containing a private key also contains the 76public key components and parameters (if any). An OpenSSL private key is 77equivalent to what some libraries call a "key pair". A private key can be used 78in functions which require the use of a public key or parameters. 79 80=head1 RETURN VALUES 81 82EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and 83EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. 84In particular a return value of -2 indicates the operation is not supported by 85the public key algorithm. 86 87=head1 EXAMPLES 88 89Generate a 2048 bit RSA key: 90 91 #include <openssl/evp.h> 92 #include <openssl/rsa.h> 93 94 EVP_PKEY_CTX *ctx; 95 EVP_PKEY *pkey = NULL; 96 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); 97 if (!ctx) 98 /* Error occurred */ 99 if (EVP_PKEY_keygen_init(ctx) <= 0) 100 /* Error */ 101 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) 102 /* Error */ 103 104 /* Generate key */ 105 if (EVP_PKEY_keygen(ctx, &pkey) <= 0) 106 /* Error */ 107 108Generate a key from a set of parameters: 109 110 #include <openssl/evp.h> 111 #include <openssl/rsa.h> 112 113 EVP_PKEY_CTX *ctx; 114 EVP_PKEY *pkey = NULL, *param; 115 /* Assumed param is set up already */ 116 ctx = EVP_PKEY_CTX_new(param); 117 if (!ctx) 118 /* Error occurred */ 119 if (EVP_PKEY_keygen_init(ctx) <= 0) 120 /* Error */ 121 122 /* Generate key */ 123 if (EVP_PKEY_keygen(ctx, &pkey) <= 0) 124 /* Error */ 125 126Example of generation callback for OpenSSL public key implementations: 127 128 /* Application data is a BIO to output status to */ 129 130 EVP_PKEY_CTX_set_app_data(ctx, status_bio); 131 132 static int genpkey_cb(EVP_PKEY_CTX *ctx) 133 { 134 char c='*'; 135 BIO *b = EVP_PKEY_CTX_get_app_data(ctx); 136 int p; 137 p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); 138 if (p == 0) c='.'; 139 if (p == 1) c='+'; 140 if (p == 2) c='*'; 141 if (p == 3) c='\n'; 142 BIO_write(b,&c,1); 143 (void)BIO_flush(b); 144 return 1; 145 } 146 147=head1 SEE ALSO 148 149L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, 150L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, 151L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, 152L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, 153L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, 154L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, 155L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> 156 157=head1 HISTORY 158 159These functions were first added to OpenSSL 1.0.0. 160 161=cut 162