lib/libcrypto/man/EVP_PKEY_keygen.3

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