Docs: Move deprecated ECDSA_ functions into a separate file.

Fixes #19829

Examples added for setting/getting ECDSA SIG related r and s values

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19936)

(cherry picked from commit c99209264de98da94937b073a42219bada9ff7f5)

3 files changed, 251 insertions, 134 deletions

diff --git a/doc/build.info b/doc/build.info
index cf89694a65..6f3039d0e4 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -991,6 +991,10 @@ DEPEND[html/man3/ECDSA_SIG_new.html]=man3/ECDSA_SIG_new.pod
 GENERATE[html/man3/ECDSA_SIG_new.html]=man3/ECDSA_SIG_new.pod
 DEPEND[man/man3/ECDSA_SIG_new.3]=man3/ECDSA_SIG_new.pod
 GENERATE[man/man3/ECDSA_SIG_new.3]=man3/ECDSA_SIG_new.pod
+DEPEND[html/man3/ECDSA_sign.html]=man3/ECDSA_sign.pod
+GENERATE[html/man3/ECDSA_sign.html]=man3/ECDSA_sign.pod
+DEPEND[man/man3/ECDSA_sign.3]=man3/ECDSA_sign.pod
+GENERATE[man/man3/ECDSA_sign.3]=man3/ECDSA_sign.pod
 DEPEND[html/man3/ECPKParameters_print.html]=man3/ECPKParameters_print.pod
 GENERATE[html/man3/ECPKParameters_print.html]=man3/ECPKParameters_print.pod
 DEPEND[man/man3/ECPKParameters_print.3]=man3/ECPKParameters_print.pod
@@ -2999,6 +3003,7 @@ html/man3/DTLS_get_data_mtu.html \
 html/man3/DTLS_set_timer_cb.html \
 html/man3/DTLSv1_listen.html \
 html/man3/ECDSA_SIG_new.html \
+html/man3/ECDSA_sign.html \
 html/man3/ECPKParameters_print.html \
 html/man3/EC_GFp_simple_method.html \
 html/man3/EC_GROUP_copy.html \
@@ -3599,6 +3604,7 @@ man/man3/DTLS_get_data_mtu.3 \
 man/man3/DTLS_set_timer_cb.3 \
 man/man3/DTLSv1_listen.3 \
 man/man3/ECDSA_SIG_new.3 \
+man/man3/ECDSA_sign.3 \
 man/man3/ECPKParameters_print.3 \
 man/man3/EC_GFp_simple_method.3 \
 man/man3/EC_GROUP_copy.3 \
diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod
index 00c611251e..3266c43b55 100644
--- a/doc/man3/ECDSA_SIG_new.pod
+++ b/doc/man3/ECDSA_SIG_new.pod
@@ -2,11 +2,9 @@
 
 =head1 NAME
 
-ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0,
-ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_size, ECDSA_sign, ECDSA_do_sign,
-ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
-ECDSA_do_sign_ex - low-level elliptic curve digital signature algorithm (ECDSA)
-functions
+ECDSA_SIG_new, ECDSA_SIG_free,
+ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0
+- Functions for creating, destroying and manipulating ECDSA_SIG objects
 
 =head1 SYNOPSIS
 
@@ -19,37 +17,18 @@ functions
  const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);
  int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
 
-The following functions have been deprecated since OpenSSL 3.0, and can be
-hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
-see L<openssl_user_macros(7)>:
-
- int ECDSA_size(const EC_KEY *eckey);
-
- int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
-                unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
- ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
-                          EC_KEY *eckey);
-
- int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
-                  const unsigned char *sig, int siglen, EC_KEY *eckey);
- int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
-                     const ECDSA_SIG *sig, EC_KEY* eckey);
-
- ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
-                             const BIGNUM *kinv, const BIGNUM *rp,
-                             EC_KEY *eckey);
- int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
- int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
-                   unsigned char *sig, unsigned int *siglen,
-                   const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
-
 =head1 DESCRIPTION
 
 B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
-I<r> and I<s> value of an ECDSA signature (see X9.62 or FIPS186-2).
+I<r> and I<s> value of an Elliptic Curve Digital Signature Algorithm (ECDSA) signature
+(see FIPS186-4 or X9.62).
+The B<ECDSA_SIG> object was mainly used by the deprecated low level functions described in
+L<ECDSA_sign(3)>, it is still required in order to be able to set or get the values of
+I<r> and I<s> into or from a signature. This is mainly used for testing purposes as shown
+in the L</EXAMPLES>.
 
-ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before
-OpenSSL 1.1.0 the: the I<r> and I<s> components were initialised.
+ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure.
+Note: before OpenSSL 1.1.0, the I<r> and I<s> components were initialised.
 
 ECDSA_SIG_free() frees the B<ECDSA_SIG> structure I<sig>.
 
@@ -69,52 +48,6 @@ passed in should not be freed by the caller.
 See L<i2d_ECDSA_SIG(3)> and L<d2i_ECDSA_SIG(3)> for information about encoding
 and decoding ECDSA signatures to/from DER.
 
-All of the functions described below are deprecated. Applications should
-use the higher level B<EVP> interface such as L<EVP_DigestSignInit(3)>
-or L<EVP_DigestVerifyInit(3)> instead.
-
-ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
-created with the private EC key I<eckey>. To obtain the actual signature
-size use L<EVP_PKEY_sign(3)> with a NULL I<sig> parameter.
-
-ECDSA_sign() computes a digital signature of the I<dgstlen> bytes hash value
-I<dgst> using the private EC key I<eckey>. The DER encoded signatures is
-stored in I<sig> and its length is returned in I<sig_len>. Note: I<sig> must
-point to ECDSA_size(eckey) bytes of memory. The parameter I<type> is currently
-ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with I<kinv>
-and I<rp> set to NULL.
-
-ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned
-as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign()
-is a wrapper function for ECDSA_do_sign_ex() with I<kinv> and I<rp> set to
-NULL.
-
-ECDSA_verify() verifies that the signature in I<sig> of size I<siglen> is a
-valid ECDSA signature of the hash value I<dgst> of size I<dgstlen> using the
-public key I<eckey>.  The parameter I<type> is ignored.
-
-ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
-presented in the form of a pointer to an B<ECDSA_SIG> structure.
-
-The remaining functions utilise the internal I<kinv> and I<r> values used
-during signature computation. Most applications will never need to call these
-and some external ECDSA ENGINE implementations may not support them at all if
-either I<kinv> or I<r> is not NULL.
-
-ECDSA_sign_setup() may be used to precompute parts of the signing operation.
-I<eckey> is the private EC key and I<ctx> is a pointer to B<BN_CTX> structure
-(or NULL). The precomputed values or returned in I<kinv> and I<rp> and can be
-used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
-
-ECDSA_sign_ex() computes a digital signature of the I<dgstlen> bytes hash value
-I<dgst> using the private EC key I<eckey> and the optional pre-computed values
-I<kinv> and I<rp>. The DER encoded signature is stored in I<sig> and its
-length is returned in I<sig_len>. Note: I<sig> must point to ECDSA_size(eckey)
-bytes of memory. The parameter I<type> is ignored.
-
-ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is
-returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
-
 =head1 RETURN VALUES
 
 ECDSA_SIG_new() returns NULL if the allocation fails.
@@ -124,74 +57,71 @@ ECDSA_SIG_set0() returns 1 on success or 0 on failure.
 ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s() return the corresponding value,
 or NULL if it is unset.
 
-ECDSA_size() returns the maximum length signature or 0 on error.
-
-ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
-or 0 on error.
-
-ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
-B<ECDSA_SIG> structure or NULL on error.
-
-ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
-signature, 0 for an invalid signature and -1 on error.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
 =head1 EXAMPLES
 
-Creating an ECDSA signature of a given SHA-256 hash value using the
-named curve prime256v1 (aka P-256).
+Extract signature I<r> and I<s> values from a ECDSA I<signature>
+of size I<signaturelen>:
 
-First step: create an EC_KEY object (note: this part is B<not> ECDSA
-specific)
+ ECDSA_SIG *obj;
+ const BIGNUM *r, *s;
 
- int ret;
- ECDSA_SIG *sig;
- EC_KEY *eckey;
-
- eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
- if (eckey == NULL)
-     /* error */
- if (EC_KEY_generate_key(eckey) == 0)
+ /* Load a signature into the ECDSA_SIG object */
+ obj = d2i_ECDSA_SIG(NULL, &signature, signaturelen);
+ if (obj == NULL)
      /* error */
 
-Second step: compute the ECDSA signature of a SHA-256 hash value
-using ECDSA_do_sign():
-
- sig = ECDSA_do_sign(digest, 32, eckey);
- if (sig == NULL)
+ r = ECDSA_SIG_get0_r(obj);
+ s = ECDSA_SIG_get0_s(obj);
+ if (r == NULL || s == NULL)
      /* error */
 
