lib/libcrypto/man/EVP_PKEY_keygen.3

   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
 116 The
 117 .Fn EVP_PKEY_keygen_init
 118 function initializes a public key algorithm context using key
 119 .Fa ctx->pkey
 120 for a key generation operation.
 121 .Pp
 122 The
 123 .Fn EVP_PKEY_keygen
 124 function performs a key generation operation.
 125 The generated key is written to
 126 .Fa ppkey .
 127 .Pp
 128 The functions
 129 .Fn EVP_PKEY_paramgen_init
 130 and
 131 .Fn EVP_PKEY_paramgen
 132 are similar except parameters are generated.
 133 .Pp
 134 The function
 135 .Fn EVP_PKEY_CTX_set_cb
 136 sets the key or parameter generation callback to
 137 .Fa cb .
 138 The function
 139 .Fn EVP_PKEY_CTX_get_cb
 140 returns the key or parameter generation callback.
 141 .Pp
 142 The function
 143 .Fn EVP_PKEY_CTX_get_keygen_info
 144 returns parameters associated with the generation operation.
 145 If
 146 .Fa idx
 147 is -1, the total number of parameters available is returned.
 148 Any non-negative value returns the value of that parameter.
 149 .Fn EVP_PKEY_CTX_get_keygen_info
 150 with a non-negative value for
 151 .Fa idx
 152 should only be called within the generation callback.
 153 .Pp
 154 If the callback returns 0, then the key generation operation is aborted
 155 and an error occurs.
 156 This might occur during a time consuming operation where a user clicks
 157 on a "cancel" button.
 158 .Pp
 159 The functions
 160 .Fn EVP_PKEY_CTX_set_app_data
 161 and
 162 .Fn EVP_PKEY_CTX_get_app_data
 163 set and retrieve an opaque pointer.
 164 This can be used to set some application defined value which can be
 165 retrieved in the callback: for example a handle which is used to update
 166 a "progress dialog".
 167 .Pp
 168 After the call to
 169 .Fn EVP_PKEY_keygen_init
 170 or
 171 .Fn EVP_PKEY_paramgen_init ,
 172 algorithm specific control operations can be performed to set any
 173 appropriate parameters for the operation.
 174 .Pp
 175 The functions
 176 .Fn EVP_PKEY_keygen
 177 and
 178 .Fn EVP_PKEY_paramgen
 179 can be called more than once on the same context if several operations
 180 are performed using the same parameters.
 181 .Pp
 182 The meaning of the parameters passed to the callback will depend on the
 183 algorithm and the specific implementation of the algorithm.
 184 Some might not give any useful information at all during key or
 185 parameter generation.
 186 Others might not even call the callback.
 187 .Pp
 188 The operation performed by key or parameter generation depends on the
 189 algorithm used.
 190 In some cases (e.g. EC with a supplied named curve) the "generation"
 191 option merely sets the appropriate fields in an
 192 .Vt EVP_PKEY
 193 structure.
 194 .Pp
 195 In OpenSSL, an
 196 .Vt EVP_PKEY
 197 structure containing a private key also contains the public key
 198 components and parameters (if any).
 199 An OpenSSL private key is equivalent to what some libraries call a "key
 200 pair".
 201 A private key can be used in functions which require the use of a public
 202 key or parameters.
 203 .Sh RETURN VALUES
 204 .Fn EVP_PKEY_keygen_init ,
 205 .Fn EVP_PKEY_paramgen_init ,
 206 .Fn EVP_PKEY_keygen ,
 207 and
 208 .Fn EVP_PKEY_paramgen
 209 return 1 for success and 0 or a negative value for failure.
 210 In particular, a return value of -2 indicates the operation is not
 211 supported by the public key algorithm.
 212 .Sh EXAMPLES
 213 Generate a 2048-bit RSA key:
 214 .Bd -literal -offset indent
 215 #include <openssl/evp.h>
 216 #include <openssl/rsa.h>
 217
 218 EVP_PKEY_CTX *ctx;
 219 EVP_PKEY *pkey = NULL;
 220
 221 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
 222 if (!ctx)
 223         /* Error occurred */
 224 if (EVP_PKEY_keygen_init(ctx) <= 0)
 225         /* Error */
 226 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
 227         /* Error */
 228
 229 /* Generate key */
 230 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 231         /* Error */
 232 .Ed
 233 .Pp
 234 Generate a key from a set of parameters:
 235 .Bd -literal -offset indent
 236 #include <openssl/evp.h>
 237 #include <openssl/rsa.h>
 238
 239 EVP_PKEY_CTX *ctx;
 240 ENGINE *eng;
 241 EVP_PKEY *pkey = NULL, *param;
 242
 243 /* Assumes that param and eng are already set up. */
 244 ctx = EVP_PKEY_CTX_new(param, eng);
 245 if (!ctx)
 246         /* Error occurred */
 247 if (EVP_PKEY_keygen_init(ctx) <= 0)
 248         /* Error */
 249
 250 /* Generate key */
 251 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 252         /* Error */
 253 .Ed
 254 .Pp
 255 Example of generation callback for OpenSSL public key implementations:
 256 .Bd -literal -offset indent
 257 /* Application data is a BIO to output status to */
 258
 259 EVP_PKEY_CTX_set_app_data(ctx, status_bio);
 260
 261 static int
 262 genpkey_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
 293 These functions first appeared in OpenSSL 1.0.0
 294 and have been available since
 295 .Ox 4.9 .