ECDSA_SIG_free(3ossl)

1ECDSA_SIG_NEW(3ossl)                OpenSSL               ECDSA_SIG_NEW(3ossl)
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, ECDSA_size, ECDSA_sign, ECDSA_do_sign,
8       ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
9       ECDSA_do_sign_ex - low-level elliptic curve digital signature algorithm
10       (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
22       The following functions have been deprecated since OpenSSL 3.0, and can
23       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
24       version value, see openssl_user_macros(7):
25
26        int ECDSA_size(const EC_KEY *eckey);
27
28        int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
29                       unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
30        ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
31                                 EC_KEY *eckey);
32
33        int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
34                         const unsigned char *sig, int siglen, EC_KEY *eckey);
35        int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
36                            const ECDSA_SIG *sig, EC_KEY* eckey);
37
38        ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
39                                    const BIGNUM *kinv, const BIGNUM *rp,
40                                    EC_KEY *eckey);
41        int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
42        int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
43                          unsigned char *sig, unsigned int *siglen,
44                          const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
45

DESCRIPTION

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

RETURN VALUES

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

EXAMPLES

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

CONFORMING TO

191       ANSI X9.62, US Federal Information Processing Standard FIPS186-2
192       (Digital Signature Standard, DSS)
193

HISTORY

199       The ECDSA_size(), ECDSA_sign(), ECDSA_do_sign(), ECDSA_verify(),
200       ECDSA_do_verify(), ECDSA_sign_setup(), ECDSA_sign_ex() and
201       ECDSA_do_sign_ex() functions were deprecated in OpenSSL 3.0.
202

COPYRIGHT

204       Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved.
205
206       Licensed under the Apache License 2.0 (the "License").  You may not use
207       this file except in compliance with the License.  You can obtain a copy
208       in the file LICENSE in the source distribution or at
209       <https://www.openssl.org/source/license.html>.
210
211
212
2133.0.5                             2022-11-01              ECDSA_SIG_NEW(3ossl)