1 .\" Automatically generated by Pod::Man 2.16 (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 .\" Escape single quotes in literal strings from groff's Unicode transform.
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
61 . tm Index:\\$1\t\\n%\t"\\$2"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
88 . \" simple accents for nroff and troff
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
132 .\" ========================================================================
134 .IX Title "DSA_generate_parameters 3"
135 .TH DSA_generate_parameters 3 "2009-04-11" "0.9.8k" "OpenSSL"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
141 DSA_generate_parameters \- generate DSA parameters
143 .IX Header "SYNOPSIS"
145 \& #include <openssl/dsa.h>
147 \& DSA *DSA_generate_parameters(int bits, unsigned char *seed,
148 \& int seed_len, int *counter_ret, unsigned long *h_ret,
149 \& void (*callback)(int, int, void *), void *cb_arg);
152 .IX Header "DESCRIPTION"
153 \&\fIDSA_generate_parameters()\fR generates primes p and q and a generator g
154 for use in the \s-1DSA\s0.
156 \&\fBbits\fR is the length of the prime to be generated; the \s-1DSS\s0 allows a
157 maximum of 1024 bits.
159 If \fBseed\fR is \fB\s-1NULL\s0\fR or \fBseed_len\fR < 20, the primes will be
160 generated at random. Otherwise, the seed is used to generate
161 them. If the given seed does not yield a prime q, a new random
162 seed is chosen and placed at \fBseed\fR.
164 \&\fIDSA_generate_parameters()\fR places the iteration count in
165 *\fBcounter_ret\fR and a counter used for finding a generator in
166 *\fBh_ret\fR, unless these are \fB\s-1NULL\s0\fR.
168 A callback function may be used to provide feedback about the progress
169 of the key generation. If \fBcallback\fR is not \fB\s-1NULL\s0\fR, it will be
172 When a candidate for q is generated, \fBcallback(0, m++, cb_arg)\fR is called
173 (m is 0 for the first candidate).
175 When a candidate for q has passed a test by trial division,
176 \&\fBcallback(1, \-1, cb_arg)\fR is called.
177 While a candidate for q is tested by Miller-Rabin primality tests,
178 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
179 (once for each witness that confirms that the candidate may be prime);
180 i is the loop counter (starting at 0).
182 When a prime q has been found, \fBcallback(2, 0, cb_arg)\fR and
183 \&\fBcallback(3, 0, cb_arg)\fR are called.
185 Before a candidate for p (other than the first) is generated and tested,
186 \&\fBcallback(0, counter, cb_arg)\fR is called.
188 When a candidate for p has passed the test by trial division,
189 \&\fBcallback(1, \-1, cb_arg)\fR is called.
190 While it is tested by the Miller-Rabin primality test,
191 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
192 (once for each witness that confirms that the candidate may be prime).
193 i is the loop counter (starting at 0).
195 When p has been found, \fBcallback(2, 1, cb_arg)\fR is called.
197 When the generator has been found, \fBcallback(3, 1, cb_arg)\fR is called.
199 .IX Header "RETURN VALUE"
200 \&\fIDSA_generate_parameters()\fR returns a pointer to the \s-1DSA\s0 structure, or
201 \&\fB\s-1NULL\s0\fR if the parameter generation fails. The error codes can be
202 obtained by \fIERR_get_error\fR\|(3).
205 Seed lengths > 20 are not supported.
207 .IX Header "SEE ALSO"
208 \&\fIdsa\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3),
209 \&\fIDSA_free\fR\|(3)
212 \&\fIDSA_generate_parameters()\fR appeared in SSLeay 0.8. The \fBcb_arg\fR
213 argument was added in SSLeay 0.9.0.
214 In versions up to OpenSSL 0.9.4, \fBcallback(1, ...)\fR was called
215 in the inner loop of the Miller-Rabin test whenever it reached the
216 squaring step (the parameters to \fBcallback\fR did not reveal how many
217 witnesses had been tested); since OpenSSL 0.9.5, \fBcallback(1, ...)\fR
218 is called as in \fIBN_is_prime\fR\|(3), i.e. once for each witness.