| blob | e6e6d90dce7ef840ad083398824d3f0940fac9c3 |
1 .\" $OpenBSD: DSA_generate_parameters.3,v 1.5 2016/12/10 22:47:49 schwarze Exp $
2 .\" OpenSSL 9b86974e Aug 7 22:14:47 2015 -0400
3 .\"
4 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
5 .\" Bodo Moeller <bodo@openssl.org>, and Matt Caswell <matt@openssl.org>.
6 .\" Copyright (c) 2000, 2013 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: December 10 2016 $
53 .Dt DSA_GENERATE_PARAMETERS 3
54 .Os
55 .Sh NAME
56 .Nm DSA_generate_parameters_ex ,
57 .Nm DSA_generate_parameters
58 .Nd generate DSA parameters
59 .Sh SYNOPSIS
60 .In openssl/dsa.h
61 .Ft int
62 .Fo DSA_generate_parameters_ex
63 .Fa "DSA *dsa"
64 .Fa "int bits"
65 .Fa "const unsigned char *seed"
66 .Fa "int seed_len"
67 .Fa "int *counter_ret"
68 .Fa "unsigned long *h_ret"
69 .Fa "BN_GENCB *cb"
70 .Fc
71 .Pp
72 Deprecated:
73 .Pp
74 .Ft DSA *
75 .Fo DSA_generate_parameters
76 .Fa "int bits"
77 .Fa "unsigned char *seed"
78 .Fa "int seed_len"
79 .Fa "int *counter_ret"
80 .Fa "unsigned long *h_ret"
81 .Fa "void (*callback)(int, int, void *)"
82 .Fa "void *cb_arg"
83 .Fc
84 .Sh DESCRIPTION
85 .Fn DSA_generate_parameters_ex
86 generates primes p and q and a generator g for use in the DSA and stores
87 the result in
88 .Fa dsa .
89 .Pp
90 .Fa bits
91 is the length of the prime to be generated; the DSS allows a maximum of
92 1024 bits.
93 .Pp
94 If
95 .Fa seed
96 is
97 .Dv NULL
98 or
99 .Fa seed_len
100 < 20, the primes will be generated at random.
101 Otherwise, the seed is used to generate them.
102 If the given seed does not yield a prime q, a new random seed is chosen
103 and placed at
104 .Fa seed .
105 .Pp
106 .Fn DSA_generate_parameters_ex
107 places the iteration count in
108 .Pf * Fa counter_ret
109 and a counter used for finding a generator in
110 .Pf * Fa h_ret ,
111 unless these are
112 .Dv NULL .
113 .Pp
114 A callback function may be used to provide feedback about the progress
115 of the key generation.
116 If
117 .Fa cb
118 is not
119 .Dv NULL ,
120 it will be called as shown below.
121 For information on the
122 .Vt BN_GENCB
123 structure, refer to
124 .Xr BN_GENCB_call 3 .
125 .Bl -bullet
126 .It
127 When a candidate for q is generated,
128 .Fn BN_GENCB_call cb 0 m++
129 is called
130 .Pf ( Fa m
131 is 0 for the first candidate).
132 .It
133 When a candidate for q has passed a test by trial division,
134 .Fn BN_GENCB_call cb 1 -1
135 is called.
136 While a candidate for q is tested by Miller-Rabin primality tests,
137 .Fn BN_GENCB_call cb 1 i
138 is called in the outer loop (once for each witness that confirms that
139 the candidate may be prime);
140 .Fa i
141 is the loop counter (starting at 0).
142 .It
143 When a prime q has been found,
144 .Fn BN_GENCB_call cb 2 0
145 and
146 .Fn BN_GENCB_call cb 3 0
147 are called.
148 .It
149 Before a candidate for p (other than the first) is generated and tested,
150 .Fn BN_GENCB_call cb 0 counter
151 is called.
152 .It
153 When a candidate for p has passed the test by trial division,
154 .Fn BN_GENCB_call cb 1 -1
155 is called.
156 While it is tested by the Miller-Rabin primality test,
157 .Fn BN_GENCB_call cb 1 i
158 is called in the outer loop (once for each witness that confirms that
159 the candidate may be prime).
160 .Fa i
161 is the loop counter (starting at 0).
162 .It
163 When p has been found,
164 .Fn BN_GENCB_call cb 2 1
165 is called.
166 .It
167 When the generator has been found,
168 .Fn BN_GENCB_call cb 3 1
169 is called.
170 .El
171 .Pp
172 .Fn DSA_generate_parameters
173 (deprecated) works in much the same way as for
174 .Fn DSA_generate_parameters_ex ,
175 except that no
176 .Fa dsa
177 parameter is passed and instead a newly allocated
178 .Vt DSA
179 structure is returned.
180 Additionally "old style" callbacks are used instead of the newer
181 .Vt BN_GENCB
182 based approach.
183 Refer to
184 .Xr BN_generate_prime 3
185 for further information.
186 .Sh RETURN VALUES
187 .Fn DSA_generate_parameters_ex
188 returns a 1 on success, or 0 otherwise.
189 .Pp
190 .Fn DSA_generate_parameters
191 returns a pointer to the
192 .Vt DSA
193 structure, or
194 .Dv NULL
195 if the parameter generation fails.
196 .Pp
197 The error codes can be obtained by
198 .Xr ERR_get_error 3 .
199 .Sh SEE ALSO
200 .Xr BN_generate_prime 3 ,
201 .Xr DSA_new 3 ,
202 .Xr ERR_get_error 3 ,
203 .Xr RAND_bytes 3
204 .Sh HISTORY
205 .Fn DSA_generate_parameters
206 appeared in SSLeay 0.8.
207 The
208 .Fa cb_arg
209 argument was added in SSLeay 0.9.0.
210 In versions up to OpenSSL 0.9.4,
211 .Fn callback 1 ...\&
212 was called in the inner loop of the Miller-Rabin test whenever it
213 reached the squaring step (the parameters to
214 .Fn callback
215 did not reveal how many witnesses had been tested); since OpenSSL 0.9.5,
216 .Fn callback 1 ...\&
217 is called as in
218 .Xr BN_is_prime 3 ,
219 i.e. once for each witness.
220 .Sh BUGS
221 Seed lengths > 20 are not supported.