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