]>
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, |
12603de6 | 9 | EVP_PKEY_gen_cb |
2aee35d3 | 10 | - key and parameter generation and check functions |
aa93b18c DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/evp.h> | |
15 | ||
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); | |
20 | ||
5bf6d418 | 21 | typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); |
aa93b18c DSH |
22 | |
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); | |
25 | ||
26 | int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); | |
27 | ||
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); | |
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
33 | The EVP_PKEY_keygen_init() function initializes a public key algorithm | |
186bb907 | 34 | context using key B<pkey> for a key generation operation. |
aa93b18c | 35 | |
1bc74519 | 36 | The EVP_PKEY_keygen() function performs a key generation operation, the |
aa93b18c DSH |
37 | generated key is written to B<ppkey>. |
38 | ||
39 | The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar | |
40 | except parameters are generated. | |
41 | ||
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 | |
44 | generation callback. | |
45 | ||
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. | |
51 | ||
186bb907 | 52 | If the callback returns 0 then the key generation operation is aborted and an |
aa93b18c DSH |
53 | error occurs. This might occur during a time consuming operation where |
54 | a user clicks on a "cancel" button. | |
55 | ||
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". | |
60 | ||
61 | =head1 NOTES | |
62 | ||
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 | |
65 | for the operation. | |
66 | ||
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 | |
69 | parameters. | |
70 | ||
71 | The meaning of the parameters passed to the callback will depend on the | |
186bb907 | 72 | algorithm and the specific implementation of the algorithm. Some might not |
aa93b18c DSH |
73 | give any useful information at all during key or parameter generation. Others |
74 | might not even call the callback. | |
75 | ||
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. | |
79 | ||
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. | |
84 | ||
85 | =head1 RETURN VALUES | |
86 | ||
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. | |
91 | ||
92 | =head1 EXAMPLES | |
93 | ||
94 | Generate a 2048 bit RSA key: | |
95 | ||
96 | #include <openssl/evp.h> | |
97 | #include <openssl/rsa.h> | |
98 | ||
99 | EVP_PKEY_CTX *ctx; | |
100 | EVP_PKEY *pkey = NULL; | |
e9b77246 | 101 | |
aa93b18c DSH |
102 | ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); |
103 | if (!ctx) | |
2947af32 | 104 | /* Error occurred */ |
aa93b18c | 105 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 106 | /* Error */ |
aa93b18c | 107 | if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) |
2947af32 | 108 | /* Error */ |
aa93b18c DSH |
109 | |
110 | /* Generate key */ | |
111 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 112 | /* Error */ |
aa93b18c DSH |
113 | |
114 | Generate a key from a set of parameters: | |
115 | ||
116 | #include <openssl/evp.h> | |
117 | #include <openssl/rsa.h> | |
118 | ||
119 | EVP_PKEY_CTX *ctx; | |
9db6673e | 120 | ENGINE *eng; |
aa93b18c | 121 | EVP_PKEY *pkey = NULL, *param; |
e9b77246 | 122 | |
9db6673e JJ |
123 | /* Assumed param, eng are set up already */ |
124 | ctx = EVP_PKEY_CTX_new(param, eng); | |
aa93b18c | 125 | if (!ctx) |
2947af32 | 126 | /* Error occurred */ |
aa93b18c | 127 | if (EVP_PKEY_keygen_init(ctx) <= 0) |
2947af32 | 128 | /* Error */ |
aa93b18c DSH |
129 | |
130 | /* Generate key */ | |
131 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | |
2947af32 | 132 | /* Error */ |
aa93b18c DSH |
133 | |
134 | Example of generation callback for OpenSSL public key implementations: | |
135 | ||
136 | /* Application data is a BIO to output status to */ | |
137 | ||
138 | EVP_PKEY_CTX_set_app_data(ctx, status_bio); | |
139 | ||
140 | static int genpkey_cb(EVP_PKEY_CTX *ctx) | |
2947af32 BB |
141 | { |
142 | char c = '*'; | |
143 | BIO *b = EVP_PKEY_CTX_get_app_data(ctx); | |
144 | int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); | |
e9b77246 | 145 | |
2947af32 BB |
146 | if (p == 0) |
147 | c = '.'; | |
148 | if (p == 1) | |
149 | c = '+'; | |
150 | if (p == 2) | |
151 | c = '*'; | |
152 | if (p == 3) | |
153 | c = '\n'; | |
154 | BIO_write(b, &c, 1); | |
155 | (void)BIO_flush(b); | |
156 | return 1; | |
157 | } | |
aa93b18c DSH |
158 | |
159 | =head1 SEE ALSO | |
160 | ||
9b86974e RS |
161 | L<EVP_PKEY_CTX_new(3)>, |
162 | L<EVP_PKEY_encrypt(3)>, | |
163 | L<EVP_PKEY_decrypt(3)>, | |
164 | L<EVP_PKEY_sign(3)>, | |
165 | L<EVP_PKEY_verify(3)>, | |
166 | L<EVP_PKEY_verify_recover(3)>, | |
1bc74519 | 167 | L<EVP_PKEY_derive(3)> |
aa93b18c DSH |
168 | |
169 | =head1 HISTORY | |
170 | ||
fc5ecadd | 171 | These functions were added in OpenSSL 1.0.0. |
aa93b18c | 172 | |
e2f92610 RS |
173 | =head1 COPYRIGHT |
174 | ||
48e5119a | 175 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 176 | |
4746f25a | 177 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
178 | this file except in compliance with the License. You can obtain a copy |
179 | in the file LICENSE in the source distribution or at | |
180 | L<https://www.openssl.org/source/license.html>. | |
181 | ||
182 | =cut |