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