From d6fff343c85b1fd1c144690b881bf89aa6d049e6 Mon Sep 17 00:00:00 2001 From: Pauli Date: Tue, 20 Oct 2020 13:31:43 +1000 Subject: [PATCH] dsa: documentation deprecation changes Fixes #13121 Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/13638) --- doc/man3/DSA_SIG_new.pod | 4 +-- doc/man3/DSA_get0_pqg.pod | 11 +++++++- doc/man3/DSA_new.pod | 12 +++++++++ doc/man3/DSA_size.pod | 14 +++++----- doc/man3/d2i_RSAPrivateKey.pod | 47 ++++++++++++++++++++++++++++++++++ doc/man3/d2i_X509.pod | 17 ------------ 6 files changed, 78 insertions(+), 27 deletions(-) diff --git a/doc/man3/DSA_SIG_new.pod b/doc/man3/DSA_SIG_new.pod index ba925ef726..1f532d3000 100644 --- a/doc/man3/DSA_SIG_new.pod +++ b/doc/man3/DSA_SIG_new.pod @@ -43,8 +43,8 @@ DSA_SIG_set0() returns 1 on success or 0 on failure. =head1 SEE ALSO -L, L, -L +L, L, L, +L =head1 COPYRIGHT diff --git a/doc/man3/DSA_get0_pqg.pod b/doc/man3/DSA_get0_pqg.pod index 5aa2c75714..3542a771e9 100644 --- a/doc/man3/DSA_get0_pqg.pod +++ b/doc/man3/DSA_get0_pqg.pod @@ -13,6 +13,10 @@ setting data in a DSA object #include +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B with a suitable version value, see +L: + void DSA_get0_pqg(const DSA *d, const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g); @@ -31,6 +35,9 @@ setting data in a DSA object =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L. + A DSA object contains the parameters B

, B and B. It also contains a public key (B) and (optionally) a private key (B). @@ -94,13 +101,15 @@ has been set. =head1 SEE ALSO +L, L, L, L, L, L, L, L, L, L, L, L =head1 HISTORY -The functions described here were added in OpenSSL 1.1.0. +The functions described here were added in OpenSSL 1.1.0 and deprecated in +OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/DSA_new.pod b/doc/man3/DSA_new.pod index 830c9938b6..0993071d18 100644 --- a/doc/man3/DSA_new.pod +++ b/doc/man3/DSA_new.pod @@ -8,12 +8,19 @@ DSA_new, DSA_free - allocate and free DSA objects #include +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B with a suitable version value, see +L: + DSA* DSA_new(void); void DSA_free(DSA *dsa); =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L and L. + DSA_new() allocates and initializes a B structure. It is equivalent to calling DSA_new_method(NULL). @@ -32,10 +39,15 @@ DSA_free() returns no value. =head1 SEE ALSO +L, L, L, L, L, L +=head1 HISTORY + +All of these functions were deprecated in OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/DSA_size.pod b/doc/man3/DSA_size.pod index 992357c4e0..b904845447 100644 --- a/doc/man3/DSA_size.pod +++ b/doc/man3/DSA_size.pod @@ -8,25 +8,25 @@ DSA_size, DSA_bits, DSA_security_bits - get DSA signature size, key bits or secu #include - int DSA_bits(const DSA *dsa); - Deprecated since OpenSSL 3.0, can be hidden entirely by defining B with a suitable version value, see L: + int DSA_bits(const DSA *dsa); + int DSA_size(const DSA *dsa); int DSA_security_bits(const DSA *dsa); =head1 DESCRIPTION +All of the functions described on this page are deprecated. +Applications should instead use L, +L and L. + DSA_bits() returns the number of bits in key I: this is the number of bits in the I

parameter. -The remaining functions described on this page are deprecated. -Applications should instead use L and -L. - DSA_size() returns the maximum size of an ASN.1 encoded DSA signature for key I in bytes. It can be used to determine how much memory must be allocated for a DSA signature. @@ -54,7 +54,7 @@ L, L =head1 HISTORY -The DSA_size() and DSA_security_bits() functions were deprecated in OpenSSL 3.0. +All of these functions were deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/d2i_RSAPrivateKey.pod b/doc/man3/d2i_RSAPrivateKey.pod index 7827b3cef4..7375f1bab3 100644 --- a/doc/man3/d2i_RSAPrivateKey.pod +++ b/doc/man3/d2i_RSAPrivateKey.pod @@ -8,6 +8,14 @@ Any deprecated keypair/params d2i or i2d functions are collected on this page. =head1 NAME +d2i_DSAPrivateKey, +d2i_DSAPrivateKey_bio, +d2i_DSAPrivateKey_fp, +d2i_DSAPublicKey, +d2i_DSA_PUBKEY, +d2i_DSA_PUBKEY_bio, +d2i_DSA_PUBKEY_fp, +d2i_DSAparams, d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, @@ -215,6 +223,45 @@ The following sample code does the rest of the work: =for comment TODO: a similar section on OSSL_DECODER is to be added +=head1 NOTES + +The letters B and B in B>() stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So B>() converts from internal to DER. + +The functions can also understand B forms. + +The actual TYPE structure passed to B>() must be a valid +populated B> structure -- it B simply be fed with an +empty structure such as that returned by TYPE_new(). + +The encoded data is in binary form and may contain embedded zeros. +Therefore, any FILE pointers or BIOs should be opened in binary mode. +Functions such as strlen() will B return the correct length +of the encoded structure. + +The ways that I<*ppin> and I<*ppout> are incremented after the operation +can trap the unwary. See the B section for some common +errors. +The reason for this-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. + +The following points about the data types might be useful: + +=over 4 + +=item B + +Represents a DSA public key using a B structure. + +=item B, B + +Use a non-standard OpenSSL format and should be avoided; use B, +L, or similar instead. + +=back + =head1 RETURN VALUES B>(), B_bio>() and B_fp>() return a valid diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 0b3414ba8f..d5c684e31d 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -51,15 +51,7 @@ d2i_DIRECTORYSTRING, d2i_DISPLAYTEXT, d2i_DIST_POINT, d2i_DIST_POINT_NAME, -d2i_DSAPrivateKey, -d2i_DSAPrivateKey_bio, -d2i_DSAPrivateKey_fp, -d2i_DSAPublicKey, -d2i_DSA_PUBKEY, -d2i_DSA_PUBKEY_bio, -d2i_DSA_PUBKEY_fp, d2i_DSA_SIG, -d2i_DSAparams, d2i_ECDSA_SIG, d2i_ECPKParameters, d2i_ECParameters, @@ -488,15 +480,6 @@ Represents a PKCS#3 DH parameters structure. Represents an ANSI X9.42 DH parameters structure. -=item B - -Represents a DSA public key using a B structure. - -=item B, B - -Use a non-standard OpenSSL format and should be avoided; use B, -L, or similar instead. - =item B Represents an ECDSA signature.