Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / DSA_generate_parameters.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
34 '''
35 '''
36 '''     Set up \*(-- to give an unbreakable dash;
37 '''     string Tr holds user defined translation string.
38 '''     Bell System Logo is used as a dummy character.
39 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
42 .ds -- \(*W-
43 .ds PI pi
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46 .ds L" ""
47 .ds R" ""
48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
50 '''   such as .IP and .SH, which do another additional levels of
51 '''   double-quote interpretation
52 .ds M" """
53 .ds S" """
54 .ds N" """""
55 .ds T" """""
56 .ds L' '
57 .ds R' '
58 .ds M' '
59 .ds S' '
60 .ds N' '
61 .ds T' '
62 'br\}
63 .el\{\
64 .ds -- \(em\|
65 .tr \*(Tr
66 .ds L" ``
67 .ds R" ''
68 .ds M" ``
69 .ds S" ''
70 .ds N" ``
71 .ds T" ''
72 .ds L' `
73 .ds R' '
74 .ds M' `
75 .ds S' '
76 .ds N' `
77 .ds T' '
78 .ds PI \(*p
79 'br\}
80 .\"     If the F register is turned on, we'll generate
81 .\"     index entries out stderr for the following things:
82 .\"             TH      Title 
83 .\"             SH      Header
84 .\"             Sh      Subsection 
85 .\"             Ip      Item
86 .\"             X<>     Xref  (embedded
87 .\"     Of course, you have to process the output yourself
88 .\"     in some meaninful fashion.
89 .if \nF \{
90 .de IX
91 .tm Index:\\$1\t\\n%\t"\\$2"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH DSA_generate_parameters 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ          \" put $1 in typewriter font
102 .ft CW
103 'if n "\c
104 'if t \\&\\$1\c
105 'if n \\&\\$1\c
106 'if n \&"
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108 '.ft R
109 ..
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 .       \" AM - accent mark definitions
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 .       \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
173 .       ds : e
174 .       ds 8 ss
175 .       ds v \h'-1'\o'\(aa\(ga'
176 .       ds _ \h'-1'^
177 .       ds . \h'-1'.
178 .       ds 3 3
179 .       ds o a
180 .       ds d- d\h'-1'\(ga
181 .       ds D- D\h'-1'\(hy
182 .       ds th \o'bp'
183 .       ds Th \o'LP'
184 .       ds ae ae
185 .       ds Ae AE
186 .       ds oe oe
187 .       ds Oe OE
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 DSA_generate_parameters \- generate DSA parameters
192 .SH "SYNOPSIS"
193 .PP
194 .Vb 1
195 \& #include <openssl/dsa.h>
196 .Ve
197 .Vb 3
198 \& DSA *DSA_generate_parameters(int bits, unsigned char *seed,
199 \&                int seed_len, int *counter_ret, unsigned long *h_ret,
200 \&                void (*callback)(int, int, void *), void *cb_arg);
201 .Ve
202 .SH "DESCRIPTION"
203 \fIDSA_generate_parameters()\fR generates primes p and q and a generator g
204 for use in the DSA.
205 .PP
206 \fBbits\fR is the length of the prime to be generated; the DSS allows a
207 maximum of 1024 bits.
208 .PP
209 If \fBseed\fR is \fBNULL\fR or \fBseed_len\fR < 20, the primes will be
210 generated at random. Otherwise, the seed is used to generate
211 them. If the given seed does not yield a prime q, a new random
212 seed is chosen and placed at \fBseed\fR.
213 .PP
214 \fIDSA_generate_parameters()\fR places the iteration count in
215 *\fBcounter_ret\fR and a counter used for finding a generator in
216 *\fBh_ret\fR, unless these are \fBNULL\fR.
217 .PP
218 A callback function may be used to provide feedback about the progress
219 of the key generation. If \fBcallback\fR is not \fBNULL\fR, it will be
220 called as follows:
221 .Ip "\(bu" 4
222 When a candidate for q is generated, \fBcallback(0, m++, cb_arg)\fR is called
223 (m is 0 for the first candidate).
224 .Ip "\(bu" 4
225 When a candidate for q has passed a test by trial division,
226 \fBcallback(1, \-1, cb_arg)\fR is called.
227 While a candidate for q is tested by Miller-Rabin primality tests,
228 \fBcallback(1, i, cb_arg)\fR is called in the outer loop
229 (once for each witness that confirms that the candidate may be prime);
230 i is the loop counter (starting at 0).
231 .Ip "\(bu" 4
232 When a prime q has been found, \fBcallback(2, 0, cb_arg)\fR and
233 \fBcallback(3, 0, cb_arg)\fR are called.
234 .Ip "\(bu" 4
235 Before a candidate for p (other than the first) is generated and tested,
236 \fBcallback(0, counter, cb_arg)\fR is called.
237 .Ip "\(bu" 4
238 When a candidate for p has passed the test by trial division,
239 \fBcallback(1, \-1, cb_arg)\fR is called.
240 While it is tested by the Miller-Rabin primality test,
241 \fBcallback(1, i, cb_arg)\fR is called in the outer loop
242 (once for each witness that confirms that the candidate may be prime).
243 i is the loop counter (starting at 0).
244 .Ip "\(bu" 4
245 When p has been found, \fBcallback(2, 1, cb_arg)\fR is called.
246 .Ip "\(bu" 4
247 When the generator has been found, \fBcallback(3, 1, cb_arg)\fR is called.
248 .SH "RETURN VALUE"
249 \fIDSA_generate_parameters()\fR returns a pointer to the DSA structure, or
250 \fBNULL\fR if the parameter generation fails. The error codes can be
251 obtained by ERR_get_error(3).
252 .SH "BUGS"
253 Seed lengths > 20 are not supported.
254 .SH "SEE ALSO"
255 dsa(3), ERR_get_error(3), rand(3),
256 DSA_free(3)
257 .SH "HISTORY"
258 \fIDSA_generate_parameters()\fR appeared in SSLeay 0.8. The \fBcb_arg\fR
259 argument was added in SSLeay 0.9.0.
260 In versions up to OpenSSL 0.9.4, \fBcallback(1, ...)\fR was called
261 in the inner loop of the Miller-Rabin test whenever it reached the
262 squaring step (the parameters to \fBcallback\fR did not reveal how many
263 witnesses had been tested); since OpenSSL 0.9.5, \fBcallback(1, ...)\fR
264 is called as in \fIBN_is_prime\fR\|(3), i.e. once for each witness.
265 =cut
266
267 .rn }` ''
268 .IX Title "DSA_generate_parameters 3"
269 .IX Name "DSA_generate_parameters - generate DSA parameters"
270
271 .IX Header "NAME"
272
273 .IX Header "SYNOPSIS"
274
275 .IX Header "DESCRIPTION"
276
277 .IX Item "\(bu"
278
279 .IX Item "\(bu"
280
281 .IX Item "\(bu"
282
283 .IX Item "\(bu"
284
285 .IX Item "\(bu"
286
287 .IX Item "\(bu"
288
289 .IX Item "\(bu"
290
291 .IX Header "RETURN VALUE"
292
293 .IX Header "BUGS"
294
295 .IX Header "SEE ALSO"
296
297 .IX Header "HISTORY"
298