.\"	$OpenBSD: EVP_PKEY_keygen.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
.\"
.Dd $Mdocdate: November 6 2016 $
.Dt EVP_PKEY_KEYGEN 3
.Os
.Sh NAME
.Nm EVP_PKEY_keygen_init ,
.Nm EVP_PKEY_keygen ,
.Nm EVP_PKEY_paramgen_init ,
.Nm EVP_PKEY_paramgen ,
.Nm EVP_PKEY_CTX_set_cb ,
.Nm EVP_PKEY_CTX_get_cb ,
.Nm EVP_PKEY_CTX_get_keygen_info ,
.Nm EVP_PKEY_CTX_set_app_data ,
.Nm EVP_PKEY_CTX_get_app_data
.Nd key and parameter generation functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft int
.Fo EVP_PKEY_keygen_init
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_keygen
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY **ppkey"
.Fc
.Ft int
.Fo EVP_PKEY_paramgen_init
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_paramgen
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY **ppkey"
.Fc
.Ft typedef int
.Fo EVP_PKEY_gen_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft void
.Fo EVP_PKEY_CTX_set_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fa "EVP_PKEY_gen_cb *cb"
.Fc
.Ft EVP_PKEY_gen_cb *
.Fo EVP_PKEY_CTX_get_cb
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Ft int
.Fo EVP_PKEY_CTX_get_keygen_info
.Fa "EVP_PKEY_CTX *ctx"
.Fa "int idx"
.Fc
.Ft void
.Fo EVP_PKEY_CTX_set_app_data
.Fa "EVP_PKEY_CTX *ctx"
.Fa "void *data"
.Fc
.Ft void *
.Fo EVP_PKEY_CTX_get_app_data
.Fa "EVP_PKEY_CTX *ctx"
.Fc
.Sh DESCRIPTION
The
.Fn EVP_PKEY_keygen_init
function initializes a public key algorithm context using key
.Fa ctx->pkey
for a key generation operation.
.Pp
The
.Fn EVP_PKEY_keygen
function performs a key generation operation, the generated key is
written to
.Fa ppkey .
.Pp
The functions
.Fn EVP_PKEY_paramgen_init
and
.Fn EVP_PKEY_paramgen
are similar except parameters are generated.
.Pp
The function
.Fn EVP_PKEY_CTX_set_cb
sets the key or parameter generation callback to
.Fa cb .
The function
.Fn EVP_PKEY_CTX_get_cb
returns the key or parameter generation callback.
.Pp
The function
.Fn EVP_PKEY_CTX_get_keygen_info
returns parameters associated with the generation operation.
If
.Fa idx
is -1, the total number of parameters available is returned.
Any non negative value returns the value of that parameter.
.Fn EVP_PKEY_CTX_get_keygen_info
with a non-negative value for
.Fa idx
should only be called within the generation callback.
.Pp
If the callback returns 0, then the key generation operation is aborted
and an error occurs.
This might occur during a time consuming operation where a user clicks
on a "cancel" button.
.Pp
The functions
.Fn EVP_PKEY_CTX_set_app_data
and
.Fn EVP_PKEY_CTX_get_app_data
set and retrieve an opaque pointer.
This can be used to set some application defined value which can be
retrieved in the callback: for example a handle which is used to update
a "progress dialog".
.Pp
After the call to
.Fn EVP_PKEY_keygen_init
or
.Fn EVP_PKEY_paramgen_init ,
algorithm specific control operations can be performed to set any
appropriate parameters for the operation.
.Pp
The functions
.Fn EVP_PKEY_keygen
and
.Fn EVP_PKEY_paramgen
can be called more than once on the same context if several operations
are performed using the same parameters.
.Pp
The meaning of the parameters passed to the callback will depend on the
algorithm and the specific implementation of the algorithm.
Some might not give any useful information at all during key or
parameter generation.
Others might not even call the callback.
.Pp
The operation performed by key or parameter generation depends on the
algorithm used.
In some cases (e.g. EC with a supplied named curve) the "generation"
option merely sets the appropriate fields in an
.Vt EVP_PKEY
structure.
.Pp
In OpenSSL, an
.Vt EVP_PKEY
structure containing a private key also contains the public key
components and parameters (if any).
An OpenSSL private key is equivalent to what some libraries call a "key
pair".
A private key can be used in functions which require the use of a public
key or parameters.
.Sh RETURN VALUES
.Fn EVP_PKEY_keygen_init ,
.Fn EVP_PKEY_paramgen_init ,
.Fn EVP_PKEY_keygen ,
and
.Fn EVP_PKEY_paramgen
return 1 for success and 0 or a negative value for failure.
In particular, a return value of -2 indicates the operation is not
supported by the public key algorithm.
.Sh EXAMPLES
Generate a 2048 bit RSA key:
.Bd -literal
#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
EVP_PKEY *pkey = NULL;
ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
if (!ctx)
	/* Error occurred */
if (EVP_PKEY_keygen_init(ctx) <= 0)
	/* Error */
if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
	/* Error */

/* Generate key */
if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
	/* Error */
.Ed
.Pp
Generate a key from a set of parameters:
.Bd -literal
#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
EVP_PKEY *pkey = NULL, *param;
/* Assumed param is set up already */
ctx = EVP_PKEY_CTX_new(param);
if (!ctx)
	/* Error occurred */
if (EVP_PKEY_keygen_init(ctx) <= 0)
	/* Error */

/* Generate key */
if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
	/* Error */
.Ed
.Pp
Example of generation callback for OpenSSL public key implementations:
.Bd -literal
/* Application data is a BIO to output status to */

EVP_PKEY_CTX_set_app_data(ctx, status_bio);

static int
genpkey_cb(EVP_PKEY_CTX *ctx)
{
	char c = '*';
	BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
	int p;

	p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
	if (p == 0)
		c='.';
	if (p == 1)
		c='+';
	if (p == 2)
		c='*';
	if (p == 3)
		c='\en';
	BIO_write(b,&c,1);
	(void)BIO_flush(b);
	return 1;
}
.Ed
.Sh SEE ALSO
.Xr EVP_PKEY_CTX_new 3 ,
.Xr EVP_PKEY_decrypt 3 ,
.Xr EVP_PKEY_derive 3 ,
.Xr EVP_PKEY_encrypt 3 ,
.Xr EVP_PKEY_sign 3 ,
.Xr EVP_PKEY_verify 3 ,
.Xr EVP_PKEY_verify_recover 3
.Sh HISTORY
These functions were first added to OpenSSL 1.0.0.