summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_PKEY_keygen.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EVP_PKEY_keygen.3')
-rw-r--r--src/lib/libcrypto/man/EVP_PKEY_keygen.3295
1 files changed, 0 insertions, 295 deletions
diff --git a/src/lib/libcrypto/man/EVP_PKEY_keygen.3 b/src/lib/libcrypto/man/EVP_PKEY_keygen.3
deleted file mode 100644
index 6173a1c438..0000000000
--- a/src/lib/libcrypto/man/EVP_PKEY_keygen.3
+++ /dev/null
@@ -1,295 +0,0 @@
1.\" $OpenBSD: EVP_PKEY_keygen.3,v 1.9 2018/03/23 04:34:23 schwarze Exp $
2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
3.\" selective merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100
4.\"
5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6.\" Copyright (c) 2006, 2009, 2013, 2015, 2016, 2018 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\" notice, this list of conditions and the following disclaimer in
18.\" the documentation and/or other materials provided with the
19.\" distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\" software must display the following acknowledgment:
23.\" "This product includes software developed by the OpenSSL Project
24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\" endorse or promote products derived from this software without
28.\" prior written permission. For written permission, please contact
29.\" openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\" nor may "OpenSSL" appear in their names without prior written
33.\" permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\" acknowledgment:
37.\" "This product includes software developed by the OpenSSL Project
38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: March 23 2018 $
54.Dt EVP_PKEY_KEYGEN 3
55.Os
56.Sh NAME
57.Nm EVP_PKEY_keygen_init ,
58.Nm EVP_PKEY_keygen ,
59.Nm EVP_PKEY_paramgen_init ,
60.Nm EVP_PKEY_paramgen ,
61.Nm EVP_PKEY_gen_cb ,
62.Nm EVP_PKEY_CTX_set_cb ,
63.Nm EVP_PKEY_CTX_get_cb ,
64.Nm EVP_PKEY_CTX_get_keygen_info ,
65.Nm EVP_PKEY_CTX_set_app_data ,
66.Nm EVP_PKEY_CTX_get_app_data
67.Nd key and parameter generation functions
68.Sh SYNOPSIS
69.In openssl/evp.h
70.Ft int
71.Fo EVP_PKEY_keygen_init
72.Fa "EVP_PKEY_CTX *ctx"
73.Fc
74.Ft int
75.Fo EVP_PKEY_keygen
76.Fa "EVP_PKEY_CTX *ctx"
77.Fa "EVP_PKEY **ppkey"
78.Fc
79.Ft int
80.Fo EVP_PKEY_paramgen_init
81.Fa "EVP_PKEY_CTX *ctx"
82.Fc
83.Ft int
84.Fo EVP_PKEY_paramgen
85.Fa "EVP_PKEY_CTX *ctx"
86.Fa "EVP_PKEY **ppkey"
87.Fc
88.Ft typedef int
89.Fo EVP_PKEY_gen_cb
90.Fa "EVP_PKEY_CTX *ctx"
91.Fc
92.Ft void
93.Fo EVP_PKEY_CTX_set_cb
94.Fa "EVP_PKEY_CTX *ctx"
95.Fa "EVP_PKEY_gen_cb *cb"
96.Fc
97.Ft EVP_PKEY_gen_cb *
98.Fo EVP_PKEY_CTX_get_cb
99.Fa "EVP_PKEY_CTX *ctx"
100.Fc
101.Ft int
102.Fo EVP_PKEY_CTX_get_keygen_info
103.Fa "EVP_PKEY_CTX *ctx"
104.Fa "int idx"
105.Fc
106.Ft void
107.Fo EVP_PKEY_CTX_set_app_data
108.Fa "EVP_PKEY_CTX *ctx"
109.Fa "void *data"
110.Fc
111.Ft void *
112.Fo EVP_PKEY_CTX_get_app_data
113.Fa "EVP_PKEY_CTX *ctx"
114.Fc
115.Sh DESCRIPTION
116The
117.Fn EVP_PKEY_keygen_init
118function initializes a public key algorithm context using key
119.Fa ctx->pkey
120for a key generation operation.
121.Pp
122The
123.Fn EVP_PKEY_keygen
124function performs a key generation operation.
125The generated key is written to
126.Fa ppkey .
127.Pp
128The functions
129.Fn EVP_PKEY_paramgen_init
130and
131.Fn EVP_PKEY_paramgen
132are similar except parameters are generated.
133.Pp
134The function
135.Fn EVP_PKEY_CTX_set_cb
136sets the key or parameter generation callback to
137.Fa cb .
138The function
139.Fn EVP_PKEY_CTX_get_cb
140returns the key or parameter generation callback.
141.Pp
142The function
143.Fn EVP_PKEY_CTX_get_keygen_info
144returns parameters associated with the generation operation.
145If
146.Fa idx
147is -1, the total number of parameters available is returned.
148Any non-negative value returns the value of that parameter.
149.Fn EVP_PKEY_CTX_get_keygen_info
150with a non-negative value for
151.Fa idx
152should only be called within the generation callback.
153.Pp
154If the callback returns 0, then the key generation operation is aborted
155and an error occurs.
156This might occur during a time consuming operation where a user clicks
157on a "cancel" button.
158.Pp
159The functions
160.Fn EVP_PKEY_CTX_set_app_data
161and
162.Fn EVP_PKEY_CTX_get_app_data
163set and retrieve an opaque pointer.
164This can be used to set some application defined value which can be
165retrieved in the callback: for example a handle which is used to update
166a "progress dialog".
167.Pp
168After the call to
169.Fn EVP_PKEY_keygen_init
170or
171.Fn EVP_PKEY_paramgen_init ,
172algorithm specific control operations can be performed to set any
173appropriate parameters for the operation.
174.Pp
175The functions
176.Fn EVP_PKEY_keygen
177and
178.Fn EVP_PKEY_paramgen
179can be called more than once on the same context if several operations
180are performed using the same parameters.
181.Pp
182The meaning of the parameters passed to the callback will depend on the
183algorithm and the specific implementation of the algorithm.
184Some might not give any useful information at all during key or
185parameter generation.
186Others might not even call the callback.
187.Pp
188The operation performed by key or parameter generation depends on the
189algorithm used.
190In some cases (e.g. EC with a supplied named curve) the "generation"
191option merely sets the appropriate fields in an
192.Vt EVP_PKEY
193structure.
194.Pp
195In OpenSSL, an
196.Vt EVP_PKEY
197structure containing a private key also contains the public key
198components and parameters (if any).
199An OpenSSL private key is equivalent to what some libraries call a "key
200pair".
201A private key can be used in functions which require the use of a public
202key or parameters.
203.Sh RETURN VALUES
204.Fn EVP_PKEY_keygen_init ,
205.Fn EVP_PKEY_paramgen_init ,
206.Fn EVP_PKEY_keygen ,
207and
208.Fn EVP_PKEY_paramgen
209return 1 for success and 0 or a negative value for failure.
210In particular, a return value of -2 indicates the operation is not
211supported by the public key algorithm.
212.Sh EXAMPLES
213Generate a 2048-bit RSA key:
214.Bd -literal -offset indent
215#include <openssl/evp.h>
216#include <openssl/rsa.h>
217
218EVP_PKEY_CTX *ctx;
219EVP_PKEY *pkey = NULL;
220
221ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
222if (!ctx)
223 /* Error occurred */
224if (EVP_PKEY_keygen_init(ctx) <= 0)
225 /* Error */
226if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
227 /* Error */
228
229/* Generate key */
230if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
231 /* Error */
232.Ed
233.Pp
234Generate a key from a set of parameters:
235.Bd -literal -offset indent
236#include <openssl/evp.h>
237#include <openssl/rsa.h>
238
239EVP_PKEY_CTX *ctx;
240ENGINE *eng;
241EVP_PKEY *pkey = NULL, *param;
242
243/* Assumes that param and eng are already set up. */
244ctx = EVP_PKEY_CTX_new(param, eng);
245if (!ctx)
246 /* Error occurred */
247if (EVP_PKEY_keygen_init(ctx) <= 0)
248 /* Error */
249
250/* Generate key */
251if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
252 /* Error */
253.Ed
254.Pp
255Example of generation callback for OpenSSL public key implementations:
256.Bd -literal -offset indent
257/* Application data is a BIO to output status to */
258
259EVP_PKEY_CTX_set_app_data(ctx, status_bio);
260
261static int
262genpkey_cb(EVP_PKEY_CTX *ctx)
263{
264 char c = '*';
265 BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
266 int p;
267
268 p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
269 if (p == 0)
270 c = '.';
271 if (p == 1)
272 c = '+';
273 if (p == 2)
274 c = '*';
275 if (p == 3)
276 c = '\en';
277 BIO_write(b, &c, 1);
278 (void)BIO_flush(b);
279 return 1;
280}
281.Ed
282.Sh SEE ALSO
283.Xr EVP_PKEY_CTX_new 3 ,
284.Xr EVP_PKEY_decrypt 3 ,
285.Xr EVP_PKEY_derive 3 ,
286.Xr EVP_PKEY_encrypt 3 ,
287.Xr EVP_PKEY_meth_set_keygen 3 ,
288.Xr EVP_PKEY_sign 3 ,
289.Xr EVP_PKEY_verify 3 ,
290.Xr EVP_PKEY_verify_recover 3 ,
291.Xr X25519 3
292.Sh HISTORY
293These functions first appeared in OpenSSL 1.0.0
294and have been available since
295.Ox 4.9 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 20:49:10 +0000