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