5 EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
6 EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
7 EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
8 EVP_PKEY_CTX_get_app_data,
10 - key and parameter generation functions
14 #include <openssl/evp.h>
16 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
17 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
18 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
19 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
21 typedef int (*EVP_PKEY_gen_cb)(EVP_PKEY_CTX *ctx);
23 void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
24 EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
26 int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
28 void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
29 void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
33 The EVP_PKEY_keygen_init() function initializes a public key algorithm
34 context using key B<pkey> for a key generation operation.
36 The EVP_PKEY_keygen() function performs a key generation operation, the
37 generated key is written to B<ppkey>.
39 The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
40 except parameters are generated.
42 The function EVP_PKEY_set_cb() sets the key or parameter generation callback
43 to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
46 The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
47 with the generation operation. If B<idx> is -1 the total number of
48 parameters available is returned. Any non negative value returns the value of
49 that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
50 B<idx> should only be called within the generation callback.
52 If the callback returns 0 then the key generation operation is aborted and an
53 error occurs. This might occur during a time consuming operation where
54 a user clicks on a "cancel" button.
56 The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
57 and retrieve an opaque pointer. This can be used to set some application
58 defined value which can be retrieved in the callback: for example a handle
59 which is used to update a "progress dialog".
63 After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
64 specific control operations can be performed to set any appropriate parameters
67 The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
68 once on the same context if several operations are performed using the same
71 The meaning of the parameters passed to the callback will depend on the
72 algorithm and the specific implementation of the algorithm. Some might not
73 give any useful information at all during key or parameter generation. Others
74 might not even call the callback.
76 The operation performed by key or parameter generation depends on the algorithm
77 used. In some cases (e.g. EC with a supplied named curve) the "generation"
78 option merely sets the appropriate fields in an EVP_PKEY structure.
80 In OpenSSL an EVP_PKEY structure containing a private key also contains the
81 public key components and parameters (if any). An OpenSSL private key is
82 equivalent to what some libraries call a "key pair". A private key can be used
83 in functions which require the use of a public key or parameters.
87 EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
88 EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
89 In particular a return value of -2 indicates the operation is not supported by
90 the public key algorithm.
94 Generate a 2048 bit RSA key:
96 #include <openssl/evp.h>
97 #include <openssl/rsa.h>
100 EVP_PKEY *pkey = NULL;
102 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
105 if (EVP_PKEY_keygen_init(ctx) <= 0)
107 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
111 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
114 Generate a key from a set of parameters:
116 #include <openssl/evp.h>
117 #include <openssl/rsa.h>
120 EVP_PKEY *pkey = NULL, *param;
122 /* Assumed param is set up already */
123 ctx = EVP_PKEY_CTX_new(param);
126 if (EVP_PKEY_keygen_init(ctx) <= 0)
130 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
133 Example of generation callback for OpenSSL public key implementations:
135 /* Application data is a BIO to output status to */
137 EVP_PKEY_CTX_set_app_data(ctx, status_bio);
139 static int genpkey_cb(EVP_PKEY_CTX *ctx)
142 BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
143 int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
160 L<EVP_PKEY_CTX_new(3)>,
161 L<EVP_PKEY_encrypt(3)>,
162 L<EVP_PKEY_decrypt(3)>,
164 L<EVP_PKEY_verify(3)>,
165 L<EVP_PKEY_verify_recover(3)>,
166 L<EVP_PKEY_derive(3)>
170 These functions were first added to OpenSSL 1.0.0.
174 Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
176 Licensed under the OpenSSL license (the "License"). You may not use
177 this file except in compliance with the License. You can obtain a copy
178 in the file LICENSE in the source distribution or at
179 L<https://www.openssl.org/source/license.html>.