RSA_generate_key.pod revision 312826 
1=pod
2
3=head1 NAME
4
5RSA_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
13Deprecated:
14
15 RSA *RSA_generate_key(int num, unsigned long e,
16    void (*callback)(int,int,void *), void *cb_arg);
17
18=head1 DESCRIPTION
19
20RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
21structure provided in B<rsa>. The pseudo-random number generator must
22be seeded prior to calling RSA_generate_key_ex().
23
24The modulus size will be of length B<bits>, and the public exponent will be
25B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
26The exponent is an odd number, typically 3, 17 or 65537.
27
28A callback function may be used to provide feedback about the
29progress of the key generation. If B<cb> is not B<NULL>, it
30will be called as follows using the BN_GENCB_call() function
31described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page.
32
33=over 4
34
35=item *
36
37While a random prime number is generated, it is called as
38described in L<BN_generate_prime(3)|BN_generate_prime(3)>.
39
40=item *
41
42When the n-th randomly generated prime is rejected as not
43suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
44
45=item *
46
47When a random p has been found with p-1 relatively prime to B<e>,
48it is called as B<BN_GENCB_call(cb, 3, 0)>.
49
50=back
51
52The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
53
54RSA_generate_key is deprecated (new applications should use
55RSA_generate_key_ex instead). RSA_generate_key works in the same way as
56RSA_generate_key_ex except it uses "old style" call backs. See
57L<BN_generate_prime(3)|BN_generate_prime(3)> for further details.
58
59=head1 RETURN VALUE
60
61If key generation fails, RSA_generate_key() returns B<NULL>.
62
63The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
64
65=head1 BUGS
66
67B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
68
69RSA_generate_key() goes into an infinite loop for illegal input values.
70
71=head1 SEE ALSO
72
73L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
74L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
75
76=head1 HISTORY
77
78The B<cb_arg> argument was added in SSLeay 0.9.0.
79
80=cut
81