dsa: documentation deprecation changes

Fixes #13121

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13638)

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<DSA_new(3)>, L<ERR_get_error(3)>,
-L<DSA_do_sign(3)>
+L<EVP_PKEY_new(3)>, L<EVP_PKEY_free(3)>, L<EVP_PKEY_get_bn_param(3)>,
+L<ERR_get_error(3)>
 
 =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 <openssl/dsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  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<EVP_PKEY_get_bn_param(3)>.
+
 A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a
 public key (B<pub_key>) and (optionally) a private key (B<priv_key>).
 
@@ -94,13 +101,15 @@ has been set.
 
 =head1 SEE ALSO
 
+L<EVP_PKEY_get_bn_param(3)>,
 L<DSA_new(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>,
 L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>,
 L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)>
 
 =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 <openssl/dsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  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<EVP_PKEY_new(3)> and L<EVP_PKEY_free(3)>.
+
 DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
 calling DSA_new_method(NULL).
 
@@ -32,10 +39,15 @@ DSA_free() returns no value.
 
 =head1 SEE ALSO
 
+L<EVP_PKEY_new(3)>, L<EVP_PKEY_free(3)>,
 L<DSA_new(3)>, L<ERR_get_error(3)>,
 L<DSA_generate_parameters(3)>,
 L<DSA_generate_key(3)>
 
+=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 <openssl/dsa.h>
 
- int DSA_bits(const DSA *dsa);
-
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
 
+ 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<EVP_PKEY_bits(3)>,
+L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
+
 DSA_bits() returns the number of bits in key I<dsa>: this is the number
 of bits in the I<p> parameter.
 
-The remaining functions described on this page are deprecated.
-Applications should instead use L<EVP_PKEY_security_bits(3)> and
-L<EVP_PKEY_size(3)>.
-
 DSA_size() returns the maximum size of an ASN.1 encoded DSA signature
 for key I<dsa> in bytes. It can be used to determine how much memory must
 be allocated for a DSA signature.
@@ -54,7 +54,7 @@ L<DSA_new(3)>, L<DSA_sign(3)>
 
 =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<i> and B<d> in B<i2d_I<TYPE>>() stand for
+"internal" (that is, an internal C structure) and "DER" respectively.
+So B<i2d_I<TYPE>>() converts from internal to DER.
+
+The functions can also understand B<BER> forms.
+
+The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
+populated B<I<TYPE>> structure -- it B<cannot> 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<not> 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<WARNINGS> 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<DSA_PUBKEY>
+
+Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
+
+=item B<DSAPublicKey>, B<DSAPrivateKey>
+
+Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
+L<PEM_write_PrivateKey(3)>, or similar instead.
+
+=back
+
 =head1 RETURN VALUES
 
 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_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<DSA_PUBKEY>
-
-Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
-
-=item B<DSAPublicKey>, B<DSAPrivateKey>
-
-Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
-L<PEM_write_PrivateKey(3)>, or similar instead.
-
 =item B<ECDSA_SIG>
 
 Represents an ECDSA signature.