From 66c749efc0f32a6add489c4c641a5d26d2ed0bef Mon Sep 17 00:00:00 2001 From: tb Date: Fri, 29 Dec 2023 19:12:46 +0000 Subject: [PATCH] Adjust documentation for upcoming DSA_generate_parameters removal This removes any mention of DSA_generate_parameters in the manuals apart from a comment that it is intentionally undocumented and adapts cross references to DSA_generate_parameters_ex. The file itself will be moved in a second step. --- lib/libcrypto/man/BN_generate_prime.3 | 6 +- lib/libcrypto/man/DSA_generate_key.3 | 6 +- lib/libcrypto/man/DSA_generate_parameters.3 | 64 ++------------------- lib/libcrypto/man/DSA_get0_pqg.3 | 5 +- lib/libcrypto/man/DSA_new.3 | 6 +- 5 files changed, 17 insertions(+), 70 deletions(-) diff --git a/lib/libcrypto/man/BN_generate_prime.3 b/lib/libcrypto/man/BN_generate_prime.3 index a7551390ece..d9144155c6e 100644 --- a/lib/libcrypto/man/BN_generate_prime.3 +++ b/lib/libcrypto/man/BN_generate_prime.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BN_generate_prime.3,v 1.24 2023/05/12 08:18:13 jsg Exp $ +.\" $OpenBSD: BN_generate_prime.3,v 1.25 2023/12/29 19:12:46 tb Exp $ .\" full merge up to: OpenSSL f987a4dd Jun 27 10:12:08 2019 +0200 .\" .\" This file is a derived work. @@ -67,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: May 12 2023 $ +.Dd $Mdocdate: December 29 2023 $ .Dt BN_GENERATE_PRIME 3 .Os .Sh NAME @@ -354,7 +354,7 @@ In some cases, error codes can be obtained by .Sh SEE ALSO .Xr BN_new 3 , .Xr DH_generate_parameters 3 , -.Xr DSA_generate_parameters 3 , +.Xr DSA_generate_parameters_ex 3 , .Xr RSA_generate_key 3 .Sh HISTORY .Fn BN_generate_prime_ex , diff --git a/lib/libcrypto/man/DSA_generate_key.3 b/lib/libcrypto/man/DSA_generate_key.3 index 97e185e0b54..37d8ec1c0f7 100644 --- a/lib/libcrypto/man/DSA_generate_key.3 +++ b/lib/libcrypto/man/DSA_generate_key.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: DSA_generate_key.3,v 1.10 2019/06/10 14:58:48 schwarze Exp $ +.\" $OpenBSD: DSA_generate_key.3,v 1.11 2023/12/29 19:12:47 tb Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: December 29 2023 $ .Dt DSA_GENERATE_KEY 3 .Os .Sh NAME @@ -75,7 +75,7 @@ returns 1 on success or 0 otherwise. The error codes can be obtained by .Xr ERR_get_error 3 . .Sh SEE ALSO -.Xr DSA_generate_parameters 3 , +.Xr DSA_generate_parameters_ex 3 , .Xr DSA_get0_key 3 , .Xr DSA_new 3 .Sh HISTORY diff --git a/lib/libcrypto/man/DSA_generate_parameters.3 b/lib/libcrypto/man/DSA_generate_parameters.3 index 07fa5acf930..bba6f9a5667 100644 --- a/lib/libcrypto/man/DSA_generate_parameters.3 +++ b/lib/libcrypto/man/DSA_generate_parameters.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: DSA_generate_parameters.3,v 1.13 2023/05/14 09:27:15 tb Exp $ +.\" $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 , @@ -49,12 +49,13 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: May 14 2023 $ -.Dt DSA_GENERATE_PARAMETERS 3 +.Dd $Mdocdate: December 29 2023 $ +.Dt DSA_GENERATE_PARAMETERS_EX 3 .Os .Sh NAME -.Nm DSA_generate_parameters_ex , -.Nm DSA_generate_parameters +.\" .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 @@ -68,19 +69,6 @@ .Fa "unsigned long *h_ret" .Fa "BN_GENCB *cb" .Fc -.Pp -Deprecated: -.Pp -.Ft DSA * -.Fo DSA_generate_parameters -.Fa "int bits" -.Fa "unsigned char *seed" -.Fa "int seed_len" -.Fa "int *counter_ret" -.Fa "unsigned long *h_ret" -.Fa "void (*callback)(int, int, void *)" -.Fa "void *cb_arg" -.Fc .Sh DESCRIPTION .Fn DSA_generate_parameters_ex generates primes p and q and a generator g for use in the DSA and stores @@ -168,32 +156,10 @@ When the generator has been found, .Fn BN_GENCB_call cb 3 1 is called. .El -.Pp -.Fn DSA_generate_parameters -(deprecated) works in much the same way as for -.Fn DSA_generate_parameters_ex , -except that no -.Fa dsa -parameter is passed and instead a newly allocated -.Vt DSA -structure is returned. -Additionally "old style" callbacks are used instead of the newer -.Vt BN_GENCB -based approach. -Refer to -.Xr BN_generate_prime 3 -for further information. .Sh RETURN VALUES .Fn DSA_generate_parameters_ex returns a 1 on success, or 0 otherwise. .Pp -.Fn DSA_generate_parameters -returns a pointer to the -.Vt DSA -structure, or -.Dv NULL -if the parameter generation fails. -.Pp The error codes can be obtained by .Xr ERR_get_error 3 . .Sh SEE ALSO @@ -201,24 +167,6 @@ The error codes can be obtained by .Xr DSA_get0_pqg 3 , .Xr DSA_new 3 .Sh HISTORY -.Fn DSA_generate_parameters -first appeared in SSLeay 0.8.0 and had its -.Fa cb_arg -argument added in SSLeay 0.9.0. -It has been available since -.Ox 2.4 . -.Pp -In versions up to OpenSSL 0.9.4, -.Fn callback 1 ...\& -was called in the inner loop of the Miller-Rabin test whenever it -reached the squaring step (the parameters to -.Fn callback -did not reveal how many witnesses had been tested); since OpenSSL 0.9.5, -.Fn callback 1 ...\& -is called as in -.Xr BN_is_prime_ex 3 , -i.e. once for each witness. -.Pp .Fn DSA_generate_parameters_ex first appeared in OpenSSL 0.9.8 and has been available since .Ox 4.5 . diff --git a/lib/libcrypto/man/DSA_get0_pqg.3 b/lib/libcrypto/man/DSA_get0_pqg.3 index b5250d9f989..68c2e7fdec2 100644 --- a/lib/libcrypto/man/DSA_get0_pqg.3 +++ b/lib/libcrypto/man/DSA_get0_pqg.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: DSA_get0_pqg.3,v 1.7 2023/03/07 06:15:07 tb Exp $ +.\" $OpenBSD: DSA_get0_pqg.3,v 1.8 2023/12/29 19:12:47 tb Exp $ .\" full merge up to: OpenSSL e90fc053 Jul 15 09:39:45 2017 -0400 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 7 2023 $ +.Dd $Mdocdate: December 29 2023 $ .Dt DSA_GET0_PQG 3 .Os .Sh NAME @@ -296,7 +296,6 @@ if no engine was set for this object. .Xr DSA_do_sign 3 , .Xr DSA_dup_DH 3 , .Xr DSA_generate_key 3 , -.Xr DSA_generate_parameters 3 , .Xr DSA_new 3 , .Xr DSA_print 3 , .Xr DSA_security_bits 3 , diff --git a/lib/libcrypto/man/DSA_new.3 b/lib/libcrypto/man/DSA_new.3 index 8e316011707..5a958b58c4f 100644 --- a/lib/libcrypto/man/DSA_new.3 +++ b/lib/libcrypto/man/DSA_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: DSA_new.3,v 1.13 2022/07/13 21:51:35 schwarze Exp $ +.\" $OpenBSD: DSA_new.3,v 1.14 2023/12/29 19:12:47 tb Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: July 13 2022 $ +.Dd $Mdocdate: December 29 2023 $ .Dt DSA_NEW 3 .Os .Sh NAME @@ -114,7 +114,7 @@ returns 1 for success or 0 for failure. .Xr DSA_do_sign 3 , .Xr DSA_dup_DH 3 , .Xr DSA_generate_key 3 , -.Xr DSA_generate_parameters 3 , +.Xr DSA_generate_parameters_ex 3 , .Xr DSA_get0_pqg 3 , .Xr DSA_get_ex_new_index 3 , .Xr DSA_meth_new 3 , -- 2.20.1