From b7a55ea56653f59eec6d2b26e637b59c9e16d39b Mon Sep 17 00:00:00 2001 From: tb <> Date: Fri, 29 Dec 2023 19:15:15 +0000 Subject: Move DSA_generate_parameters.3 to DSA_generate_parameters_ex.3 --- src/lib/libcrypto/man/DSA_generate_parameters_ex.3 | 174 +++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 src/lib/libcrypto/man/DSA_generate_parameters_ex.3 (limited to 'src/lib/libcrypto/man/DSA_generate_parameters_ex.3') diff --git a/src/lib/libcrypto/man/DSA_generate_parameters_ex.3 b/src/lib/libcrypto/man/DSA_generate_parameters_ex.3 new file mode 100644 index 0000000000..a318bf8298 --- /dev/null +++ b/src/lib/libcrypto/man/DSA_generate_parameters_ex.3 @@ -0,0 +1,174 @@ +.\" $OpenBSD: DSA_generate_parameters_ex.3,v 1.1 2023/12/29 19:15:15 tb Exp $ +.\" OpenSSL 9b86974e Aug 7 22:14:47 2015 -0400 +.\" +.\" This file was written by Ulf Moeller , +.\" Bodo Moeller , and Matt Caswell . +.\" Copyright (c) 2000, 2013 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 29 2023 $ +.Dt DSA_GENERATE_PARAMETERS_EX 3 +.Os +.Sh NAME +.\" .Nm DSA_generate_parameters is intentionally undocumented +.\" because it will be removed in the next major bump +.Nm DSA_generate_parameters_ex +.Nd generate DSA parameters +.Sh SYNOPSIS +.In openssl/dsa.h +.Ft int +.Fo DSA_generate_parameters_ex +.Fa "DSA *dsa" +.Fa "int bits" +.Fa "const unsigned char *seed" +.Fa "int seed_len" +.Fa "int *counter_ret" +.Fa "unsigned long *h_ret" +.Fa "BN_GENCB *cb" +.Fc +.Sh DESCRIPTION +.Fn DSA_generate_parameters_ex +generates primes p and q and a generator g for use in the DSA and stores +the result in +.Fa dsa . +.Pp +.Fa bits +is the length of the prime to be generated; the DSS allows a maximum of +1024 bits. +.Pp +If +.Fa seed +is +.Dv NULL +or +.Fa seed_len +< 20, the primes will be generated at random. +Otherwise, the seed is used to generate them. +If the given seed does not yield a prime q, a new random seed is chosen +and placed at +.Fa seed . +.Pp +.Fn DSA_generate_parameters_ex +places the iteration count in +.Pf * Fa counter_ret +and a counter used for finding a generator in +.Pf * Fa h_ret , +unless these are +.Dv NULL . +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as shown below. +For information on the +.Vt BN_GENCB +structure, refer to +.Xr BN_GENCB_call 3 . +.Bl -bullet +.It +When a candidate for q is generated, +.Fn BN_GENCB_call cb 0 m++ +is called +.Pf ( Fa m +is 0 for the first candidate). +.It +When a candidate for q has passed a test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While a candidate for q is tested by Miller-Rabin primality tests, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime); +.Fa i +is the loop counter (starting at 0). +.It +When a prime q has been found, +.Fn BN_GENCB_call cb 2 0 +and +.Fn BN_GENCB_call cb 3 0 +are called. +.It +Before a candidate for p (other than the first) is generated and tested, +.Fn BN_GENCB_call cb 0 counter +is called. +.It +When a candidate for p has passed the test by trial division, +.Fn BN_GENCB_call cb 1 -1 +is called. +While it is tested by the Miller-Rabin primality test, +.Fn BN_GENCB_call cb 1 i +is called in the outer loop (once for each witness that confirms that +the candidate may be prime). +.Fa i +is the loop counter (starting at 0). +.It +When p has been found, +.Fn BN_GENCB_call cb 2 1 +is called. +.It +When the generator has been found, +.Fn BN_GENCB_call cb 3 1 +is called. +.El +.Sh RETURN VALUES +.Fn DSA_generate_parameters_ex +returns a 1 on success, or 0 otherwise. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_generate_prime 3 , +.Xr DSA_get0_pqg 3 , +.Xr DSA_new 3 +.Sh HISTORY +.Fn DSA_generate_parameters_ex +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh BUGS +Seed lengths > 20 are not supported. -- cgit v1.2.3-55-g6feb