-or using ECDSA_sign():
+ /* Use BN_bn2binpad() here to convert to r and s into byte arrays */
 
- unsigned char *buffer, *pp;
- int buf_len;
+ /*
+  * Do not try to access I<r> or I<s> after calling ECDSA_SIG_free(),
+  * as they are both freed by this call.
+  */
+ ECDSA_SIG_free(obj);
 
- buf_len = ECDSA_size(eckey);
- buffer = OPENSSL_malloc(buf_len);
- pp = buffer;
- if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)
-     /* error */
+Convert I<r> and I<s> byte arrays into an ECDSA_SIG I<signature> of
+size I<signaturelen>:
 
-Third step: verify the created ECDSA signature using ECDSA_do_verify():
+ ECDSA_SIG *obj = NULL;
+ unsigned char *signature = NULL;
+ size_t signaturelen;
+ BIGNUM *rbn = NULL, *sbn = NULL;
 
- ret = ECDSA_do_verify(digest, 32, sig, eckey);
+ obj = ECDSA_SIG_new();
+ if (obj == NULL)
+     /* error */
+ rbn = BN_bin2bn(r, rlen, NULL);
+ sbn = BN_bin2bn(s, slen, NULL);
+ if (rbn == NULL || sbn == NULL)
+     /* error */
 
-or using ECDSA_verify():
+ if (!ECDSA_SIG_set0(obj, rbn, sbn))
+     /* error */
+ /* Set these to NULL since they are now owned by obj */
+ rbn = sbn = NULL;
 
- ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
+ signaturelen = i2d_ECDSA_SIG(obj, &signature);
+ if (signaturelen <= 0)
+     /* error */
 
-and finally evaluate the return value:
+ /*
+  * This signature could now be passed to L<EVP_DigestVerify(3)>
+  * or L<EVP_DigestVerifyFinal(3)>
+  */
 
- if (ret == 1)
-     /* signature ok */
- else if (ret == 0)
-     /* incorrect signature */
- else
-     /* error */
+ BN_free(rbn);
+ BN_free(sbn);
+ OPENSSL_free(signature);
+ ECDSA_SIG_free(obj);
 
 =head1 CONFORMING TO
 
-ANSI X9.62, US Federal Information Processing Standard FIPS186-2
+ANSI X9.62,
+US Federal Information Processing Standard FIPS186-4
 (Digital Signature Standard, DSS)
 
 =head1 SEE ALSO
@@ -201,13 +131,8 @@ L<EVP_DigestSignInit(3)>,
 L<EVP_DigestVerifyInit(3)>,
 L<EVP_PKEY_sign(3)>
 L<i2d_ECDSA_SIG(3)>,
