1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
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. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, 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 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "DSA_generate_parameters 3"
132 .TH DSA_generate_parameters 3 "2009-07-23" "0.9.8k" "OpenSSL"
134 DSA_generate_parameters \- generate DSA parameters
136 .IX Header "SYNOPSIS"
138 \& #include <openssl/dsa.h>
142 \& DSA *DSA_generate_parameters(int bits, unsigned char *seed,
143 \& int seed_len, int *counter_ret, unsigned long *h_ret,
144 \& void (*callback)(int, int, void *), void *cb_arg);
147 .IX Header "DESCRIPTION"
148 \&\fIDSA_generate_parameters()\fR generates primes p and q and a generator g
149 for use in the \s-1DSA\s0.
151 \&\fBbits\fR is the length of the prime to be generated; the \s-1DSS\s0 allows a
152 maximum of 1024 bits.
154 If \fBseed\fR is \fB\s-1NULL\s0\fR or \fBseed_len\fR < 20, the primes will be
155 generated at random. Otherwise, the seed is used to generate
156 them. If the given seed does not yield a prime q, a new random
157 seed is chosen and placed at \fBseed\fR.
159 \&\fIDSA_generate_parameters()\fR places the iteration count in
160 *\fBcounter_ret\fR and a counter used for finding a generator in
161 *\fBh_ret\fR, unless these are \fB\s-1NULL\s0\fR.
163 A callback function may be used to provide feedback about the progress
164 of the key generation. If \fBcallback\fR is not \fB\s-1NULL\s0\fR, it will be
167 When a candidate for q is generated, \fBcallback(0, m++, cb_arg)\fR is called
168 (m is 0 for the first candidate).
170 When a candidate for q has passed a test by trial division,
171 \&\fBcallback(1, \-1, cb_arg)\fR is called.
172 While a candidate for q is tested by Miller-Rabin primality tests,
173 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
174 (once for each witness that confirms that the candidate may be prime);
175 i is the loop counter (starting at 0).
177 When a prime q has been found, \fBcallback(2, 0, cb_arg)\fR and
178 \&\fBcallback(3, 0, cb_arg)\fR are called.
180 Before a candidate for p (other than the first) is generated and tested,
181 \&\fBcallback(0, counter, cb_arg)\fR is called.
183 When a candidate for p has passed the test by trial division,
184 \&\fBcallback(1, \-1, cb_arg)\fR is called.
185 While it is tested by the Miller-Rabin primality test,
186 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
187 (once for each witness that confirms that the candidate may be prime).
188 i is the loop counter (starting at 0).
190 When p has been found, \fBcallback(2, 1, cb_arg)\fR is called.
192 When the generator has been found, \fBcallback(3, 1, cb_arg)\fR is called.
194 .IX Header "RETURN VALUE"
195 \&\fIDSA_generate_parameters()\fR returns a pointer to the \s-1DSA\s0 structure, or
196 \&\fB\s-1NULL\s0\fR if the parameter generation fails. The error codes can be
197 obtained by \fIERR_get_error\fR\|(3).
200 Seed lengths > 20 are not supported.
202 .IX Header "SEE ALSO"
203 \&\fIdsa\fR\|(3), \fIERR_get_error\fR\|(3), \fIrand\fR\|(3),
204 \&\fIDSA_free\fR\|(3)
207 \&\fIDSA_generate_parameters()\fR appeared in SSLeay 0.8. The \fBcb_arg\fR
208 argument was added in SSLeay 0.9.0.
209 In versions up to OpenSSL 0.9.4, \fBcallback(1, ...)\fR was called
210 in the inner loop of the Miller-Rabin test whenever it reached the
211 squaring step (the parameters to \fBcallback\fR did not reveal how many
212 witnesses had been tested); since OpenSSL 0.9.5, \fBcallback(1, ...)\fR
213 is called as in \fIBN_is_prime\fR\|(3), i.e. once for each witness.