openssl-devel/ECDSA_size(3ssl)

1ECDSA_SIG_NEW(3)                    OpenSSL                   ECDSA_SIG_NEW(3)
2
3
4

NAME

6       ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0,
7       ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG,
8       ECDSA_size, ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify,
9       ECDSA_sign_setup, ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic
10       curve digital signature algorithm (ECDSA) functions
11

SYNOPSIS

13        #include <openssl/ecdsa.h>
14
15        ECDSA_SIG *ECDSA_SIG_new(void);
16        void ECDSA_SIG_free(ECDSA_SIG *sig);
17        void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
18        const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);
19        const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);
20        int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
21        int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
22        ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
23        int ECDSA_size(const EC_KEY *eckey);
24
25        int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
26                       unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
27        ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
28                                 EC_KEY *eckey);
29
30        int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
31                         const unsigned char *sig, int siglen, EC_KEY *eckey);
32        int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
33                            const ECDSA_SIG *sig, EC_KEY* eckey);
34
35        ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
36                                    const BIGNUM *kinv, const BIGNUM *rp,
37                                    EC_KEY *eckey);
38        int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
39        int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
40                          unsigned char *sig, unsigned int *siglen,
41                          const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
42

DESCRIPTION

44       Note: these functions provide a low level interface to ECDSA. Most
45       applications should use the higher level EVP interface such as
46       EVP_DigestSignInit(3) or EVP_DigestVerifyInit(3) instead.
47
48       ECDSA_SIG is an opaque structure consisting of two BIGNUMs for the r
49       and s value of an ECDSA signature (see X9.62 or FIPS 186-2).
50
51       ECDSA_SIG_new() allocates an empty ECDSA_SIG structure. Note: before
52       OpenSSL 1.1.0 the: the r and s components were initialised.
53
54       ECDSA_SIG_free() frees the ECDSA_SIG structure sig.
55
56       ECDSA_SIG_get0() returns internal pointers the r and s values contained
57       in sig and stores them in *pr and *ps, respectively.  The pointer pr or
58       ps can be NULL, in which case the corresponding value is not returned.
59
60       The values r, s can also be retrieved separately by the corresponding
61       function ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s(), respectively.
62
63       The r and s values can be set by calling ECDSA_SIG_set0() and passing
64       the new values for r and s as parameters to the function. Calling this
65       function transfers the memory management of the values to the ECDSA_SIG
66       object, and therefore the values that have been passed in should not be
67       freed directly after this function has been called.
68
69       i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature sig and
70       writes the encoded signature to *pp (note: if pp is NULL
71       i2d_ECDSA_SIG() returns the expected length in bytes of the DER encoded
72       signature).  i2d_ECDSA_SIG() returns the length of the DER encoded
73       signature (or 0 on error).
74
75       d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the
76       decoded signature in a newly allocated ECDSA_SIG structure. *sig points
77       to the buffer containing the DER encoded signature of size len.
78
79       ECDSA_size() returns the maximum length of a DER encoded ECDSA
80       signature created with the private EC key eckey.
81
82       ECDSA_sign() computes a digital signature of the dgstlen bytes hash
83       value dgst using the private EC key eckey. The DER encoded signatures
84       is stored in sig and its length is returned in sig_len. Note: sig must
85       point to ECDSA_size(eckey) bytes of memory. The parameter type is
86       currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex()
87       with kinv and rp set to NULL.
88
89       ECDSA_do_sign() is similar to ECDSA_sign() except the signature is
90       returned as a newly allocated ECDSA_SIG structure (or NULL on error).
91       ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with kinv
92       and rp set to NULL.
93
94       ECDSA_verify() verifies that the signature in sig of size siglen is a
95       valid ECDSA signature of the hash value dgst of size dgstlen using the
96       public key eckey.  The parameter type is ignored.
97
98       ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
99       presented in the form of a pointer to an ECDSA_SIG structure.
100
101       The remaining functions utilise the internal kinv and r values used
102       during signature computation. Most applications will never need to call
103       these and some external ECDSA ENGINE implementations may not support
104       them at all if either kinv or r is not NULL.
105
106       ECDSA_sign_setup() may be used to precompute parts of the signing
107       operation.  eckey is the private EC key and ctx is a pointer to BN_CTX
108       structure (or NULL). The precomputed values or returned in kinv and rp
109       and can be used in a later call to ECDSA_sign_ex() or
110       ECDSA_do_sign_ex().
111
112       ECDSA_sign_ex() computes a digital signature of the dgstlen bytes hash
113       value dgst using the private EC key eckey and the optional pre-computed
114       values kinv and rp. The DER encoded signature is stored in sig and its
115       length is returned in sig_len. Note: sig must point to
116       ECDSA_size(eckey) bytes of memory. The parameter type is ignored.
117
118       ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature
119       is returned as a newly allocated ECDSA_SIG structure (or NULL on
120       error).
121

RETURN VALUES

123       ECDSA_SIG_new() returns NULL if the allocation fails.
124
125       ECDSA_SIG_set0() returns 1 on success or 0 on failure.
126
127       ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s() return the corresponding
128       value, or NULL if it is unset.
129
130       ECDSA_size() returns the maximum length signature or 0 on error.
131
132       ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if
133       successful or 0 on error.
134
135       ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
136       ECDSA_SIG structure or NULL on error.
137
138       ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0
139       for an invalid signature and -1 on error.  The error codes can be
140       obtained by ERR_get_error(3).
141

EXAMPLES

143       Creating an ECDSA signature of a given SHA-256 hash value using the
144       named curve prime256v1 (aka P-256).
145
146       First step: create an EC_KEY object (note: this part is not ECDSA
147       specific)
148
149        int ret;
150        ECDSA_SIG *sig;
151        EC_KEY *eckey;
152
153        eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
154        if (eckey == NULL)
155            /* error */
156        if (EC_KEY_generate_key(eckey) == 0)
157            /* error */
158
159       Second step: compute the ECDSA signature of a SHA-256 hash value using
160       ECDSA_do_sign():
161
162        sig = ECDSA_do_sign(digest, 32, eckey);
163        if (sig == NULL)
164            /* error */
165
166       or using ECDSA_sign():
167
168        unsigned char *buffer, *pp;
169        int buf_len;
170
171        buf_len = ECDSA_size(eckey);
172        buffer = OPENSSL_malloc(buf_len);
173        pp = buffer;
174        if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)
175            /* error */
176
177       Third step: verify the created ECDSA signature using ECDSA_do_verify():
178
179        ret = ECDSA_do_verify(digest, 32, sig, eckey);
180
181       or using ECDSA_verify():
182
183        ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
184
185       and finally evaluate the return value:
186
187        if (ret == 1)
188            /* signature ok */
189        else if (ret == 0)
190            /* incorrect signature */
191        else
192            /* error */
193

CONFORMING TO

195       ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
196       (Digital Signature Standard, DSS)
197

COPYRIGHT

202       Copyright 2004-2019 The OpenSSL Project Authors. All Rights Reserved.
203
204       Licensed under the OpenSSL license (the "License").  You may not use
205       this file except in compliance with the License.  You can obtain a copy
206       in the file LICENSE in the source distribution or at
207       <https://www.openssl.org/source/license.html>.
208
209
210
2111.1.1c                            2019-05-28                  ECDSA_SIG_NEW(3)