xref: /openbsd-src/lib/libcrypto/man/EVP_PKEY_keygen.3 (revision f1c41952defc4168d000b336cecabdeb1a7edc96) 
1.\" $OpenBSD: EVP_PKEY_keygen.3,v 1.15 2024/12/06 14:27:49 schwarze Exp $
2.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2023, 2024 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2006, 2009, 2013, 2015, 2016, 2018 The OpenSSL Project.
23.\" All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\"    notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\"    notice, this list of conditions and the following disclaimer in
34.\"    the documentation and/or other materials provided with the
35.\"    distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\"    software must display the following acknowledgment:
39.\"    "This product includes software developed by the OpenSSL Project
40.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\"    endorse or promote products derived from this software without
44.\"    prior written permission. For written permission, please contact
45.\"    openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\"    nor may "OpenSSL" appear in their names without prior written
49.\"    permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\"    acknowledgment:
53.\"    "This product includes software developed by the OpenSSL Project
54.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: December 6 2024 $
70.Dt EVP_PKEY_KEYGEN 3
71.Os
72.Sh NAME
73.Nm EVP_PKEY_keygen_init ,
74.Nm EVP_PKEY_keygen ,
75.Nm EVP_PKEY_paramgen_init ,
76.Nm EVP_PKEY_paramgen ,
77.Nm EVP_PKEY_gen_cb ,
78.Nm EVP_PKEY_CTX_set_cb ,
79.Nm EVP_PKEY_CTX_get_cb ,
80.Nm EVP_PKEY_CTX_set0_keygen_info ,
81.Nm EVP_PKEY_CTX_get_keygen_info ,
82.Nm EVP_PKEY_CTX_set_app_data ,
83.Nm EVP_PKEY_CTX_get_app_data ,
84.Nm EVP_PKEY_CTX_set_data ,
85.Nm EVP_PKEY_CTX_get_data
86.Nd key and parameter generation functions
87.Sh SYNOPSIS
88.In openssl/evp.h
89.Ft int
90.Fo EVP_PKEY_keygen_init
91.Fa "EVP_PKEY_CTX *ctx"
92.Fc
93.Ft int
94.Fo EVP_PKEY_keygen
95.Fa "EVP_PKEY_CTX *ctx"
96.Fa "EVP_PKEY **ppkey"
97.Fc
98.Ft int
99.Fo EVP_PKEY_paramgen_init
100.Fa "EVP_PKEY_CTX *ctx"
101.Fc
102.Ft int
103.Fo EVP_PKEY_paramgen
104.Fa "EVP_PKEY_CTX *ctx"
105.Fa "EVP_PKEY **ppkey"
106.Fc
107.Ft typedef int
108.Fo EVP_PKEY_gen_cb
109.Fa "EVP_PKEY_CTX *ctx"
110.Fc
111.Ft void
112.Fo EVP_PKEY_CTX_set_cb
113.Fa "EVP_PKEY_CTX *ctx"
114.Fa "EVP_PKEY_gen_cb *cb"
115.Fc
116.Ft EVP_PKEY_gen_cb *
117.Fo EVP_PKEY_CTX_get_cb
118.Fa "EVP_PKEY_CTX *ctx"
119.Fc
120.Ft void
121.Fo EVP_PKEY_CTX_set0_keygen_info
122.Fa "EVP_PKEY_CTX *ctx"
123.Fa "int *dat"
124.Fa "int datlen"
125.Fc
126.Ft int
127.Fo EVP_PKEY_CTX_get_keygen_info
128.Fa "EVP_PKEY_CTX *ctx"
129.Fa "int idx"
130.Fc
131.Ft void
132.Fo EVP_PKEY_CTX_set_app_data
133.Fa "EVP_PKEY_CTX *ctx"
134.Fa "void *app_data"
135.Fc
136.Ft void *
137.Fo EVP_PKEY_CTX_get_app_data
138.Fa "EVP_PKEY_CTX *ctx"
139.Fc
140.Ft void
141.Fo EVP_PKEY_CTX_set_data
142.Fa "EVP_PKEY_CTX *ctx"
143.Fa "void *data"
144.Fc
145.Ft void *
146.Fo EVP_PKEY_CTX_get_data
147.Fa "EVP_PKEY_CTX *ctx"
148.Fc
149.Sh DESCRIPTION
150The
151.Fn EVP_PKEY_keygen_init
152function initializes a public key algorithm context using key
153.Fa ctx->pkey
154for a key generation operation.
155.Pp
156The
157.Fn EVP_PKEY_keygen
158function performs a key generation operation.
159The generated key is written to
160.Fa ppkey .
161.Pp
162The functions
163.Fn EVP_PKEY_paramgen_init
164and
165.Fn EVP_PKEY_paramgen
166are similar except parameters are generated.
167.Pp
168The functions
169.Fn EVP_PKEY_CTX_set_cb
170and
171.Fn EVP_PKEY_CTX_get_cb
172set and retrieve the key or parameter generation callback, respectively.
173.Pp
174The function
175.Fn EVP_PKEY_CTX_set0_keygen_info
176sets the parameters associated with the generation operation to the array
177.Fa dat
178containing
179.Ft datlen
180integer parameters.
181The caller retains ownership of the
182.Fa dat
183array; it will never be freed by the library.
184.Pp
185The function
186.Fn EVP_PKEY_CTX_get_keygen_info
187returns parameters associated with the generation operation.
188If
189.Fa idx
190is -1, the total number of parameters available is returned.
191Any non-negative value returns the value of that parameter.
192.Fn EVP_PKEY_CTX_get_keygen_info
193with a non-negative value for
194.Fa idx
195should only be called within the generation callback.
196.Pp
197If the callback returns 0, then the key generation operation is aborted
198and an error occurs.
199This might occur during a time consuming operation where a user clicks
200on a "cancel" button.
201.Pp
202The functions
203.Fn EVP_PKEY_CTX_set_app_data
204and
205.Fn EVP_PKEY_CTX_get_app_data
206set and retrieve an opaque pointer.
207This can be used to set some application defined value which can be
208retrieved in the callback: for example a handle which is used to update
209a "progress dialog".
210.Pp
211The deprecated functions
212.Fn EVP_PKEY_CTX_set_data
213and
214.Fn EVP_PKEY_CTX_get_data
215set and retrieve a
216.Em different
217opaque pointer that is ignored by the library.
218.Pp
219After the call to
220.Fn EVP_PKEY_keygen_init
221or
222.Fn EVP_PKEY_paramgen_init ,
223algorithm specific control operations can be performed to set any
224appropriate parameters for the operation.
225.Pp
226The functions
227.Fn EVP_PKEY_keygen
228and
229.Fn EVP_PKEY_paramgen
230can be called more than once on the same context if several operations
231are performed using the same parameters.
232.Pp
233The meaning of the parameters passed to the callback will depend on the
234algorithm and the specific implementation of the algorithm.
235Some might not give any useful information at all during key or
236parameter generation.
237Others might not even call the callback.
238.Pp
239The operation performed by key or parameter generation depends on the
240algorithm used.
241In some cases (e.g. EC with a supplied named curve) the "generation"
242option merely sets the appropriate fields in an
243.Vt EVP_PKEY
244structure.
245.Pp
246In OpenSSL, an
247.Vt EVP_PKEY
248structure containing a private key also contains the public key
249components and parameters (if any).
250An OpenSSL private key is equivalent to what some libraries call a "key
251pair".
252A private key can be used in functions which require the use of a public
253key or parameters.
254.Sh RETURN VALUES
255.Fn EVP_PKEY_keygen_init ,
256.Fn EVP_PKEY_paramgen_init ,
257.Fn EVP_PKEY_keygen ,
258and
259.Fn EVP_PKEY_paramgen
260return 1 for success and 0 or a negative value for failure.
261In particular, a return value of -2 indicates the operation is not
262supported by the public key algorithm.
263.Pp
264Callback functions of the type
265.Fn EVP_PKEY_gen_cb
266are supposed to return 1 on success or 0 on error.
267.Pp
268.Fn EVP_PKEY_CTX_get_cb
269returns a function pointer to the currently installed callback function or
270.Dv NULL
271if no callback function is installed.
272.Pp
273.Fn EVP_PKEY_CTX_get_keygen_info
274returns the number of available parameters if
275.Fa idx
276is \-1, one of these parameters if
277.Fa idx
278is greater than or equal to zero but less than the number
279of available parameters, or 0 otherwise.
280.Pp
281.Fn EVP_PKEY_CTX_get_app_data
282and
283.Fn EVP_PKEY_CTX_get_data
284return the pointer that was last passed to the corresponding set function, or
285.Dv NULL
286if the corresponding set function was never called on
287.Fa ctx .
288.Sh EXAMPLES
289Generate a 2048-bit RSA key:
290.Bd -literal -offset indent
291#include <openssl/evp.h>
292#include <openssl/rsa.h>
293
294EVP_PKEY_CTX *ctx;
295EVP_PKEY *pkey = NULL;
296
297ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
298if (!ctx)
299	/* Error occurred */
300if (EVP_PKEY_keygen_init(ctx) <= 0)
301	/* Error */
302if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
303	/* Error */
304
305/* Generate key */
306if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
307	/* Error */
308.Ed
309.Pp
310Generate a key from a set of parameters:
311.Bd -literal -offset indent
312#include <openssl/evp.h>
313#include <openssl/rsa.h>
314
315EVP_PKEY_CTX *ctx;
316EVP_PKEY *pkey = NULL, *param;
317
318/* Assumes that param is already set up. */
319ctx = EVP_PKEY_CTX_new(param, NULL);
320if (!ctx)
321	/* Error occurred */
322if (EVP_PKEY_keygen_init(ctx) <= 0)
323	/* Error */
324
325/* Generate key */
326if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
327	/* Error */
328.Ed
329.Pp
330Example of generation callback for OpenSSL public key implementations:
331.Bd -literal -offset indent
332/* Application data is a BIO to output status to */
333
334EVP_PKEY_CTX_set_app_data(ctx, status_bio);
335
336static int
337genpkey_cb(EVP_PKEY_CTX *ctx)
338{
339	char c = '*';
340	BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
341	int p;
342
343	p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
344	if (p == 0)
345		c = '.';
346	if (p == 1)
347		c = '+';
348	if (p == 2)
349		c = '*';
350	if (p == 3)
351		c = '\en';
352	BIO_write(b, &c, 1);
353	(void)BIO_flush(b);
354	return 1;
355}
356.Ed
357.Sh SEE ALSO
358.Xr EVP_PKEY_CTX_new 3 ,
359.Xr EVP_PKEY_decrypt 3 ,
360.Xr EVP_PKEY_derive 3 ,
361.Xr EVP_PKEY_encrypt 3 ,
362.Xr EVP_PKEY_sign 3 ,
363.Xr EVP_PKEY_verify 3 ,
364.Xr EVP_PKEY_verify_recover 3 ,
365.Xr X25519 3
366.Sh HISTORY
367These functions first appeared in OpenSSL 1.0.0
368and have been available since
369.Ox 4.9 .
370