xref: /openbsd-src/lib/libcrypto/man/ECDSA_SIG_new.3 (revision 207d91d1e26440ebde32ac662488e2432270bfe3) 
1.\" $OpenBSD: ECDSA_SIG_new.3,v 1.21 2024/11/15 20:14:58 tb Exp $
2.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
3.\" selective merge up to: OpenSSL da4ea0cf Aug 5 16:13:24 2019 +0100
4.\"
5.\" This file was written by Nils Larsch <nils@openssl.org>.
6.\" Copyright (c) 2004, 2005, 2013, 2016 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in
18.\"    the documentation and/or other materials provided with the
19.\"    distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\"    software must display the following acknowledgment:
23.\"    "This product includes software developed by the OpenSSL Project
24.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\"    endorse or promote products derived from this software without
28.\"    prior written permission. For written permission, please contact
29.\"    openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\"    nor may "OpenSSL" appear in their names without prior written
33.\"    permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\"    acknowledgment:
37.\"    "This product includes software developed by the OpenSSL Project
38.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: November 15 2024 $
54.Dt ECDSA_SIG_NEW 3
55.Os
56.Sh NAME
57.Nm ECDSA_SIG_new ,
58.Nm ECDSA_SIG_free ,
59.Nm ECDSA_SIG_get0 ,
60.Nm ECDSA_SIG_get0_r ,
61.Nm ECDSA_SIG_get0_s ,
62.Nm ECDSA_SIG_set0 ,
63.Nm i2d_ECDSA_SIG ,
64.Nm d2i_ECDSA_SIG ,
65.Nm ECDSA_size ,
66.Nm ECDSA_sign ,
67.Nm ECDSA_verify ,
68.Nm ECDSA_do_sign ,
69.Nm ECDSA_do_verify
70.Nd Elliptic Curve Digital Signature Algorithm
71.Sh SYNOPSIS
72.In openssl/ec.h
73.Ft ECDSA_SIG*
74.Fo ECDSA_SIG_new
75.Fa void
76.Fc
77.Ft void
78.Fo ECDSA_SIG_free
79.Fa "ECDSA_SIG *sig"
80.Fc
81.Ft void
82.Fo ECDSA_SIG_get0
83.Fa "const ECDSA_SIG *sig"
84.Fa "const BIGNUM **r"
85.Fa "const BIGNUM **s"
86.Fc
87.Ft "const BIGNUM *"
88.Fo ECDSA_SIG_get0_r
89.Fa "const ECDSA_SIG *sig"
90.Fc
91.Ft "const BIGNUM *"
92.Fo ECDSA_SIG_get0_s
93.Fa "const ECDSA_SIG *sig"
94.Fc
95.Ft int
96.Fo ECDSA_SIG_set0
97.Fa "ECDSA_SIG *sig"
98.Fa "BIGNUM *r"
99.Fa "BIGNUM *s"
100.Fc
101.Ft int
102.Fo i2d_ECDSA_SIG
103.Fa "const ECDSA_SIG *sig_in"
104.Fa "unsigned char **der_out"
105.Fc
106.Ft ECDSA_SIG*
107.Fo d2i_ECDSA_SIG
108.Fa "ECDSA_SIG **sig_out"
109.Fa "const unsigned char **der_in"
110.Fa "long len"
111.Fc
112.Ft int
113.Fo ECDSA_size
114.Fa "const EC_KEY *eckey"
115.Fc
116.Ft int
117.Fo ECDSA_sign
118.Fa "int type"
119.Fa "const unsigned char *dgst"
120.Fa "int dgstlen"
121.Fa "unsigned char *sig"
122.Fa "unsigned int *siglen"
123.Fa "EC_KEY *eckey"
124.Fc
125.Ft int
126.Fo ECDSA_verify
127.Fa "int type"
128.Fa "const unsigned char *dgst"
129.Fa "int dgstlen"
130.Fa "const unsigned char *sig"
131.Fa "int siglen"
132.Fa "EC_KEY *eckey"
133.Fc
134.Ft ECDSA_SIG*
135.Fo ECDSA_do_sign
136.Fa "const unsigned char *dgst"
137.Fa "int dgst_len"
138.Fa "EC_KEY *eckey"
139.Fc
140.Ft int
141.Fo ECDSA_do_verify
142.Fa "const unsigned char *dgst"
143.Fa "int dgst_len"
144.Fa "const ECDSA_SIG *sig"
145.Fa "EC_KEY* eckey"
146.Fc
147.Sh DESCRIPTION
148These functions provide a low level interface to ECDSA.
149Most applications should use the higher level EVP interface such as
150.Xr EVP_DigestSignInit 3
151or
152.Xr EVP_DigestVerifyInit 3
153instead.
154Creation of the required
155.Vt EC_KEY
156objects is described in
157.Xr EC_KEY_new 3 .
158.Pp
159The
160.Vt ECDSA_SIG
161structure consists of two
162.Vt BIGNUM Ns s
163for the
164.Fa r
165and
166.Fa s
167value of an ECDSA signature (see X9.62 or FIPS 186-2).
168.Bd -literal -offset indent
169struct {
170	BIGNUM *r;
171	BIGNUM *s;
172} ECDSA_SIG;
173.Ed
174.Pp
175.Fn ECDSA_SIG_new
176allocates a new
177.Vt ECDSA_SIG
178structure (note: this function also allocates the
179.Vt BIGNUM Ns s )
180and initializes it.
181.Pp
182.Fn ECDSA_SIG_free
183frees the
184.Vt ECDSA_SIG
185structure
186.Fa sig .
187.Pp
188.Fn ECDSA_SIG_get0
189retrieves internal pointers the
190.Fa r
191and
192.Fa s
193values contained in
194.Fa sig .
195The values
196.Fa r
197and
198.Fa s
199can also be retrieved separately by the corresponding function
200.Fn ECDSA_SIG_get0_r
201and
202.Fn ECDSA_SIG_get0_s ,
203respectively.
204.Pp
205.Fn ECDSA_SIG_set0
206sets the
207.Fa r
208and
209.Fa s
210values in
211.Fa sig .
212Calling this function transfers the memory management of the values to
213.Fa sig .
214Therefore, the values that have been passed in
215should not be freed by the caller.
216.Pp
217.Fn i2d_ECDSA_SIG
218creates the DER encoding of the ECDSA signature
219.Fa sig_in
220and writes the encoded signature to
221.Pf * Fa der_out .
222.Fn d2i_ECDSA_SIG
223decodes the DER-encoded signature stored in the buffer
224.Pf * Fa der_in
225which is
226.Fa len
227bytes long into
228.Pf * Fa sig_out .
229For details about the semantics, examples, caveats, and bugs, see
230.Xr ASN1_item_d2i 3 .
231.Pp
232.Fn ECDSA_size
233returns the maximum length of a DER-encoded ECDSA signature created with
234the private EC key
235.Fa eckey .
236.Pp
237.Fn ECDSA_sign
238computes a digital signature of the
239.Fa dgstlen
240bytes hash value
241.Fa dgst
242using the private EC key
243.Fa eckey .
244The DER-encoded signature is stored in
245.Fa sig
246and its length is returned in
247.Fa siglen .
248Note:
249.Fa sig
250must point to
251.Fn ECDSA_size
252bytes of memory.
253The parameter
254.Fa type
255is ignored.
256.Pp
257.Fn ECDSA_verify
258verifies that the signature in
259.Fa sig
260of size
261.Fa siglen
262is a valid ECDSA signature of the hash value
263.Fa dgst
264of size
265.Fa dgstlen
266using the public key
267.Fa eckey .
268The parameter
269.Fa type
270is ignored.
271.Pp
272.Fn ECDSA_do_sign
273computes a digital signature of the
274.Fa dgst_len
275bytes hash value
276.Fa dgst
277using the private key
278.Fa eckey .
279The signature is returned in a newly allocated
280.Vt ECDSA_SIG
281structure (or
282.Dv NULL
283on error).
284.Pp
285.Fn ECDSA_do_verify
286verifies that the signature
287.Fa sig
288is a valid ECDSA signature of the hash value
289.Fa dgst
290of size
291.Fa dgst_len
292using the public key
293.Fa eckey .
294.Sh RETURN VALUES
295.Fn ECDSA_SIG_new
296returns the new
297.Vt ECDSA_SIG
298object or
299.Dv NULL
300if an error occurs.
301.Pp
302.Fn i2d_ECDSA_SIG
303returns the number of bytes successfully encoded
304or a negative value if an error occurs.
305.Pp
306.Fn d2i_ECDSA_SIG
307returns a pointer to the decoded
308.Vt ECDSA_SIG
309structure or
310.Dv NULL
311if an error occurs.
312.Pp
313.Fn ECDSA_size
314returns the maximum length signature or 0 on error.
315.Pp
316.Fn ECDSA_SIG_get0_r
317and
318.Fn ECDSA_SIG_get0_s
319return a pointer owned by the
320.Vt ECDSA_SIG
321object if it has been set or
322.Dv NULL
323otherwise.
324.Pp
325.Fn ECDSA_SIG_set0
326and
327.Fn ECDSA_sign
328return 1 if successful or 0 on error.
329.Pp
330.Fn ECDSA_do_sign
331returns a pointer to an allocated
332.Vt ECDSA_SIG
333structure or
334.Dv NULL
335on error.
336.Pp
337.Fn ECDSA_verify
338and
339.Fn ECDSA_do_verify
340return 1 for a valid signature, 0 for an invalid signature and -1 on
341error.
342The error codes can be obtained by
343.Xr ERR_get_error 3 .
344.Sh EXAMPLES
345Creating an ECDSA signature of given SHA-384 hash value using the named
346curve secp384r1.
347.Pp
348First step: create an
349.Vt EC_KEY
350object.
351This part is
352.Em not
353ECDSA specific.
354.Bd -literal -offset indent
355int ret;
356ECDSA_SIG *sig;
357EC_KEY *eckey;
358
359eckey = EC_KEY_new_by_curve_name(NID_secp384r1);
360if (eckey == NULL) {
361	/* error */
362}
363if (!EC_KEY_generate_key(eckey)) {
364	/* error */
365}
366.Ed
367.Pp
368Second step: compute the ECDSA signature of a SHA-384 hash value using
369.Fn ECDSA_do_sign
370.Bd -literal -offset indent
371sig = ECDSA_do_sign(digest, SHA384_DIGEST_LENGTH, eckey);
372if (sig == NULL) {
373	/* error */
374}
375.Ed
376.Pp
377or using
378.Fn ECDSA_sign
379.Bd -literal -offset indent
380unsigned char *buffer, *pp;
381int buf_len;
382
383buf_len = ECDSA_size(eckey);
384buffer  = malloc(buf_len);
385pp = buffer;
386if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
387	/* error */
388}
389.Ed
390.Pp
391Third step: verify the created ECDSA signature using
392.Fn ECDSA_do_verify
393.Pp
394.Dl ret = ECDSA_do_verify(digest, SHA384_DIGEST_LENGTH, sig, eckey);
395.Pp
396or using
397.Fn ECDSA_verify
398.Pp
399.Dl ret = ECDSA_verify(0, digest, SHA384_DIGEST_LENGTH, buffer, buf_len, eckey);
400.Pp
401and finally evaluate the return value:
402.Bd -literal -offset indent
403if (ret == -1) {
404	/* error */
405} else if (ret == 0) {
406	/* incorrect signature */
407} else {
408	/* ret == 1 */
409	/* signature ok */
410}
411.Ed
412.Sh SEE ALSO
413.Xr crypto 3 ,
414.Xr d2i_ECPKParameters 3 ,
415.Xr DSA_new 3 ,
416.Xr EC_GROUP_new 3 ,
417.Xr EC_KEY_METHOD_new 3 ,
418.Xr EC_KEY_new 3 ,
419.Xr EC_KEY_set_ex_data 3 ,
420.Xr EVP_DigestSignInit 3 ,
421.Xr EVP_DigestVerifyInit 3 ,
422.Xr RSA_new 3
423.Sh STANDARDS
424ANSI X9.62, US Federal Information Processing Standard FIPS 186-5
425(Digital Signature Standard, DSS)
426.Sh HISTORY
427.Fn ECDSA_SIG_new ,
428.Fn ECDSA_SIG_free ,
429.Fn i2d_ECDSA_SIG ,
430.Fn d2i_ECDSA_SIG ,
431.Fn ECDSA_size ,
432.Fn ECDSA_sign ,
433.Fn ECDSA_verify ,
434.Fn ECDSA_do_sign ,
435and
436.Fn ECDSA_do_verify
437first appeared in OpenSSL 0.9.8 and have been available since
438.Ox 4.5 .
439.Pp
440.Fn ECDSA_SIG_get0
441and
442.Fn ECDSA_SIG_set0
443first appeared in OpenSSL 1.1.0 and have been available since
444.Ox 6.3 .
445.Fn ECDSA_SIG_get0_r
446and
447.Fn ECDSA_SIG_get0_s
448first appeared in OpenSSL 1.1.1 and have been available since
449.Ox 7.1 .
450.Sh AUTHORS
451.An Nils Larsch
452for the OpenSSL project.
453