doc/man3/RSA_generate_key.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/rsa.h>
  10
  11  int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
  12
  13 Deprecated:
  14
  15  #if OPENSSL_API_COMPAT < 0x00908000L
  16  RSA *RSA_generate_key(int num, unsigned long e,
  17                        void (*callback)(int, int, void *), void *cb_arg);
  18  #endif
  19
  20 =head1 DESCRIPTION
  21
  22 RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
  23 structure provided in B<rsa>. The pseudo-random number generator must
  24 be seeded prior to calling RSA_generate_key_ex().
  25
  26 The modulus size will be of length B<bits>, and the public exponent will be
  27 B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
  28 The exponent is an odd number, typically 3, 17 or 65537.
  29
  30 A callback function may be used to provide feedback about the
  31 progress of the key generation. If B<cb> is not B<NULL>, it
  32 will be called as follows using the BN_GENCB_call() function
  33 described on the L<BN_generate_prime(3)> page.
  34
  35 RSA_generate_prime() is similar to RSA_generate_prime_ex() but
  36 expects an old-style callback function; see
  37 L<BN_generate_prime(3)> for information on the old-style callback.
  38
  39 =over 2
  40
  41 =item *
  42
  43 While a random prime number is generated, it is called as
  44 described in L<BN_generate_prime(3)>.
  45
  46 =item *
  47
  48 When the n-th randomly generated prime is rejected as not
  49 suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
  50
  51 =item *
  52
  53 When a random p has been found with p-1 relatively prime to B<e>,
  54 it is called as B<BN_GENCB_call(cb, 3, 0)>.
  55
  56 =back
  57
  58 The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
  59
  60 =head1 RETURN VALUE
  61
  62 RSA_generate_key_ex() returns 1 on success or 0 on error.
  63 The error codes can be obtained by L<ERR_get_error(3)>.
  64
  65 RSA_generate_key() returns a pointer to the RSA structure or
  66 B<NULL> if the key generation fails.
  67
  68 =head1 BUGS
  69
  70 B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
  71
  72 =head1 SEE ALSO
  73
  74 L<ERR_get_error(3)>, L<RAND_bytes(3)>,
  75 L<RSA_generate_key_ex(3)>, L<BN_generate_prime(3)>
  76
  77 =head1 HISTORY
  78
  79 RSA_generate_key() was deprecated in OpenSSL 0.9.8; use
  80 RSA_generate_key_ex() intsead.
  81
  82 =head1 COPYRIGHT
  83
  84 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  85
  86 Licensed under the OpenSSL license (the "License").  You may not use
  87 this file except in compliance with the License.  You can obtain a copy
  88 in the file LICENSE in the source distribution or at
  89 L<https://www.openssl.org/source/license.html>.
  90
  91 =cut