diff options
-rw-r--r-- | doc/build.info | 6 | ||||
-rw-r--r-- | doc/man3/ECDSA_SIG_new.pod | 193 | ||||
-rw-r--r-- | doc/man3/ECDSA_sign.pod | 186 |
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 |