doc/man3/EVP_PKEY_keygen.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
   6 EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
   7 EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
   8 EVP_PKEY_CTX_get_app_data,
   9 EVP_PKEY_gen_cb
  10 - key and parameter generation functions
  11
  12 =head1 SYNOPSIS
  13
  14  #include <openssl/evp.h>
  15
  16  int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
  17  int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
  18  int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
  19  int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
  20
  21  typedef int (*EVP_PKEY_gen_cb)(EVP_PKEY_CTX *ctx);
  22
  23  void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
  24  EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
  25
  26  int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
  27
  28  void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
  29  void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
  30
  31 =head1 DESCRIPTION
  32
  33 The EVP_PKEY_keygen_init() function initializes a public key algorithm
  34 context using key B<pkey> for a key generation operation.
  35
  36 The EVP_PKEY_keygen() function performs a key generation operation, the
  37 generated key is written to B<ppkey>.
  38
  39 The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
  40 except parameters are generated.
  41
  42 The function EVP_PKEY_set_cb() sets the key or parameter generation callback
  43 to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
  44 generation callback.
  45
  46 The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
  47 with the generation operation. If B<idx> is -1 the total number of
  48 parameters available is returned. Any non negative value returns the value of
  49 that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
  50 B<idx> should only be called within the generation callback.
  51
  52 If the callback returns 0 then the key generation operation is aborted and an
  53 error occurs. This might occur during a time consuming operation where
  54 a user clicks on a "cancel" button.
  55
  56 The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
  57 and retrieve an opaque pointer. This can be used to set some application
  58 defined value which can be retrieved in the callback: for example a handle
  59 which is used to update a "progress dialog".
  60
  61 =head1 NOTES
  62
  63 After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
  64 specific control operations can be performed to set any appropriate parameters
  65 for the operation.
  66
  67 The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
  68 once on the same context if several operations are performed using the same
  69 parameters.
  70
  71 The meaning of the parameters passed to the callback will depend on the
  72 algorithm and the specific implementation of the algorithm. Some might not
  73 give any useful information at all during key or parameter generation. Others
  74 might not even call the callback.
  75
  76 The operation performed by key or parameter generation depends on the algorithm
  77 used. In some cases (e.g. EC with a supplied named curve) the "generation"
  78 option merely sets the appropriate fields in an EVP_PKEY structure.
  79
  80 In OpenSSL an EVP_PKEY structure containing a private key also contains the
  81 public key components and parameters (if any). An OpenSSL private key is
  82 equivalent to what some libraries call a "key pair". A private key can be used
  83 in functions which require the use of a public key or parameters.
  84
  85 =head1 RETURN VALUES
  86
  87 EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
  88 EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
  89 In particular a return value of -2 indicates the operation is not supported by
  90 the public key algorithm.
  91
  92 =head1 EXAMPLES
  93
  94 Generate a 2048 bit RSA key:
  95
  96  #include <openssl/evp.h>
  97  #include <openssl/rsa.h>
  98
  99  EVP_PKEY_CTX *ctx;
 100  EVP_PKEY *pkey = NULL;
 101
 102  ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
 103  if (!ctx)
 104      /* Error occurred */
 105  if (EVP_PKEY_keygen_init(ctx) <= 0)
 106      /* Error */
 107  if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
 108      /* Error */
 109
 110  /* Generate key */
 111  if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 112      /* Error */
 113
 114 Generate a key from a set of parameters:
 115
 116  #include <openssl/evp.h>
 117  #include <openssl/rsa.h>
 118
 119  EVP_PKEY_CTX *ctx;
 120  EVP_PKEY *pkey = NULL, *param;
 121
 122  /* Assumed param is set up already */
 123  ctx = EVP_PKEY_CTX_new(param);
 124  if (!ctx)
 125      /* Error occurred */
 126  if (EVP_PKEY_keygen_init(ctx) <= 0)
 127      /* Error */
 128
 129  /* Generate key */
 130  if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 131      /* Error */
 132
 133 Example of generation callback for OpenSSL public key implementations:
 134
 135  /* Application data is a BIO to output status to */
 136
 137  EVP_PKEY_CTX_set_app_data(ctx, status_bio);
 138
 139  static int genpkey_cb(EVP_PKEY_CTX *ctx)
 140  {
 141      char c = '*';
 142      BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
 143      int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
 144
 145      if (p == 0)
 146          c = '.';
 147      if (p == 1)
 148          c = '+';
 149      if (p == 2)
 150          c = '*';
 151      if (p == 3)
 152          c = '\n';
 153      BIO_write(b, &c, 1);
 154      (void)BIO_flush(b);
 155      return 1;
 156  }
 157
 158 =head1 SEE ALSO
 159
 160 L<EVP_PKEY_CTX_new(3)>,
 161 L<EVP_PKEY_encrypt(3)>,
 162 L<EVP_PKEY_decrypt(3)>,
 163 L<EVP_PKEY_sign(3)>,
 164 L<EVP_PKEY_verify(3)>,
 165 L<EVP_PKEY_verify_recover(3)>,
 166 L<EVP_PKEY_derive(3)>
 167
 168 =head1 HISTORY
 169
 170 These functions were first added to OpenSSL 1.0.0.
 171
 172 =head1 COPYRIGHT
 173
 174 Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
 175
 176 Licensed under the OpenSSL license (the "License").  You may not use
 177 this file except in compliance with the License.  You can obtain a copy
 178 in the file LICENSE in the source distribution or at
 179 L<https://www.openssl.org/source/license.html>.
 180
 181 =cut