]>
Commit | Line | Data |
---|---|---|
aa93b18c DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
62924755 RL |
5 | EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_gen, |
6 | EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, | |
c952780c | 7 | EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, |
121677b4 | 8 | EVP_PKEY_CTX_get_app_data, |
62924755 RL |
9 | EVP_PKEY_gen_cb, |
10 | EVP_PKEY_paramgen, EVP_PKEY_keygen | |
2aee35d3 | 11 | - key and parameter generation and check functions |
aa93b18c DSH |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/evp.h> | |
16 | ||
17 | int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); | |
aa93b18c | 18 | int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); |
62924755 | 19 | int EVP_PKEY_gen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); |
aa93b18c | 20 | int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); |
62924755 | 21 | int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); |
aa93b18c | 22 | |
5bf6d418 | 23 | typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); |
aa93b18c DSH |
24 | |
25 | void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); | |
26 | EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); | |
27 | ||
28 | int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); | |
29 | ||
30 | void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); | |
31 | void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); | |
32 | ||
33 | =head1 DESCRIPTION | |
34 | ||
62924755 RL |
35 | Generating keys is sometimes straight forward, just generate the key's |
36 | numbers and be done with it. However, there are certain key types that need | |
37 | key parameters, often called domain parameters but not necessarily limited | |
38 | to that, that also need to be generated. In addition to this, the caller | |
39 | may want to set user provided generation parameters that further affect key | |
40 | parameter or key generation, such as the desired key size. | |
41 | ||
42 | To flexibly allow all that's just been described, key parameter and key | |
43 | generation is divided into an initialization of a key algorithm context, | |
44 | functions to set user provided parameters, and finally the key parameter or | |
45 | key generation function itself. | |
46 | ||
47 | The key algorithm context must be created using L<EVP_PKEY_CTX_new(3)> or | |
48 | variants thereof, see that manual for details. | |
49 | ||
50 | EVP_PKEY_keygen_init() initializes a public key algorithm context using key | |
51 | I<pkey> for a key generation operation. | |
52 | ||
53 | EVP_PKEY_paramgen_init() is similar to EVP_PKEY_keygen_init() except key | |
54 | parameters are generated. | |
aa93b18c | 55 | |
62924755 RL |
56 | After initialization, generation parameters may be provided with |
57 | L<EVP_PKEY_CTX_ctrl(3)> or L<EVP_PKEY_CTX_set_params(3)>, or any other | |
58 | function described in those manuals. | |
aa93b18c | 59 | |
62924755 RL |
60 | EVP_PKEY_gen() performs the generation operation, the resulting key |
61 | parameters or key are written to I<*ppkey>. If I<*ppkey> is NULL when this | |
62 | function is called, it will be allocated, and should be freed by the caller | |
63 | when no longer useful, using L<EVP_PKEY_free(3)>. | |
64 | ||
65 | EVP_PKEY_paramgen() and EVP_PKEY_keygen() do exactly the same thing as | |
66 | EVP_PKEY_gen(), after checking that the corresponding EVP_PKEY_paramgen_init() | |
67 | or EVP_PKEY_keygen_init() was used to initialize I<ctx>. | |
68 | These are older functions that are kept for backward compatibility. | |
69 | It is safe to use EVP_PKEY_gen() instead. | |
aa93b18c DSH |
70 | |
71 | The function EVP_PKEY_set_cb() sets the key or parameter generation callback | |
62924755 | 72 | to I<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter |
aa93b18c DSH |
73 | generation callback. |
74 | ||
75 | The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated | |
62924755 | 76 | with the generation operation. If I<idx> is -1 the total number of |
aa93b18c DSH |
77 | parameters available is returned. Any non negative value returns the value of |
78 | that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for | |
62924755 | 79 | I<idx> should only be called within the generation callback. |
aa93b18c | 80 | |
186bb907 | 81 | If the callback returns 0 then the key generation operation is aborted and an |
aa93b18c DSH |
82 | error occurs. This might occur during a time consuming operation where |
83 | a user clicks on a "cancel" button. | |
84 | ||
85 | The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set | |
86 | and retrieve an opaque pointer. This can be used to set some application | |
87 | defined value which can be retrieved in the callback: for example a handle | |
88 | which is used to update a "progress dialog". | |
89 | ||
62924755 RL |
90 | =head1 RETURN VALUES |
91 | ||
92 | EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and | |
93 | EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. | |
94 | In particular a return value of -2 indicates the operation is not supported by | |
95 | the public key algorithm. | |
96 | ||
aa93b18c DSH |
97 | =head1 NOTES |
98 | ||
99 | After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm | |
100 | specific control operations can be performed to set any appropriate parameters | |
101 | for the operation. | |
102 | ||
103 | The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than | |
104 | once on the same context if several operations are performed using the same | |
105 | parameters. | |
106 | ||
107 | The meaning of the parameters passed to the callback will depend on the | |
186bb907 | 108 | algorithm and the specific implementation of the algorithm. Some might not |
aa93b18c DSH |
109 | give any useful information at all during key or parameter generation. Others |
110 | might not even call the callback. | |
111 | ||
112 | The operation performed by key or parameter generation depends on the algorithm | |
113 | used. In some cases (e.g. EC with a supplied named curve) the "generation" | |
114 | option merely sets the appropriate fields in an EVP_PKEY structure. | |
115 | ||
116 | In OpenSSL an EVP_PKEY structure containing a private key also contains the | |
117 | public key components and parameters (if any). An OpenSSL private key is | |
118 | equivalent to what some libraries call a "key pair". A private key can be used | |
119 | in functions which require the use of a public key or parameters. | |
120 | ||
aa93b18c DSH |
121 | =head1 EXAMPLES |
122 | ||
123 | Generate a 2048 bit RSA key: | |
124 | ||
125 | #include <openssl/evp.h> | |
126 | #include <openssl/rsa.h> | |
127 | ||
128 | EVP_PKEY_CTX *ctx; | |
129 | EVP_PKEY *pkey = NULL; | |
e9b77246 | 130 | |
aa93b18c DSH |
131 | ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); |
132 | if (!ctx) | |
2947af32 | 133 | /* Error occurred */ |
aa93b18c | 134 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 135 | /* Error */ |
aa93b18c | 136 | if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) |
2947af32 | 137 | /* Error */ |
aa93b18c DSH |
138 | |
139 | /* Generate key */ | |
140 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 141 | /* Error */ |
aa93b18c DSH |
142 | |
143 | Generate a key from a set of parameters: | |
144 | ||
145 | #include <openssl/evp.h> | |
146 | #include <openssl/rsa.h> | |
147 | ||
148 | EVP_PKEY_CTX *ctx; | |
9db6673e | 149 | ENGINE *eng; |
aa93b18c | 150 | EVP_PKEY *pkey = NULL, *param; |
e9b77246 | 151 | |
9db6673e JJ |
152 | /* Assumed param, eng are set up already */ |
153 | ctx = EVP_PKEY_CTX_new(param, eng); | |
aa93b18c | 154 | if (!ctx) |
2947af32 | 155 | /* Error occurred */ |
aa93b18c | 156 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 157 | /* Error */ |
aa93b18c DSH |
158 | |
159 | /* Generate key */ | |
160 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 161 | /* Error */ |
aa93b18c DSH |
162 | |
163 | Example of generation callback for OpenSSL public key implementations: | |
164 | ||
165 | /* Application data is a BIO to output status to */ | |
166 | ||
167 | EVP_PKEY_CTX_set_app_data(ctx, status_bio); | |
168 | ||
169 | static int genpkey_cb(EVP_PKEY_CTX *ctx) | |
2947af32 BB |
170 | { |
171 | char c = '*'; | |
172 | BIO *b = EVP_PKEY_CTX_get_app_data(ctx); | |
173 | int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); | |
e9b77246 | 174 | |
2947af32 BB |
175 | if (p == 0) |
176 | c = '.'; | |
177 | if (p == 1) | |
178 | c = '+'; | |
179 | if (p == 2) | |
180 | c = '*'; | |
181 | if (p == 3) | |
182 | c = '\n'; | |
183 | BIO_write(b, &c, 1); | |
184 | (void)BIO_flush(b); | |
185 | return 1; | |
186 | } | |
aa93b18c DSH |
187 | |
188 | =head1 SEE ALSO | |
189 | ||
9b86974e RS |
190 | L<EVP_PKEY_CTX_new(3)>, |
191 | L<EVP_PKEY_encrypt(3)>, | |
192 | L<EVP_PKEY_decrypt(3)>, | |
193 | L<EVP_PKEY_sign(3)>, | |
194 | L<EVP_PKEY_verify(3)>, | |
195 | L<EVP_PKEY_verify_recover(3)>, | |
1bc74519 | 196 | L<EVP_PKEY_derive(3)> |
aa93b18c DSH |
197 | |
198 | =head1 HISTORY | |
199 | ||
62924755 RL |
200 | EVP_PKEY_keygen_init(), int EVP_PKEY_paramgen_init(), EVP_PKEY_keygen(), |
201 | EVP_PKEY_paramgen(), EVP_PKEY_gen_cb(), EVP_PKEY_CTX_set_cb(), | |
202 | EVP_PKEY_CTX_get_cb(), EVP_PKEY_CTX_get_keygen_info(), | |
203 | EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() were added in | |
204 | OpenSSL 1.0.0. | |
205 | ||
206 | EVP_PKEY_gen() was added in OpenSSL 3.0. | |
aa93b18c | 207 | |
e2f92610 RS |
208 | =head1 COPYRIGHT |
209 | ||
62924755 | 210 | Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 211 | |
4746f25a | 212 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
213 | this file except in compliance with the License. You can obtain a copy |
214 | in the file LICENSE in the source distribution or at | |
215 | L<https://www.openssl.org/source/license.html>. | |
216 | ||
217 | =cut |