]>
Commit | Line | Data |
---|---|---|
38e33cef UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4d524e10 | 5 | DSA_generate_parameters - generate DSA parameters |
38e33cef UM |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/dsa.h> | |
10 | ||
74235cc9 | 11 | DSA *DSA_generate_parameters(int bits, unsigned char *seed, |
38e33cef | 12 | int seed_len, int *counter_ret, unsigned long *h_ret, |
9dbc41d7 | 13 | void (*callback)(int, int, void *), void *cb_arg); |
38e33cef UM |
14 | |
15 | =head1 DESCRIPTION | |
16 | ||
17 | DSA_generate_parameters() generates primes p and q and a generator g | |
18 | for use in the DSA. | |
19 | ||
9a974464 IP |
20 | B<bits> is the length of the prime p to be generated. |
21 | For lengths under 2048 bits, the length of q is 160 bits; for lengths | |
22 | at least 2048, it is set to 256 bits. | |
38e33cef | 23 | |
9a974464 IP |
24 | If B<seed> is NULL, the primes will be generated at random. |
25 | If B<seed_len> is less than the length of q, an error is returned. | |
38e33cef UM |
26 | |
27 | DSA_generate_parameters() places the iteration count in | |
28 | *B<counter_ret> and a counter used for finding a generator in | |
a87030a1 | 29 | *B<h_ret>, unless these are B<NULL>. |
38e33cef UM |
30 | |
31 | A callback function may be used to provide feedback about the progress | |
32 | of the key generation. If B<callback> is not B<NULL>, it will be | |
33 | called as follows: | |
34 | ||
35 | =over 4 | |
36 | ||
37 | =item * | |
38 | ||
a87030a1 BM |
39 | When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called |
40 | (m is 0 for the first candidate). | |
38e33cef UM |
41 | |
42 | =item * | |
43 | ||
1baa9490 BM |
44 | When a candidate for q has passed a test by trial division, |
45 | B<callback(1, -1, cb_arg)> is called. | |
46 | While a candidate for q is tested by Miller-Rabin primality tests, | |
47 | B<callback(1, i, cb_arg)> is called in the outer loop | |
48 | (once for each witness that confirms that the candidate may be prime); | |
a87030a1 | 49 | i is the loop counter (starting at 0). |
38e33cef UM |
50 | |
51 | =item * | |
52 | ||
53 | When a prime q has been found, B<callback(2, 0, cb_arg)> and | |
54 | B<callback(3, 0, cb_arg)> are called. | |
55 | ||
56 | =item * | |
57 | ||
a87030a1 BM |
58 | Before a candidate for p (other than the first) is generated and tested, |
59 | B<callback(0, counter, cb_arg)> is called. | |
60 | ||
61 | =item * | |
62 | ||
1baa9490 | 63 | When a candidate for p has passed the test by trial division, |
1749d8a0 | 64 | B<callback(1, -1, cb_arg)> is called. |
1baa9490 BM |
65 | While it is tested by the Miller-Rabin primality test, |
66 | B<callback(1, i, cb_arg)> is called in the outer loop | |
a87030a1 BM |
67 | (once for each witness that confirms that the candidate may be prime). |
68 | i is the loop counter (starting at 0). | |
38e33cef UM |
69 | |
70 | =item * | |
71 | ||
72 | When p has been found, B<callback(2, 1, cb_arg)> is called. | |
73 | ||
74 | =item * | |
75 | ||
76 | When the generator has been found, B<callback(3, 1, cb_arg)> is called. | |
77 | ||
78 | =back | |
79 | ||
80 | =head1 RETURN VALUE | |
81 | ||
82 | DSA_generate_parameters() returns a pointer to the DSA structure, or | |
a87030a1 | 83 | B<NULL> if the parameter generation fails. The error codes can be |
38e33cef UM |
84 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. |
85 | ||
86 | =head1 BUGS | |
87 | ||
38e33cef UM |
88 | Seed lengths E<gt> 20 are not supported. |
89 | ||
90 | =head1 SEE ALSO | |
91 | ||
6859cf74 | 92 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, |
38e33cef UM |
93 | L<DSA_free(3)|DSA_free(3)> |
94 | ||
95 | =head1 HISTORY | |
96 | ||
97 | DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> | |
98 | argument was added in SSLeay 0.9.0. | |
a87030a1 BM |
99 | In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called |
100 | in the inner loop of the Miller-Rabin test whenever it reached the | |
101 | squaring step (the parameters to B<callback> did not reveal how many | |
102 | witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> | |
103 | is called as in BN_is_prime(3), i.e. once for each witness. | |
38e33cef | 104 | =cut |