1 .\" Automatically generated by Pod::Man 2.12 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
124 .\" ========================================================================
126 .IX Title "DSA_generate_parameters 3"
127 .TH DSA_generate_parameters 3 "2007-10-24" "0.9.8g" "OpenSSL"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 DSA_generate_parameters \- generate DSA parameters
135 .IX Header "SYNOPSIS"
137 \& #include <openssl/dsa.h>
139 \& DSA *DSA_generate_parameters(int bits, unsigned char *seed,
140 \& int seed_len, int *counter_ret, unsigned long *h_ret,
141 \& void (*callback)(int, int, void *), void *cb_arg);
144 .IX Header "DESCRIPTION"
145 \&\fIDSA_generate_parameters()\fR generates primes p and q and a generator g
146 for use in the \s-1DSA\s0.
148 \&\fBbits\fR is the length of the prime to be generated; the \s-1DSS\s0 allows a
149 maximum of 1024 bits.
151 If \fBseed\fR is \fB\s-1NULL\s0\fR or \fBseed_len\fR < 20, the primes will be
152 generated at random. Otherwise, the seed is used to generate
153 them. If the given seed does not yield a prime q, a new random
154 seed is chosen and placed at \fBseed\fR.
156 \&\fIDSA_generate_parameters()\fR places the iteration count in
157 *\fBcounter_ret\fR and a counter used for finding a generator in
158 *\fBh_ret\fR, unless these are \fB\s-1NULL\s0\fR.
160 A callback function may be used to provide feedback about the progress
161 of the key generation. If \fBcallback\fR is not \fB\s-1NULL\s0\fR, it will be
164 When a candidate for q is generated, \fBcallback(0, m++, cb_arg)\fR is called
165 (m is 0 for the first candidate).
167 When a candidate for q has passed a test by trial division,
168 \&\fBcallback(1, \-1, cb_arg)\fR is called.
169 While a candidate for q is tested by Miller-Rabin primality tests,
170 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
171 (once for each witness that confirms that the candidate may be prime);
172 i is the loop counter (starting at 0).
174 When a prime q has been found, \fBcallback(2, 0, cb_arg)\fR and
175 \&\fBcallback(3, 0, cb_arg)\fR are called.
177 Before a candidate for p (other than the first) is generated and tested,
178 \&\fBcallback(0, counter, cb_arg)\fR is called.
180 When a candidate for p has passed the test by trial division,
181 \&\fBcallback(1, \-1, cb_arg)\fR is called.
182 While it is tested by the Miller-Rabin primality test,
183 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
184 (once for each witness that confirms that the candidate may be prime).
185 i is the loop counter (starting at 0).
187 When p has been found, \fBcallback(2, 1, cb_arg)\fR is called.
189 When the generator has been found, \fBcallback(3, 1, cb_arg)\fR is called.
191 .IX Header "RETURN VALUE"
192 \&\fIDSA_generate_parameters()\fR returns a pointer to the \s-1DSA\s0 structure, or
193 \&\fB\s-1NULL\s0\fR if the parameter generation fails. The error codes can be
194 obtained by \fIERR_get_error\fR\|(3).
197 Seed lengths > 20 are not supported.
199 .IX Header "SEE ALSO"
200 \&\fIdsa\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3),
201 \&\fIDSA_free\fR\|(3)
204 \&\fIDSA_generate_parameters()\fR appeared in SSLeay 0.8. The \fBcb_arg\fR
205 argument was added in SSLeay 0.9.0.
206 In versions up to OpenSSL 0.9.4, \fBcallback(1, ...)\fR was called
207 in the inner loop of the Miller-Rabin test whenever it reached the
208 squaring step (the parameters to \fBcallback\fR did not reveal how many
209 witnesses had been tested); since OpenSSL 0.9.5, \fBcallback(1, ...)\fR
210 is called as in \fIBN_is_prime\fR\|(3), i.e. once for each witness.