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