From: tb Date: Fri, 29 Dec 2023 19:15:15 +0000 (+0000) Subject: Move DSA_generate_parameters.3 to DSA_generate_parameters_ex.3 X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=b3d8295f3cd942c6ea4804dc602a677bb68323e4;p=openbsd Move DSA_generate_parameters.3 to DSA_generate_parameters_ex.3 --- diff --git a/lib/libcrypto/man/DSA_generate_parameters.3 b/lib/libcrypto/man/DSA_generate_parameters.3 deleted file mode 100644 index bba6f9a5667..00000000000 --- a/lib/libcrypto/man/DSA_generate_parameters.3 +++ /dev/null @@ -1,174 +0,0 @@ -.\" $OpenBSD: DSA_generate_parameters.3,v 1.14 2023/12/29 19:12:47 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. diff --git a/lib/libcrypto/man/DSA_generate_parameters_ex.3 b/lib/libcrypto/man/DSA_generate_parameters_ex.3 new file mode 100644 index 00000000000..a318bf82988 --- /dev/null +++ b/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. diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 544495207dd..72ddcd34356 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.279 2023/12/16 10:26:10 tb Exp $ +# $OpenBSD: Makefile,v 1.280 2023/12/29 19:15:15 tb Exp $ .include @@ -123,7 +123,7 @@ MAN= \ DSA_do_sign.3 \ DSA_dup_DH.3 \ DSA_generate_key.3 \ - DSA_generate_parameters.3 \ + DSA_generate_parameters_ex.3 \ DSA_get0_pqg.3 \ DSA_get_ex_new_index.3 \ DSA_meth_new.3 \