5 ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size,
6 ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup,
7 ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature
8 algorithm (ECDSA) functions.
12 #include <openssl/ecdsa.h>
14 ECDSA_SIG *ECDSA_SIG_new(void);
15 void ECDSA_SIG_free(ECDSA_SIG *sig);
16 void ECDSA_SIG_get0(BIGNUM **pr, BIGNUM **ps, ECDSA_SIG *sig);
17 int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
18 ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
19 int ECDSA_size(const EC_KEY *eckey);
21 int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
22 unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
23 ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
26 int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
27 const unsigned char *sig, int siglen, EC_KEY *eckey);
28 int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
29 const ECDSA_SIG *sig, EC_KEY* eckey);
31 ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
32 const BIGNUM *kinv, const BIGNUM *rp,
34 int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
35 int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
36 unsigned char *sig, unsigned int *siglen,
37 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
41 Note: these functions provide a low level interface to ECDSA. Most
42 applications should use the higher level B<EVP> interface such as
43 L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead.
45 B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
46 B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
48 ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this
49 function also allocates the BIGNUMs) and initializes it.
51 ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
53 ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained
54 in B<sig>. The values can then be examined or initialised.
56 i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and
57 writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG()
58 returns the expected length in bytes of the DER encoded signature).
59 i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on
62 d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded
63 signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the
64 buffer containing the DER encoded signature of size B<len>.
66 ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
67 created with the private EC key B<eckey>.
69 ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value
70 B<dgst> using the private EC key B<eckey>. The DER encoded signatures is
71 stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> must
72 point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently
73 ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv>
74 and B<rp> set to NULL.
76 ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned
77 as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign()
78 is a wrapper function for ECDSA_do_sign_ex() with B<kinv> and B<rp> set to
81 ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a
82 valid ECDSA signature of the hash value B<dgst> of size B<dgstlen> using the
83 public key B<eckey>. The parameter B<type> is ignored.
85 ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
86 presented in the form of a pointer to an B<ECDSA_SIG> structure.
88 The remaining functions utilise the internal B<kinv> and B<r> values used
89 during signature computation. Most applications will never need to call these
90 and some external ECDSA ENGINE implementations may not support them at all if
91 either B<kinv> or B<r> is not B<NULL>.
93 ECDSA_sign_setup() may be used to precompute parts of the signing operation.
94 B<eckey> is the private EC key and B<ctx> is a pointer to B<BN_CTX> structure
95 (or NULL). The precomputed values or returned in B<kinv> and B<rp> and can be
96 used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
98 ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value
99 B<dgst> using the private EC key B<eckey> and the optional pre-computed values
100 B<kinv> and B<rp>. The DER encoded signatures is stored in B<sig> and it's
101 length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey)
102 bytes of memory. The parameter B<type> is ignored.
104 ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is
105 returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
109 ECDSA_size() returns the maximum length signature or 0 on error.
111 ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
114 ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
115 B<ECDSA_SIG> structure or NULL on error.
117 ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
118 signature, 0 for an invalid signature and -1 on error.
119 The error codes can be obtained by L<ERR_get_error(3)>.
123 Creating an ECDSA signature of a given SHA-256 hash value using the
124 named curve prime256v1 (aka P-256).
126 First step: create a EC_KEY object (note: this part is B<not> ECDSA
132 eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
136 if (EC_KEY_generate_key(eckey) == 0) {
140 Second step: compute the ECDSA signature of a SHA-256 hash value
141 using ECDSA_do_sign():
143 sig = ECDSA_do_sign(digest, 32, eckey);
148 or using ECDSA_sign():
150 unsigned char *buffer, *pp;
152 buf_len = ECDSA_size(eckey);
153 buffer = OPENSSL_malloc(buf_len);
155 if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) {
159 Third step: verify the created ECDSA signature using ECDSA_do_verify():
161 ret = ECDSA_do_verify(digest, 32, sig, eckey);
163 or using ECDSA_verify():
165 ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
167 and finally evaluate the return value:
171 } else if (ret == 0) {
172 /* incorrect signature */
179 ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
180 (Digital Signature Standard, DSS)
186 L<EVP_DigestSignInit(3)>,
187 L<EVP_DigestVerifyInit(3)>