-L<d2i_ECDSA_SIG(3)>
-
-=head1 HISTORY
-
-The ECDSA_size(), ECDSA_sign(), ECDSA_do_sign(), ECDSA_verify(),
-ECDSA_do_verify(), ECDSA_sign_setup(), ECDSA_sign_ex() and ECDSA_do_sign_ex()
-functions were deprecated in OpenSSL 3.0.
+L<d2i_ECDSA_SIG(3)>,
+L<ECDSA_sign(3)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/ECDSA_sign.pod b/doc/man3/ECDSA_sign.pod
new file mode 100644
index 0000000000..7e56466653
--- /dev/null
+++ b/doc/man3/ECDSA_sign.pod
@@ -0,0 +1,186 @@
+=pod
+
+=head1 NAME
+
+ECDSA_size, ECDSA_sign, ECDSA_do_sign,
+ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
+ECDSA_do_sign_ex - deprecated low-level elliptic curve digital signature algorithm
+(ECDSA) functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ecdsa.h>
+
+The following functions have been deprecated since OpenSSL 3.0, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
+
+ int ECDSA_size(const EC_KEY *eckey);
+
+ int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
+                unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
+ ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
+                          EC_KEY *eckey);
+
+ int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
+                  const unsigned char *sig, int siglen, EC_KEY *eckey);
+ int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
+                     const ECDSA_SIG *sig, EC_KEY* eckey);
+
+ ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
+                             const BIGNUM *kinv, const BIGNUM *rp,
+                             EC_KEY *eckey);
+ int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
+ int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
+                   unsigned char *sig, unsigned int *siglen,
+                   const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
+
+=head1 DESCRIPTION
+
+See L<ECDSA_SIG_new(3)> for a description of the B<ECDSA_SIG> object.
+
+See L<i2d_ECDSA_SIG(3)> and L<d2i_ECDSA_SIG(3)> for information about encoding
+and decoding ECDSA signatures to/from DER.
+
+All of the functions described below are deprecated. Applications should
+use the higher level B<EVP> interface such as L<EVP_DigestSignInit(3)>
+or L<EVP_DigestVerifyInit(3)> instead.
+
+ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
+created with the private EC key I<eckey>. To obtain the actual signature
+size use L<EVP_PKEY_sign(3)> with a NULL I<sig> parameter.
+
+ECDSA_sign() computes a digital signature of the I<dgstlen> bytes hash value
+I<dgst> using the private EC key I<eckey>. The DER encoded signatures is
+stored in I<sig> and its length is returned in I<sig_len>. Note: I<sig> must
+point to ECDSA_size(eckey) bytes of memory. The parameter I<type> is currently
+ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with I<kinv>
+and I<rp> set to NULL.
+
+ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned
+as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign()
+is a wrapper function for ECDSA_do_sign_ex() with I<kinv> and I<rp> set to
+NULL.
+
+ECDSA_verify() verifies that the signature in I<sig> of size I<siglen> is a
+valid ECDSA signature of the hash value I<dgst> of size I<dgstlen> using the
+public key I<eckey>.  The parameter I<type> is ignored.
+
+ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
+presented in the form of a pointer to an B<ECDSA_SIG> structure.
+
+The remaining functions utilise the internal I<kinv> and I<r> values used
+during signature computation. Most applications will never need to call these
+and some external ECDSA ENGINE implementations may not support them at all if
+either I<kinv> or I<r> is not NULL.
+
+ECDSA_sign_setup() may be used to precompute parts of the signing operation.
+I<eckey> is the private EC key and I<ctx> is a pointer to B<BN_CTX> structure
+(or NULL). The precomputed values or returned in I<kinv> and I<rp> and can be
+used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
+
+ECDSA_sign_ex() computes a digital signature of the I<dgstlen> bytes hash value
+I<dgst> using the private EC key I<eckey> and the optional pre-computed values
+I<kinv> and I<rp>. The DER encoded signature is stored in I<sig> and its
+length is returned in I<sig_len>. Note: I<sig> must point to ECDSA_size(eckey)
+bytes of memory. The parameter I<type> is ignored.
+
+ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is
+returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
+
+=head1 RETURN VALUES
+
+ECDSA_size() returns the maximum length signature or 0 on error.
+
+ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
+or 0 on error.
+
+ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
+B<ECDSA_SIG> structure or NULL on error.
+
+ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
+signature, 0 for an invalid signature and -1 on error.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 EXAMPLES
+
+Creating an ECDSA signature of a given SHA-256 hash value using the
+named curve prime256v1 (aka P-256).
+This example uses deprecated functionality. See L</DESCRIPTION>.
+
+First step: create an EC_KEY object (note: this part is B<not> ECDSA
+specific)
+
+ int ret;
+ ECDSA_SIG *sig;
+ EC_KEY *eckey;
+
+ eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
+ if (eckey == NULL)
+     /* error */
+ if (EC_KEY_generate_key(eckey) == 0)
+     /* error */
+
+Second step: compute the ECDSA signature of a SHA-256 hash value
+using ECDSA_do_sign():
+
+ sig = ECDSA_do_sign(digest, 32, eckey);
+ if (sig == NULL)
+     /* error */
+
+or using ECDSA_sign():
+
+ unsigned char *buffer, *pp;
+ int buf_len;
+
+ buf_len = ECDSA_size(eckey);
+ buffer = OPENSSL_malloc(buf_len);
+ pp = buffer;
+ if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)
+     /* error */
+
+Third step: verify the created ECDSA signature using ECDSA_do_verify():
+
+ ret = ECDSA_do_verify(digest, 32, sig, eckey);
+
+or using ECDSA_verify():
+
+ ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
+
+and finally evaluate the return value:
+
+ if (ret == 1)
+     /* signature ok */
+ else if (ret == 0)
+     /* incorrect signature */
+ else
+     /* error */
+
+=head1 CONFORMING TO
+
+ANSI X9.62, US Federal Information Processing Standard FIPS186-2
+(Digital Signature Standard, DSS)
+
+=head1 SEE ALSO
+
+L<EC_KEY_new(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_DigestVerifyInit(3)>,
+L<EVP_PKEY_sign(3)>
+L<i2d_ECDSA_SIG(3)>,
+L<d2i_ECDSA_SIG(3)>
+
+=head1 HISTORY
+
+All functionality described here was deprecated in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut