1.\" $OpenBSD: ECDSA_SIG_new.3,v 1.17 2023/03/07 06:12:27 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: March 7 2023 $ 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_setup , 67.Nm ECDSA_sign , 68.Nm ECDSA_sign_ex , 69.Nm ECDSA_verify , 70.Nm ECDSA_do_sign , 71.Nm ECDSA_do_sign_ex , 72.Nm ECDSA_do_verify , 73.Nm ECDSA_OpenSSL , 74.Nm ECDSA_get_default_method , 75.Nm ECDSA_set_default_method , 76.Nm ECDSA_set_method 77.Nd Elliptic Curve Digital Signature Algorithm 78.Sh SYNOPSIS 79.In openssl/ecdsa.h 80.Ft ECDSA_SIG* 81.Fo ECDSA_SIG_new 82.Fa void 83.Fc 84.Ft void 85.Fo ECDSA_SIG_free 86.Fa "ECDSA_SIG *sig" 87.Fc 88.Ft void 89.Fo ECDSA_SIG_get0 90.Fa "const ECDSA_SIG *sig" 91.Fa "const BIGNUM **r" 92.Fa "const BIGNUM **s" 93.Fc 94.Ft "const BIGNUM *" 95.Fo ECDSA_SIG_get0_r 96.Fa "const ECDSA_SIG *sig" 97.Fc 98.Ft "const BIGNUM *" 99.Fo ECDSA_SIG_get0_s 100.Fa "const ECDSA_SIG *sig" 101.Fc 102.Ft int 103.Fo ECDSA_SIG_set0 104.Fa "ECDSA_SIG *sig" 105.Fa "BIGNUM *r" 106.Fa "BIGNUM *s" 107.Fc 108.Ft int 109.Fo i2d_ECDSA_SIG 110.Fa "const ECDSA_SIG *sig_in" 111.Fa "unsigned char **der_out" 112.Fc 113.Ft ECDSA_SIG* 114.Fo d2i_ECDSA_SIG 115.Fa "ECDSA_SIG **sig_out" 116.Fa "const unsigned char **der_in" 117.Fa "long len" 118.Fc 119.Ft int 120.Fo ECDSA_size 121.Fa "const EC_KEY *eckey" 122.Fc 123.Ft int 124.Fo ECDSA_sign_setup 125.Fa "EC_KEY *eckey" 126.Fa "BN_CTX *ctx" 127.Fa "BIGNUM **kinv" 128.Fa "BIGNUM **rp" 129.Fc 130.Ft int 131.Fo ECDSA_sign 132.Fa "int type" 133.Fa "const unsigned char *dgst" 134.Fa "int dgstlen" 135.Fa "unsigned char *sig" 136.Fa "unsigned int *siglen" 137.Fa "EC_KEY *eckey" 138.Fc 139.Ft int 140.Fo ECDSA_sign_ex 141.Fa "int type" 142.Fa "const unsigned char *dgst" 143.Fa "int dgstlen" 144.Fa "unsigned char *sig" 145.Fa "unsigned int *siglen" 146.Fa "const BIGNUM *kinv" 147.Fa "const BIGNUM *rp" 148.Fa "EC_KEY *eckey" 149.Fc 150.Ft int 151.Fo ECDSA_verify 152.Fa "int type" 153.Fa "const unsigned char *dgst" 154.Fa "int dgstlen" 155.Fa "const unsigned char *sig" 156.Fa "int siglen" 157.Fa "EC_KEY *eckey" 158.Fc 159.Ft ECDSA_SIG* 160.Fo ECDSA_do_sign 161.Fa "const unsigned char *dgst" 162.Fa "int dgst_len" 163.Fa "EC_KEY *eckey" 164.Fc 165.Ft ECDSA_SIG* 166.Fo ECDSA_do_sign_ex 167.Fa "const unsigned char *dgst" 168.Fa "int dgstlen" 169.Fa "const BIGNUM *kinv" 170.Fa "const BIGNUM *rp" 171.Fa "EC_KEY *eckey" 172.Fc 173.Ft int 174.Fo ECDSA_do_verify 175.Fa "const unsigned char *dgst" 176.Fa "int dgst_len" 177.Fa "const ECDSA_SIG *sig" 178.Fa "EC_KEY* eckey" 179.Fc 180.Ft const ECDSA_METHOD* 181.Fo ECDSA_OpenSSL 182.Fa void 183.Fc 184.Ft const ECDSA_METHOD* 185.Fo ECDSA_get_default_method 186.Fa void 187.Fc 188.Ft void 189.Fo ECDSA_set_default_method 190.Fa "const ECDSA_METHOD *meth" 191.Fc 192.Ft int 193.Fo ECDSA_set_method 194.Fa "EC_KEY *eckey" 195.Fa "const ECDSA_METHOD *meth" 196.Fc 197.Sh DESCRIPTION 198These functions provide a low level interface to ECDSA. 199Most applications should use the higher level EVP interface such as 200.Xr EVP_DigestSignInit 3 201or 202.Xr EVP_DigestVerifyInit 3 203instead. 204Creation of the required 205.Vt EC_KEY 206objects is described in 207.Xr EC_KEY_new 3 . 208.Pp 209The 210.Vt ECDSA_SIG 211structure consists of two 212.Vt BIGNUM Ns s 213for the 214.Fa r 215and 216.Fa s 217value of an ECDSA signature (see X9.62 or FIPS 186-2). 218.Bd -literal -offset indent 219struct { 220 BIGNUM *r; 221 BIGNUM *s; 222} ECDSA_SIG; 223.Ed 224.Pp 225.Fn ECDSA_SIG_new 226allocates a new 227.Vt ECDSA_SIG 228structure (note: this function also allocates the 229.Vt BIGNUM Ns s ) 230and initializes it. 231.Pp 232.Fn ECDSA_SIG_free 233frees the 234.Vt ECDSA_SIG 235structure 236.Fa sig . 237.Pp 238.Fn ECDSA_SIG_get0 239retrieves internal pointers the 240.Fa r 241and 242.Fa s 243values contained in 244.Fa sig . 245The values 246.Fa r 247and 248.Fa s 249can also be retrieved separately by the corresponding function 250.Fn ECDSA_SIG_get0_r 251and 252.Fn ECDSA_SIG_get0_s , 253respectively. 254.Pp 255.Fn ECDSA_SIG_set0 256sets the 257.Fa r 258and 259.Fa s 260values in 261.Fa sig . 262Calling this function transfers the memory management of the values to 263.Fa sig . 264Therefore, the values that have been passed in 265should not be freed by the caller. 266.Pp 267.Fn i2d_ECDSA_SIG 268creates the DER encoding of the ECDSA signature 269.Fa sig_in 270and writes the encoded signature to 271.Pf * Fa der_out . 272.Fn d2i_ECDSA_SIG 273decodes the DER-encoded signature stored in the buffer 274.Pf * Fa der_in 275which is 276.Fa len 277bytes long into 278.Pf * Fa sig_out . 279For details about the semantics, examples, caveats, and bugs, see 280.Xr ASN1_item_d2i 3 . 281.Pp 282.Fn ECDSA_size 283returns the maximum length of a DER-encoded ECDSA signature created with 284the private EC key 285.Fa eckey . 286.Pp 287.Fn ECDSA_sign_setup 288may be used to precompute parts of the signing operation. 289.Fa eckey 290is the private EC key and 291.Fa ctx 292is a pointer to a 293.Vt BN_CTX 294structure (or 295.Dv NULL ) . 296The precomputed values are returned in 297.Fa kinv 298and 299.Fa rp 300and can be used in a later call to 301.Fa ECDSA_sign_ex 302or 303.Fa ECDSA_do_sign_ex . 304.Pp 305.Fn ECDSA_sign 306is a wrapper function for 307.Fa ECDSA_sign_ex 308with 309.Fa kinv 310and 311.Fa rp 312set to 313.Dv NULL . 314.Pp 315.Fn ECDSA_sign_ex 316computes a digital signature of the 317.Fa dgstlen 318bytes hash value 319.Fa dgst 320using the private EC key 321.Fa eckey 322and the optional pre-computed values 323.Fa kinv 324and 325.Fa rp . 326The DER-encoded signature is stored in 327.Fa sig 328and its length is returned in 329.Fa siglen . 330Note: 331.Fa sig 332must point to 333.Fn ECDSA_size 334bytes of memory. 335The parameter 336.Fa type 337is ignored. 338.Pp 339.Fn ECDSA_verify 340verifies that the signature in 341.Fa sig 342of size 343.Fa siglen 344is a valid ECDSA signature of the hash value 345.Fa dgst 346of size 347.Fa dgstlen 348using the public key 349.Fa eckey . 350The parameter 351.Fa type 352is ignored. 353.Pp 354.Fn ECDSA_do_sign 355is a wrapper function for 356.Fn ECDSA_do_sign_ex 357with 358.Fa kinv 359and 360.Fa rp 361set to 362.Dv NULL . 363.Pp 364.Fn ECDSA_do_sign_ex 365computes a digital signature of the 366.Fa dgst_len 367bytes hash value 368.Fa dgst 369using the private key 370.Fa eckey 371and the optional pre-computed values 372.Fa kinv 373and 374.Fa rp . 375The signature is returned in a newly allocated 376.Vt ECDSA_SIG 377structure (or 378.Dv NULL 379on error). 380.Pp 381.Fn ECDSA_do_verify 382verifies that the signature 383.Fa sig 384is a valid ECDSA signature of the hash value 385.Fa dgst 386of size 387.Fa dgst_len 388using the public key 389.Fa eckey . 390.Sh RETURN VALUES 391.Fn ECDSA_SIG_new 392returns the new 393.Vt ECDSA_SIG 394object or 395.Dv NULL 396if an error occurs. 397.Pp 398.Fn i2d_ECDSA_SIG 399returns the number of bytes successfully encoded 400or a negative value if an error occurs. 401.Pp 402.Fn d2i_ECDSA_SIG 403returns a pointer to the decoded 404.Vt ECDSA_SIG 405structure or 406.Dv NULL 407if an error occurs. 408.Pp 409.Fn ECDSA_size 410returns the maximum length signature or 0 on error. 411.Pp 412.Fn ECDSA_SIG_get0_r 413and 414.Fn ECDSA_SIG_get0_s 415return a pointer owned by the 416.Vt ECDSA_SIG 417object if it has been set or 418.Dv NULL 419otherwise. 420.Pp 421.Fn ECDSA_SIG_set0 , 422.Fn ECDSA_sign , 423.Fn ECDSA_sign_ex , 424and 425.Fn ECDSA_sign_setup 426return 1 if successful or 0 on error. 427.Pp 428.Fn ECDSA_do_sign 429and 430.Fn ECDSA_do_sign_ex 431return a pointer to an allocated 432.Vt ECDSA_SIG 433structure or 434.Dv NULL 435on error. 436.Pp 437.Fn ECDSA_verify 438and 439.Fn ECDSA_do_verify 440return 1 for a valid signature, 0 for an invalid signature and -1 on 441error. 442The error codes can be obtained by 443.Xr ERR_get_error 3 . 444.Sh EXAMPLES 445Creating an ECDSA signature of given SHA-1 hash value using the named 446curve secp192k1. 447.Pp 448First step: create an 449.Vt EC_KEY 450object. 451This part is 452.Em not 453ECDSA specific. 454.Bd -literal -offset indent 455int ret; 456ECDSA_SIG *sig; 457EC_KEY *eckey; 458 459eckey = EC_KEY_new_by_curve_name(NID_secp192k1); 460if (eckey == NULL) { 461 /* error */ 462} 463if (!EC_KEY_generate_key(eckey)) { 464 /* error */ 465} 466.Ed 467.Pp 468Second step: compute the ECDSA signature of a SHA-1 hash value using 469.Fn ECDSA_do_sign 470.Bd -literal -offset indent 471sig = ECDSA_do_sign(digest, 20, eckey); 472if (sig == NULL) { 473 /* error */ 474} 475.Ed 476.Pp 477or using 478.Fn ECDSA_sign 479.Bd -literal -offset indent 480unsigned char *buffer, *pp; 481int buf_len; 482 483buf_len = ECDSA_size(eckey); 484buffer = malloc(buf_len); 485pp = buffer; 486if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) { 487 /* error */ 488} 489.Ed 490.Pp 491Third step: verify the created ECDSA signature using 492.Fn ECDSA_do_verify 493.Pp 494.Dl ret = ECDSA_do_verify(digest, 20, sig, eckey); 495.Pp 496or using 497.Fn ECDSA_verify 498.Pp 499.Dl ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); 500.Pp 501and finally evaluate the return value: 502.Bd -literal -offset indent 503if (ret == -1) { 504 /* error */ 505} else if (ret == 0) { 506 /* incorrect signature */ 507} else { 508 /* ret == 1 */ 509 /* signature ok */ 510} 511.Ed 512.Sh SEE ALSO 513.Xr crypto 3 , 514.Xr d2i_ECPKParameters 3 , 515.Xr DSA_new 3 , 516.Xr EC_GROUP_new 3 , 517.Xr EC_KEY_METHOD_new 3 , 518.Xr EC_KEY_new 3 , 519.Xr ECDSA_set_ex_data 3 , 520.Xr EVP_DigestSignInit 3 , 521.Xr EVP_DigestVerifyInit 3 , 522.Xr RSA_new 3 523.Sh STANDARDS 524ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 525(Digital Signature Standard, DSS) 526.Sh HISTORY 527.Fn ECDSA_SIG_new , 528.Fn ECDSA_SIG_free , 529.Fn i2d_ECDSA_SIG , 530.Fn d2i_ECDSA_SIG , 531.Fn ECDSA_size , 532.Fn ECDSA_sign_setup , 533.Fn ECDSA_sign , 534.Fn ECDSA_sign_ex , 535.Fn ECDSA_verify , 536.Fn ECDSA_do_sign , 537.Fn ECDSA_do_sign_ex , 538.Fn ECDSA_do_verify , 539.Fn ECDSA_OpenSSL , 540.Fn ECDSA_get_default_method , 541.Fn ECDSA_set_default_method , 542and 543.Fn ECDSA_set_method 544first appeared in OpenSSL 0.9.8 and have been available since 545.Ox 4.5 . 546.Pp 547.Fn ECDSA_SIG_get0 548and 549.Fn ECDSA_SIG_set0 550first appeared in OpenSSL 1.1.0 and have been available since 551.Ox 6.3 . 552.Fn ECDSA_SIG_get0_r 553and 554.Fn ECDSA_SIG_get0_s 555first appeared in OpenSSL 1.1.1 and have been available since 556.Ox 7.1 . 557.Sh AUTHORS 558.An Nils Larsch 559for the OpenSSL project. 560