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