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