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 and check 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  ENGINE *eng;
 121  EVP_PKEY *pkey = NULL, *param;
 122
 123  /* Assumed param, eng are set up already */
 124  ctx = EVP_PKEY_CTX_new(param, eng);
 125  if (!ctx)
 126      /* Error occurred */
 127  if (EVP_PKEY_keygen_init(ctx) <= 0)
 128      /* Error */
 129
 130  /* Generate key */
 131  if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 132      /* Error */
 133
 134 Example of generation callback for OpenSSL public key implementations:
 135
 136  /* Application data is a BIO to output status to */
 137
 138  EVP_PKEY_CTX_set_app_data(ctx, status_bio);
 139
 140  static int genpkey_cb(EVP_PKEY_CTX *ctx)
 141  {
 142      char c = '*';
 143      BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
 144      int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
 145
 146      if (p == 0)
 147          c = '.';
 148      if (p == 1)
 149          c = '+';
 150      if (p == 2)
 151          c = '*';
 152      if (p == 3)
 153          c = '\n';
 154      BIO_write(b, &c, 1);
 155      (void)BIO_flush(b);
 156      return 1;
 157  }
 158
 159 =head1 SEE ALSO
 160
 161 L<EVP_PKEY_CTX_new(3)>,
 162 L<EVP_PKEY_encrypt(3)>,
 163 L<EVP_PKEY_decrypt(3)>,
 164 L<EVP_PKEY_sign(3)>,
 165 L<EVP_PKEY_verify(3)>,
 166 L<EVP_PKEY_verify_recover(3)>,
 167 L<EVP_PKEY_derive(3)>
 168
 169 =head1 HISTORY
 170
 171 These functions were added in OpenSSL 1.0.0.
 172
 173 =head1 COPYRIGHT
 174
 175 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 176
 177 Licensed under the Apache License 2.0 (the "License").  You may not use
 178 this file except in compliance with the License.  You can obtain a copy
 179 in the file LICENSE in the source distribution or at
 180 L<https://www.openssl.org/source/license.html>.
 181
 182 =cut