1 .\" $NetBSD: DSA_generate_parameters.3,v 1.14 2015/06/12 17:01:13 christos Exp $
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
11 .de Vb \" Begin verbatim text
16 .de Ve \" End verbatim text
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), 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.
56 .\" Avoid warning from groff about undefined register 'F'.
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
64 . tm Index:\\$1\t\\n%\t"\\$2"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
91 . \" simple accents for nroff and troff
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
135 .\" ========================================================================
137 .IX Title "DSA_generate_parameters 3"
138 .TH DSA_generate_parameters 3 "2009-07-19" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
144 DSA_generate_parameters \- generate DSA parameters
148 .IX Header "SYNOPSIS"
150 \& #include <openssl/dsa.h>
152 \& DSA *DSA_generate_parameters(int bits, unsigned char *seed,
153 \& int seed_len, int *counter_ret, unsigned long *h_ret,
154 \& void (*callback)(int, int, void *), void *cb_arg);
157 .IX Header "DESCRIPTION"
158 \&\fIDSA_generate_parameters()\fR generates primes p and q and a generator g
159 for use in the \s-1DSA.\s0
161 \&\fBbits\fR is the length of the prime to be generated; the \s-1DSS\s0 allows a
162 maximum of 1024 bits.
164 If \fBseed\fR is \fB\s-1NULL\s0\fR or \fBseed_len\fR < 20, the primes will be
165 generated at random. Otherwise, the seed is used to generate
166 them. If the given seed does not yield a prime q, a new random
167 seed is chosen and placed at \fBseed\fR.
169 \&\fIDSA_generate_parameters()\fR places the iteration count in
170 *\fBcounter_ret\fR and a counter used for finding a generator in
171 *\fBh_ret\fR, unless these are \fB\s-1NULL\s0\fR.
173 A callback function may be used to provide feedback about the progress
174 of the key generation. If \fBcallback\fR is not \fB\s-1NULL\s0\fR, it will be
177 When a candidate for q is generated, \fBcallback(0, m++, cb_arg)\fR is called
178 (m is 0 for the first candidate).
180 When a candidate for q has passed a test by trial division,
181 \&\fBcallback(1, \-1, cb_arg)\fR is called.
182 While a candidate for q is tested by Miller-Rabin primality tests,
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 a prime q has been found, \fBcallback(2, 0, cb_arg)\fR and
188 \&\fBcallback(3, 0, cb_arg)\fR are called.
190 Before a candidate for p (other than the first) is generated and tested,
191 \&\fBcallback(0, counter, cb_arg)\fR is called.
193 When a candidate for p has passed the test by trial division,
194 \&\fBcallback(1, \-1, cb_arg)\fR is called.
195 While it is tested by the Miller-Rabin primality test,
196 \&\fBcallback(1, i, cb_arg)\fR is called in the outer loop
197 (once for each witness that confirms that the candidate may be prime).
198 i is the loop counter (starting at 0).
200 When p has been found, \fBcallback(2, 1, cb_arg)\fR is called.
202 When the generator has been found, \fBcallback(3, 1, cb_arg)\fR is called.
204 .IX Header "RETURN VALUE"
205 \&\fIDSA_generate_parameters()\fR returns a pointer to the \s-1DSA\s0 structure, or
206 \&\fB\s-1NULL\s0\fR if the parameter generation fails. The error codes can be
207 obtained by \fIERR_get_error\fR\|(3).
210 Seed lengths > 20 are not supported.
212 .IX Header "SEE ALSO"
213 \&\fIopenssl_dsa\fR\|(3), \fIERR_get_error\fR\|(3), \fIopenssl_rand\fR\|(3),
214 \&\fIDSA_free\fR\|(3)
217 \&\fIDSA_generate_parameters()\fR appeared in SSLeay 0.8. The \fBcb_arg\fR
218 argument was added in SSLeay 0.9.0.
219 In versions up to OpenSSL 0.9.4, \fBcallback(1, ...)\fR was called
220 in the inner loop of the Miller-Rabin test whenever it reached the
221 squaring step (the parameters to \fBcallback\fR did not reveal how many
222 witnesses had been tested); since OpenSSL 0.9.5, \fBcallback(1, ...)\fR
223 is called as in \fIBN_is_prime\fR\|(3), i.e. once for each witness.