1160814Ssimon=pod 2160814Ssimon 3160814Ssimon=head1 NAME 4160814Ssimon 5160814Ssimonecdsa - Elliptic Curve Digital Signature Algorithm 6160814Ssimon 7160814Ssimon=head1 SYNOPSIS 8160814Ssimon 9160814Ssimon #include <openssl/ecdsa.h> 10160814Ssimon 11160814Ssimon ECDSA_SIG* ECDSA_SIG_new(void); 12160814Ssimon void ECDSA_SIG_free(ECDSA_SIG *sig); 13160814Ssimon int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); 14160814Ssimon ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, 15160814Ssimon long len); 16160814Ssimon 17160814Ssimon ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, 18160814Ssimon EC_KEY *eckey); 19160814Ssimon ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, 20160814Ssimon const BIGNUM *kinv, const BIGNUM *rp, 21160814Ssimon EC_KEY *eckey); 22160814Ssimon int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, 23160814Ssimon const ECDSA_SIG *sig, EC_KEY* eckey); 24160814Ssimon int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, 25160814Ssimon BIGNUM **kinv, BIGNUM **rp); 26160814Ssimon int ECDSA_sign(int type, const unsigned char *dgst, 27160814Ssimon int dgstlen, unsigned char *sig, 28160814Ssimon unsigned int *siglen, EC_KEY *eckey); 29160814Ssimon int ECDSA_sign_ex(int type, const unsigned char *dgst, 30160814Ssimon int dgstlen, unsigned char *sig, 31160814Ssimon unsigned int *siglen, const BIGNUM *kinv, 32160814Ssimon const BIGNUM *rp, EC_KEY *eckey); 33160814Ssimon int ECDSA_verify(int type, const unsigned char *dgst, 34160814Ssimon int dgstlen, const unsigned char *sig, 35160814Ssimon int siglen, EC_KEY *eckey); 36160814Ssimon int ECDSA_size(const EC_KEY *eckey); 37160814Ssimon 38160814Ssimon const ECDSA_METHOD* ECDSA_OpenSSL(void); 39160814Ssimon void ECDSA_set_default_method(const ECDSA_METHOD *meth); 40160814Ssimon const ECDSA_METHOD* ECDSA_get_default_method(void); 41160814Ssimon int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); 42160814Ssimon 43160814Ssimon int ECDSA_get_ex_new_index(long argl, void *argp, 44160814Ssimon CRYPTO_EX_new *new_func, 45160814Ssimon CRYPTO_EX_dup *dup_func, 46160814Ssimon CRYPTO_EX_free *free_func); 47160814Ssimon int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); 48160814Ssimon void* ECDSA_get_ex_data(EC_KEY *d, int idx); 49160814Ssimon 50160814Ssimon=head1 DESCRIPTION 51160814Ssimon 52160814SsimonThe B<ECDSA_SIG> structure consists of two BIGNUMs for the 53160814Ssimonr and s value of a ECDSA signature (see X9.62 or FIPS 186-2). 54160814Ssimon 55160814Ssimon struct 56160814Ssimon { 57160814Ssimon BIGNUM *r; 58160814Ssimon BIGNUM *s; 59160814Ssimon } ECDSA_SIG; 60160814Ssimon 61160814SsimonECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this 62160814Ssimonfunction also allocates the BIGNUMs) and initialize it. 63160814Ssimon 64160814SsimonECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. 65160814Ssimon 66160814Ssimoni2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature 67160814SsimonB<sig> and writes the encoded signature to B<*pp> (note: if B<pp> 68160814Ssimonis NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of 69160814Ssimonthe DER encoded signature). B<i2d_ECDSA_SIG> returns the length 70160814Ssimonof the DER encoded signature (or 0 on error). 71160814Ssimon 72160814Ssimond2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns 73160814Ssimonthe decoded signature in a newly allocated B<ECDSA_SIG> structure. 74160814SsimonB<*sig> points to the buffer containing the DER encoded signature 75160814Ssimonof size B<len>. 76160814Ssimon 77160814SsimonECDSA_size() returns the maximum length of a DER encoded 78160814SsimonECDSA signature created with the private EC key B<eckey>. 79160814Ssimon 80160814SsimonECDSA_sign_setup() may be used to precompute parts of the 81160814Ssimonsigning operation. B<eckey> is the private EC key and B<ctx> 82160814Ssimonis a pointer to B<BN_CTX> structure (or NULL). The precomputed 83160814Ssimonvalues or returned in B<kinv> and B<rp> and can be used in a 84160814Ssimonlater call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. 85160814Ssimon 86160814SsimonECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> 87160814Ssimonand B<rp> set to NULL. 88160814Ssimon 89160814SsimonECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes 90160814Ssimonhash value B<dgst> using the private EC key B<eckey> and the optional 91160814Ssimonpre-computed values B<kinv> and B<rp>. The DER encoded signatures is 92160814Ssimonstored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> 93160814Ssimonmust point to B<ECDSA_size> bytes of memory. The parameter B<type> 94160814Ssimonis ignored. 95160814Ssimon 96160814SsimonECDSA_verify() verifies that the signature in B<sig> of size 97160814SsimonB<siglen> is a valid ECDSA signature of the hash value 98279264SdelphijB<dgst> of size B<dgstlen> using the public key B<eckey>. 99160814SsimonThe parameter B<type> is ignored. 100160814Ssimon 101160814SsimonECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> 102160814Ssimonand B<rp> set to NULL. 103160814Ssimon 104160814SsimonECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> 105160814Ssimonbytes hash value B<dgst> using the private key B<eckey> and the 106160814Ssimonoptional pre-computed values B<kinv> and B<rp>. The signature is 107160814Ssimonreturned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). 108160814Ssimon 109160814SsimonECDSA_do_verify() verifies that the signature B<sig> is a valid 110160814SsimonECDSA signature of the hash value B<dgst> of size B<dgst_len> 111160814Ssimonusing the public key B<eckey>. 112160814Ssimon 113160814Ssimon=head1 RETURN VALUES 114160814Ssimon 115160814SsimonECDSA_size() returns the maximum length signature or 0 on error. 116160814Ssimon 117238405SjkimECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 118160814Ssimonon error. 119160814Ssimon 120160814SsimonECDSA_verify() and ECDSA_do_verify() return 1 for a valid 121160814Ssimonsignature, 0 for an invalid signature and -1 on error. 122160814SsimonThe error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 123160814Ssimon 124160814Ssimon=head1 EXAMPLES 125160814Ssimon 126160814SsimonCreating a ECDSA signature of given SHA-1 hash value using the 127160814Ssimonnamed curve secp192k1. 128160814Ssimon 129160814SsimonFirst step: create a EC_KEY object (note: this part is B<not> ECDSA 130160814Ssimonspecific) 131160814Ssimon 132160814Ssimon int ret; 133160814Ssimon ECDSA_SIG *sig; 134279264Sdelphij EC_KEY *eckey; 135279264Sdelphij eckey = EC_KEY_new_by_curve_name(NID_secp192k1); 136160814Ssimon if (eckey == NULL) 137160814Ssimon { 138160814Ssimon /* error */ 139160814Ssimon } 140160814Ssimon if (!EC_KEY_generate_key(eckey)) 141160814Ssimon { 142160814Ssimon /* error */ 143160814Ssimon } 144160814Ssimon 145160814SsimonSecond step: compute the ECDSA signature of a SHA-1 hash value 146160814Ssimonusing B<ECDSA_do_sign> 147160814Ssimon 148160814Ssimon sig = ECDSA_do_sign(digest, 20, eckey); 149160814Ssimon if (sig == NULL) 150160814Ssimon { 151160814Ssimon /* error */ 152160814Ssimon } 153160814Ssimon 154160814Ssimonor using B<ECDSA_sign> 155160814Ssimon 156160814Ssimon unsigned char *buffer, *pp; 157160814Ssimon int buf_len; 158160814Ssimon buf_len = ECDSA_size(eckey); 159160814Ssimon buffer = OPENSSL_malloc(buf_len); 160160814Ssimon pp = buffer; 161160814Ssimon if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey); 162160814Ssimon { 163160814Ssimon /* error */ 164160814Ssimon } 165160814Ssimon 166160814SsimonThird step: verify the created ECDSA signature using B<ECDSA_do_verify> 167160814Ssimon 168160814Ssimon ret = ECDSA_do_verify(digest, 20, sig, eckey); 169160814Ssimon 170160814Ssimonor using B<ECDSA_verify> 171160814Ssimon 172160814Ssimon ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); 173160814Ssimon 174160814Ssimonand finally evaluate the return value: 175160814Ssimon 176160814Ssimon if (ret == -1) 177160814Ssimon { 178160814Ssimon /* error */ 179160814Ssimon } 180160814Ssimon else if (ret == 0) 181160814Ssimon { 182160814Ssimon /* incorrect signature */ 183160814Ssimon } 184160814Ssimon else /* ret == 1 */ 185160814Ssimon { 186160814Ssimon /* signature ok */ 187160814Ssimon } 188160814Ssimon 189160814Ssimon=head1 CONFORMING TO 190160814Ssimon 191160814SsimonANSI X9.62, US Federal Information Processing Standard FIPS 186-2 192160814Ssimon(Digital Signature Standard, DSS) 193160814Ssimon 194160814Ssimon=head1 SEE ALSO 195160814Ssimon 196160814SsimonL<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)> 197160814Ssimon 198160814Ssimon=head1 HISTORY 199160814Ssimon 200160814SsimonThe ecdsa implementation was first introduced in OpenSSL 0.9.8 201160814Ssimon 202160814Ssimon=head1 AUTHOR 203160814Ssimon 204160814SsimonNils Larsch for the OpenSSL project (http://www.openssl.org). 205160814Ssimon 206160814Ssimon=cut 207