summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/DSA_generate_parameters.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/DSA_generate_parameters.3')
-rw-r--r--src/lib/libcrypto/man/DSA_generate_parameters.3226
1 files changed, 0 insertions, 226 deletions
diff --git a/src/lib/libcrypto/man/DSA_generate_parameters.3 b/src/lib/libcrypto/man/DSA_generate_parameters.3
deleted file mode 100644
index f7dcb901f3..0000000000
--- a/src/lib/libcrypto/man/DSA_generate_parameters.3
+++ /dev/null
@@ -1,226 +0,0 @@
1.\" $OpenBSD: DSA_generate_parameters.3,v 1.12 2019/06/10 14:58:48 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: June 10 2019 $
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
72Deprecated:
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
86generates primes p and q and a generator g for use in the DSA and stores
87the result in
88.Fa dsa .
89.Pp
90.Fa bits
91is the length of the prime to be generated; the DSS allows a maximum of
921024 bits.
93.Pp
94If
95.Fa seed
96is
97.Dv NULL
98or
99.Fa seed_len
100< 20, the primes will be generated at random.
101Otherwise, the seed is used to generate them.
102If the given seed does not yield a prime q, a new random seed is chosen
103and placed at
104.Fa seed .
105.Pp
106.Fn DSA_generate_parameters_ex
107places the iteration count in
108.Pf * Fa counter_ret
109and a counter used for finding a generator in
110.Pf * Fa h_ret ,
111unless these are
112.Dv NULL .
113.Pp
114A callback function may be used to provide feedback about the progress
115of the key generation.
116If
117.Fa cb
118is not
119.Dv NULL ,
120it will be called as shown below.
121For information on the
122.Vt BN_GENCB
123structure, refer to
124.Xr BN_GENCB_call 3 .
125.Bl -bullet
126.It
127When a candidate for q is generated,
128.Fn BN_GENCB_call cb 0 m++
129is called
130.Pf ( Fa m
131is 0 for the first candidate).
132.It
133When a candidate for q has passed a test by trial division,
134.Fn BN_GENCB_call cb 1 -1
135is called.
136While a candidate for q is tested by Miller-Rabin primality tests,
137.Fn BN_GENCB_call cb 1 i
138is called in the outer loop (once for each witness that confirms that
139the candidate may be prime);
140.Fa i
141is the loop counter (starting at 0).
142.It
143When a prime q has been found,
144.Fn BN_GENCB_call cb 2 0
145and
146.Fn BN_GENCB_call cb 3 0
147are called.
148.It
149Before a candidate for p (other than the first) is generated and tested,
150.Fn BN_GENCB_call cb 0 counter
151is called.
152.It
153When a candidate for p has passed the test by trial division,
154.Fn BN_GENCB_call cb 1 -1
155is called.
156While it is tested by the Miller-Rabin primality test,
157.Fn BN_GENCB_call cb 1 i
158is called in the outer loop (once for each witness that confirms that
159the candidate may be prime).
160.Fa i
161is the loop counter (starting at 0).
162.It
163When p has been found,
164.Fn BN_GENCB_call cb 2 1
165is called.
166.It
167When the generator has been found,
168.Fn BN_GENCB_call cb 3 1
169is 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 ,
175except that no
176.Fa dsa
177parameter is passed and instead a newly allocated
178.Vt DSA
179structure is returned.
180Additionally "old style" callbacks are used instead of the newer
181.Vt BN_GENCB
182based approach.
183Refer to
184.Xr BN_generate_prime 3
185for further information.
186.Sh RETURN VALUES
187.Fn DSA_generate_parameters_ex
188returns a 1 on success, or 0 otherwise.
189.Pp
190.Fn DSA_generate_parameters
191returns a pointer to the
192.Vt DSA
193structure, or
194.Dv NULL
195if the parameter generation fails.
196.Pp
197The 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_get0_pqg 3 ,
202.Xr DSA_new 3
203.Sh HISTORY
204.Fn DSA_generate_parameters
205first appeared in SSLeay 0.8.0 and had its
206.Fa cb_arg
207argument added in SSLeay 0.9.0.
208It has been available since
209.Ox 2.4 .
210.Pp
211In versions up to OpenSSL 0.9.4,
212.Fn callback 1 ...\&
213was called in the inner loop of the Miller-Rabin test whenever it
214reached the squaring step (the parameters to
215.Fn callback
216did not reveal how many witnesses had been tested); since OpenSSL 0.9.5,
217.Fn callback 1 ...\&
218is called as in
219.Xr BN_is_prime 3 ,
220i.e. once for each witness.
221.Pp
222.Fn DSA_generate_parameters_ex
223first appeared in OpenSSL 0.9.8 and has been available since
224.Ox 4.5 .
225.Sh BUGS
226Seed lengths > 20 are not supported.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-14 01:31:32 +0000