]>
Commit | Line | Data |
---|---|---|
38e33cef UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters |
38e33cef UM |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/dsa.h> | |
10 | ||
aafbe1cc | 11 | int DSA_generate_parameters_ex(DSA *dsa, int bits, |
e9b77246 BB |
12 | const unsigned char *seed, int seed_len, |
13 | int *counter_ret, unsigned long *h_ret, | |
14 | BN_GENCB *cb); | |
aafbe1cc | 15 | |
be80b21d RL |
16 | Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining |
17 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
18 | L<openssl_user_macros(7)>: | |
aafbe1cc | 19 | |
e9b77246 BB |
20 | DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, |
21 | int *counter_ret, unsigned long *h_ret, | |
22 | void (*callback)(int, int, void *), void *cb_arg); | |
38e33cef UM |
23 | |
24 | =head1 DESCRIPTION | |
25 | ||
aafbe1cc MC |
26 | DSA_generate_parameters_ex() generates primes p and q and a generator g |
27 | for use in the DSA and stores the result in B<dsa>. | |
38e33cef | 28 | |
f00a10b8 IP |
29 | B<bits> is the length of the prime p to be generated. |
30 | For lengths under 2048 bits, the length of q is 160 bits; for lengths | |
36ac7bc8 | 31 | greater than or equal to 2048 bits, the length of q is set to 256 bits. |
38e33cef | 32 | |
f00a10b8 IP |
33 | If B<seed> is NULL, the primes will be generated at random. |
34 | If B<seed_len> is less than the length of q, an error is returned. | |
38e33cef | 35 | |
aafbe1cc | 36 | DSA_generate_parameters_ex() places the iteration count in |
38e33cef | 37 | *B<counter_ret> and a counter used for finding a generator in |
a87030a1 | 38 | *B<h_ret>, unless these are B<NULL>. |
38e33cef UM |
39 | |
40 | A callback function may be used to provide feedback about the progress | |
aafbe1cc MC |
41 | of the key generation. If B<cb> is not B<NULL>, it will be |
42 | called as shown below. For information on the BN_GENCB structure and the | |
43 | BN_GENCB_call function discussed below, refer to | |
9b86974e | 44 | L<BN_generate_prime(3)>. |
38e33cef | 45 | |
b3696a55 RS |
46 | DSA_generate_prime() is similar to DSA_generate_prime_ex() but |
47 | expects an old-style callback function; see | |
48 | L<BN_generate_prime(3)> for information on the old-style callback. | |
49 | ||
2f61bc2e | 50 | =over 2 |
38e33cef UM |
51 | |
52 | =item * | |
53 | ||
aafbe1cc | 54 | When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called |
a87030a1 | 55 | (m is 0 for the first candidate). |
38e33cef UM |
56 | |
57 | =item * | |
58 | ||
1baa9490 | 59 | When a candidate for q has passed a test by trial division, |
aafbe1cc | 60 | B<BN_GENCB_call(cb, 1, -1)> is called. |
1baa9490 | 61 | While a candidate for q is tested by Miller-Rabin primality tests, |
aafbe1cc | 62 | B<BN_GENCB_call(cb, 1, i)> is called in the outer loop |
1baa9490 | 63 | (once for each witness that confirms that the candidate may be prime); |
a87030a1 | 64 | i is the loop counter (starting at 0). |
38e33cef UM |
65 | |
66 | =item * | |
67 | ||
aafbe1cc MC |
68 | When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and |
69 | B<BN_GENCB_call(cb, 3, 0)> are called. | |
38e33cef UM |
70 | |
71 | =item * | |
72 | ||
a87030a1 | 73 | Before a candidate for p (other than the first) is generated and tested, |
aafbe1cc | 74 | B<BN_GENCB_call(cb, 0, counter)> is called. |
a87030a1 BM |
75 | |
76 | =item * | |
77 | ||
1baa9490 | 78 | When a candidate for p has passed the test by trial division, |
aafbe1cc | 79 | B<BN_GENCB_call(cb, 1, -1)> is called. |
1baa9490 | 80 | While it is tested by the Miller-Rabin primality test, |
aafbe1cc | 81 | B<BN_GENCB_call(cb, 1, i)> is called in the outer loop |
a87030a1 BM |
82 | (once for each witness that confirms that the candidate may be prime). |
83 | i is the loop counter (starting at 0). | |
38e33cef UM |
84 | |
85 | =item * | |
86 | ||
aafbe1cc | 87 | When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called. |
38e33cef UM |
88 | |
89 | =item * | |
90 | ||
aafbe1cc | 91 | When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called. |
38e33cef UM |
92 | |
93 | =back | |
94 | ||
1f13ad31 | 95 | =head1 RETURN VALUES |
38e33cef | 96 | |
aafbe1cc | 97 | DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. |
b3696a55 | 98 | The error codes can be obtained by L<ERR_get_error(3)>. |
aafbe1cc | 99 | |
b3696a55 | 100 | DSA_generate_parameters() returns a pointer to the DSA structure or |
aafbe1cc MC |
101 | B<NULL> if the parameter generation fails. |
102 | ||
38e33cef UM |
103 | =head1 BUGS |
104 | ||
b3696a55 | 105 | Seed lengths greater than 20 are not supported. |
38e33cef UM |
106 | |
107 | =head1 SEE ALSO | |
108 | ||
b97fdb57 | 109 | L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, |
9b86974e | 110 | L<DSA_free(3)>, L<BN_generate_prime(3)> |
38e33cef | 111 | |
b3696a55 RS |
112 | =head1 HISTORY |
113 | ||
02eca5c6 | 114 | DSA_generate_parameters() was deprecated in OpenSSL 0.9.8; use |
b3696a55 RS |
115 | DSA_generate_parameters_ex() instead. |
116 | ||
e2f92610 RS |
117 | =head1 COPYRIGHT |
118 | ||
61f805c1 | 119 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 120 | |
4746f25a | 121 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
122 | this file except in compliance with the License. You can obtain a copy |
123 | in the file LICENSE in the source distribution or at | |
124 | L<https://www.openssl.org/source/license.html>. | |
125 | ||
126 | =cut |