1=pod 2 3=head1 NAME 4 5ECDSA_size, ECDSA_sign, ECDSA_do_sign, 6ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex, 7ECDSA_do_sign_ex - deprecated low-level elliptic curve digital signature algorithm 8(ECDSA) functions 9 10=head1 SYNOPSIS 11 12 #include <openssl/ecdsa.h> 13 14The following functions have been deprecated since OpenSSL 3.0, and can be 15hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 16see L<openssl_user_macros(7)>: 17 18 int ECDSA_size(const EC_KEY *eckey); 19 20 int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, 21 unsigned char *sig, unsigned int *siglen, EC_KEY *eckey); 22 ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len, 23 EC_KEY *eckey); 24 25 int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, 26 const unsigned char *sig, int siglen, EC_KEY *eckey); 27 int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, 28 const ECDSA_SIG *sig, EC_KEY* eckey); 29 30 ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, 31 const BIGNUM *kinv, const BIGNUM *rp, 32 EC_KEY *eckey); 33 int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp); 34 int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen, 35 unsigned char *sig, unsigned int *siglen, 36 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey); 37 38=head1 DESCRIPTION 39 40See L<ECDSA_SIG_new(3)> for a description of the B<ECDSA_SIG> object. 41 42See L<i2d_ECDSA_SIG(3)> and L<d2i_ECDSA_SIG(3)> for information about encoding 43and decoding ECDSA signatures to/from DER. 44 45All of the functions described below are deprecated. Applications should 46use the higher level B<EVP> interface such as L<EVP_DigestSignInit(3)> 47or L<EVP_DigestVerifyInit(3)> instead. 48 49ECDSA_size() returns the maximum length of a DER encoded ECDSA signature 50created with the private EC key I<eckey>. To obtain the actual signature 51size use L<EVP_PKEY_sign(3)> with a NULL I<sig> parameter. 52 53ECDSA_sign() computes a digital signature of the I<dgstlen> bytes hash value 54I<dgst> using the private EC key I<eckey>. The DER encoded signatures is 55stored in I<sig> and its length is returned in I<sig_len>. Note: I<sig> must 56point to ECDSA_size(eckey) bytes of memory. The parameter I<type> is currently 57ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with I<kinv> 58and I<rp> set to NULL. 59 60ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned 61as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign() 62is a wrapper function for ECDSA_do_sign_ex() with I<kinv> and I<rp> set to 63NULL. 64 65ECDSA_verify() verifies that the signature in I<sig> of size I<siglen> is a 66valid ECDSA signature of the hash value I<dgst> of size I<dgstlen> using the 67public key I<eckey>. The parameter I<type> is ignored. 68 69ECDSA_do_verify() is similar to ECDSA_verify() except the signature is 70presented in the form of a pointer to an B<ECDSA_SIG> structure. 71 72The remaining functions utilise the internal I<kinv> and I<r> values used 73during signature computation. Most applications will never need to call these 74and some external ECDSA ENGINE implementations may not support them at all if 75either I<kinv> or I<r> is not NULL. 76 77ECDSA_sign_setup() may be used to precompute parts of the signing operation. 78I<eckey> is the private EC key and I<ctx> is a pointer to B<BN_CTX> structure 79(or NULL). The precomputed values or returned in I<kinv> and I<rp> and can be 80used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex(). 81 82ECDSA_sign_ex() computes a digital signature of the I<dgstlen> bytes hash value 83I<dgst> using the private EC key I<eckey> and the optional pre-computed values 84I<kinv> and I<rp>. The DER encoded signature is stored in I<sig> and its 85length is returned in I<sig_len>. Note: I<sig> must point to ECDSA_size(eckey) 86bytes of memory. The parameter I<type> is ignored. 87 88ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is 89returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error). 90 91=head1 RETURN VALUES 92 93ECDSA_size() returns the maximum length signature or 0 on error. 94 95ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful 96or 0 on error. 97 98ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated 99B<ECDSA_SIG> structure or NULL on error. 100 101ECDSA_verify() and ECDSA_do_verify() return 1 for a valid 102signature, 0 for an invalid signature and -1 on error. 103The error codes can be obtained by L<ERR_get_error(3)>. 104 105=head1 EXAMPLES 106 107Creating an ECDSA signature of a given SHA-256 hash value using the 108named curve prime256v1 (aka P-256). 109This example uses deprecated functionality. See L</DESCRIPTION>. 110 111First step: create an EC_KEY object (note: this part is B<not> ECDSA 112specific) 113 114 int ret; 115 ECDSA_SIG *sig; 116 EC_KEY *eckey; 117 118 eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); 119 if (eckey == NULL) 120 /* error */ 121 if (EC_KEY_generate_key(eckey) == 0) 122 /* error */ 123 124Second step: compute the ECDSA signature of a SHA-256 hash value 125using ECDSA_do_sign(): 126 127 sig = ECDSA_do_sign(digest, 32, eckey); 128 if (sig == NULL) 129 /* error */ 130 131or using ECDSA_sign(): 132 133 unsigned char *buffer, *pp; 134 int buf_len; 135 136 buf_len = ECDSA_size(eckey); 137 buffer = OPENSSL_malloc(buf_len); 138 pp = buffer; 139 if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) 140 /* error */ 141 142Third step: verify the created ECDSA signature using ECDSA_do_verify(): 143 144 ret = ECDSA_do_verify(digest, 32, sig, eckey); 145 146or using ECDSA_verify(): 147 148 ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey); 149 150and finally evaluate the return value: 151 152 if (ret == 1) 153 /* signature ok */ 154 else if (ret == 0) 155 /* incorrect signature */ 156 else 157 /* error */ 158 159=head1 CONFORMING TO 160 161ANSI X9.62, US Federal Information Processing Standard FIPS186-2 162(Digital Signature Standard, DSS) 163 164=head1 SEE ALSO 165 166L<EC_KEY_new(3)>, 167L<EVP_DigestSignInit(3)>, 168L<EVP_DigestVerifyInit(3)>, 169L<EVP_PKEY_sign(3)> 170L<i2d_ECDSA_SIG(3)>, 171L<d2i_ECDSA_SIG(3)> 172 173=head1 HISTORY 174 175All functionality described here was deprecated in OpenSSL 3.0. 176 177=head1 COPYRIGHT 178 179Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved. 180 181Licensed under the Apache License 2.0 (the "License"). You may not use 182this file except in compliance with the License. You can obtain a copy 183in the file LICENSE in the source distribution or at 184L<https://www.openssl.org/source/license.html>. 185 186=cut 187