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 . 296