]>
Commit | Line | Data |
---|---|---|
aa93b18c DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
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, | |
121677b4 | 8 | EVP_PKEY_CTX_get_app_data, |
b0004708 PY |
9 | EVP_PKEY_gen_cb, EVP_PKEY_check, EVP_PKEY_public_check, |
10 | EVP_PKEY_param_check | |
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); | |
18 | int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | |
19 | int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); | |
20 | int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | |
21 | ||
5bf6d418 | 22 | typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); |
aa93b18c DSH |
23 | |
24 | void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); | |
25 | EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); | |
26 | ||
27 | int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); | |
28 | ||
29 | void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); | |
30 | void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); | |
31 | ||
2aee35d3 | 32 | int EVP_PKEY_check(EVP_PKEY_CTX *ctx); |
b0004708 PY |
33 | int EVP_PKEY_public_check(EVP_PKEY_CTX *ctx); |
34 | int EVP_PKEY_param_check(EVP_PKEY_CTX *ctx); | |
2aee35d3 | 35 | |
aa93b18c DSH |
36 | =head1 DESCRIPTION |
37 | ||
38 | The EVP_PKEY_keygen_init() function initializes a public key algorithm | |
186bb907 | 39 | context using key B<pkey> for a key generation operation. |
aa93b18c | 40 | |
1bc74519 | 41 | The EVP_PKEY_keygen() function performs a key generation operation, the |
aa93b18c DSH |
42 | generated key is written to B<ppkey>. |
43 | ||
44 | The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar | |
45 | except parameters are generated. | |
46 | ||
47 | The function EVP_PKEY_set_cb() sets the key or parameter generation callback | |
48 | to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter | |
49 | generation callback. | |
50 | ||
51 | The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated | |
52 | with the generation operation. If B<idx> is -1 the total number of | |
53 | parameters available is returned. Any non negative value returns the value of | |
54 | that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for | |
55 | B<idx> should only be called within the generation callback. | |
56 | ||
186bb907 | 57 | If the callback returns 0 then the key generation operation is aborted and an |
aa93b18c DSH |
58 | error occurs. This might occur during a time consuming operation where |
59 | a user clicks on a "cancel" button. | |
60 | ||
61 | The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set | |
62 | and retrieve an opaque pointer. This can be used to set some application | |
63 | defined value which can be retrieved in the callback: for example a handle | |
64 | which is used to update a "progress dialog". | |
65 | ||
2aee35d3 PY |
66 | EVP_PKEY_check() validates the key-pair given by B<ctx>. This function first tries |
67 | to use customized key check method in B<EVP_PKEY_METHOD> if it's present; otherwise | |
68 | it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. | |
69 | ||
b0004708 PY |
70 | EVP_PKEY_public_check() validates the public component of the key-pair given by B<ctx>. |
71 | This function first tries to use customized key check method in B<EVP_PKEY_METHOD> | |
72 | if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. | |
73 | ||
74 | EVP_PKEY_param_check() validates the algorithm parameters of the key-pair given by B<ctx>. | |
75 | This function first tries to use customized key check method in B<EVP_PKEY_METHOD> | |
76 | if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>. | |
77 | ||
aa93b18c DSH |
78 | =head1 NOTES |
79 | ||
80 | After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm | |
81 | specific control operations can be performed to set any appropriate parameters | |
82 | for the operation. | |
83 | ||
84 | The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than | |
85 | once on the same context if several operations are performed using the same | |
86 | parameters. | |
87 | ||
88 | The meaning of the parameters passed to the callback will depend on the | |
186bb907 | 89 | algorithm and the specific implementation of the algorithm. Some might not |
aa93b18c DSH |
90 | give any useful information at all during key or parameter generation. Others |
91 | might not even call the callback. | |
92 | ||
93 | The operation performed by key or parameter generation depends on the algorithm | |
94 | used. In some cases (e.g. EC with a supplied named curve) the "generation" | |
95 | option merely sets the appropriate fields in an EVP_PKEY structure. | |
96 | ||
97 | In OpenSSL an EVP_PKEY structure containing a private key also contains the | |
98 | public key components and parameters (if any). An OpenSSL private key is | |
99 | equivalent to what some libraries call a "key pair". A private key can be used | |
100 | in functions which require the use of a public key or parameters. | |
101 | ||
102 | =head1 RETURN VALUES | |
103 | ||
104 | EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and | |
105 | EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. | |
106 | In particular a return value of -2 indicates the operation is not supported by | |
107 | the public key algorithm. | |
108 | ||
b0004708 PY |
109 | EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() return 1 |
110 | for success or others for failure. They return -2 if the operation is not supported | |
111 | for the specific algorithm. | |
2aee35d3 | 112 | |
aa93b18c DSH |
113 | =head1 EXAMPLES |
114 | ||
115 | Generate a 2048 bit RSA key: | |
116 | ||
117 | #include <openssl/evp.h> | |
118 | #include <openssl/rsa.h> | |
119 | ||
120 | EVP_PKEY_CTX *ctx; | |
121 | EVP_PKEY *pkey = NULL; | |
e9b77246 | 122 | |
aa93b18c DSH |
123 | ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); |
124 | if (!ctx) | |
2947af32 | 125 | /* Error occurred */ |
aa93b18c | 126 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 127 | /* Error */ |
aa93b18c | 128 | if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) |
2947af32 | 129 | /* Error */ |
aa93b18c DSH |
130 | |
131 | /* Generate key */ | |
132 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 133 | /* Error */ |
aa93b18c DSH |
134 | |
135 | Generate a key from a set of parameters: | |
136 | ||
137 | #include <openssl/evp.h> | |
138 | #include <openssl/rsa.h> | |
139 | ||
140 | EVP_PKEY_CTX *ctx; | |
9db6673e | 141 | ENGINE *eng; |
aa93b18c | 142 | EVP_PKEY *pkey = NULL, *param; |
e9b77246 | 143 | |
9db6673e JJ |
144 | /* Assumed param, eng are set up already */ |
145 | ctx = EVP_PKEY_CTX_new(param, eng); | |
aa93b18c | 146 | if (!ctx) |
2947af32 | 147 | /* Error occurred */ |
aa93b18c | 148 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 149 | /* Error */ |
aa93b18c DSH |
150 | |
151 | /* Generate key */ | |
152 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 153 | /* Error */ |
aa93b18c DSH |
154 | |
155 | Example of generation callback for OpenSSL public key implementations: | |
156 | ||
157 | /* Application data is a BIO to output status to */ | |
158 | ||
159 | EVP_PKEY_CTX_set_app_data(ctx, status_bio); | |
160 | ||
161 | static int genpkey_cb(EVP_PKEY_CTX *ctx) | |
2947af32 BB |
162 | { |
163 | char c = '*'; | |
164 | BIO *b = EVP_PKEY_CTX_get_app_data(ctx); | |
165 | int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); | |
e9b77246 | 166 | |
2947af32 BB |
167 | if (p == 0) |
168 | c = '.'; | |
169 | if (p == 1) | |
170 | c = '+'; | |
171 | if (p == 2) | |
172 | c = '*'; | |
173 | if (p == 3) | |
174 | c = '\n'; | |
175 | BIO_write(b, &c, 1); | |
176 | (void)BIO_flush(b); | |
177 | return 1; | |
178 | } | |
aa93b18c DSH |
179 | |
180 | =head1 SEE ALSO | |
181 | ||
9b86974e RS |
182 | L<EVP_PKEY_CTX_new(3)>, |
183 | L<EVP_PKEY_encrypt(3)>, | |
184 | L<EVP_PKEY_decrypt(3)>, | |
185 | L<EVP_PKEY_sign(3)>, | |
186 | L<EVP_PKEY_verify(3)>, | |
187 | L<EVP_PKEY_verify_recover(3)>, | |
1bc74519 | 188 | L<EVP_PKEY_derive(3)> |
aa93b18c DSH |
189 | |
190 | =head1 HISTORY | |
191 | ||
fc5ecadd | 192 | These functions were added in OpenSSL 1.0.0. |
aa93b18c | 193 | |
b0004708 PY |
194 | EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() were added |
195 | in OpenSSL 1.1.1. | |
196 | ||
e2f92610 RS |
197 | =head1 COPYRIGHT |
198 | ||
48e5119a | 199 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 200 | |
4746f25a | 201 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
202 | this file except in compliance with the License. You can obtain a copy |
203 | in the file LICENSE in the source distribution or at | |
204 | L<https://www.openssl.org/source/license.html>. | |
205 | ||
206 | =cut |