Less documentation for deprecated API
[openssl.git] / 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