1.\" $OpenBSD: EC_KEY_new.3,v 1.17 2023/04/27 09:49:44 tb Exp $ 2.\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500 3.\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 4.\" 5.\" This file was written by Matt Caswell <matt@openssl.org>. 6.\" Copyright (c) 2013, 2014 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: April 27 2023 $ 53.Dt EC_KEY_NEW 3 54.Os 55.Sh NAME 56.Nm EC_KEY_new , 57.Nm EC_KEY_get_flags , 58.Nm EC_KEY_set_flags , 59.Nm EC_KEY_clear_flags , 60.Nm EC_KEY_new_by_curve_name , 61.Nm EC_KEY_free , 62.Nm EC_KEY_copy , 63.Nm EC_KEY_dup , 64.Nm EC_KEY_up_ref , 65.Nm EC_KEY_get0_group , 66.Nm EC_KEY_set_group , 67.Nm EC_KEY_get0_private_key , 68.Nm EC_KEY_set_private_key , 69.Nm EC_KEY_get0_public_key , 70.Nm EC_KEY_set_public_key , 71.Nm EC_KEY_get_enc_flags , 72.Nm EC_KEY_set_enc_flags , 73.Nm EC_KEY_get_conv_form , 74.Nm EC_KEY_set_conv_form , 75.Nm EC_KEY_set_asn1_flag , 76.Nm EC_KEY_precompute_mult , 77.Nm EC_KEY_generate_key , 78.Nm EC_KEY_check_key , 79.Nm EC_KEY_set_public_key_affine_coordinates , 80.Nm EC_KEY_print , 81.Nm EC_KEY_print_fp 82.Nd create, destroy and manipulate EC_KEY objects 83.Sh SYNOPSIS 84.In openssl/ec.h 85.In openssl/bn.h 86.Ft EC_KEY * 87.Fn EC_KEY_new void 88.Ft int 89.Fo EC_KEY_get_flags 90.Fa "const EC_KEY *key" 91.Fc 92.Ft void 93.Fo EC_KEY_set_flags 94.Fa "EC_KEY *key" 95.Fa "int flags" 96.Fc 97.Ft void 98.Fo EC_KEY_clear_flags 99.Fa "EC_KEY *key" 100.Fa "int flags" 101.Fc 102.Ft EC_KEY * 103.Fo EC_KEY_new_by_curve_name 104.Fa "int nid" 105.Fc 106.Ft void 107.Fo EC_KEY_free 108.Fa "EC_KEY *key" 109.Fc 110.Ft EC_KEY * 111.Fo EC_KEY_copy 112.Fa "EC_KEY *dst" 113.Fa "const EC_KEY *src" 114.Fc 115.Ft EC_KEY * 116.Fo EC_KEY_dup 117.Fa "const EC_KEY *src" 118.Fc 119.Ft int 120.Fo EC_KEY_up_ref 121.Fa "EC_KEY *key" 122.Fc 123.Ft const EC_GROUP * 124.Fo EC_KEY_get0_group 125.Fa "const EC_KEY *key" 126.Fc 127.Ft int 128.Fo EC_KEY_set_group 129.Fa "EC_KEY *key" 130.Fa "const EC_GROUP *group" 131.Fc 132.Ft const BIGNUM * 133.Fo EC_KEY_get0_private_key 134.Fa "const EC_KEY *key" 135.Fc 136.Ft int 137.Fo EC_KEY_set_private_key 138.Fa "EC_KEY *key" 139.Fa "const BIGNUM *prv" 140.Fc 141.Ft const EC_POINT * 142.Fo EC_KEY_get0_public_key 143.Fa "const EC_KEY *key" 144.Fc 145.Ft int 146.Fo EC_KEY_set_public_key 147.Fa "EC_KEY *key" 148.Fa "const EC_POINT *pub" 149.Fc 150.Ft unsigned int 151.Fo EC_KEY_get_enc_flags 152.Fa "const EC_KEY *key" 153.Fc 154.Ft void 155.Fo EC_KEY_set_enc_flags 156.Fa "EC_KEY *key" 157.Fa "unsigned int flags" 158.Fc 159.Ft point_conversion_form_t 160.Fo EC_KEY_get_conv_form 161.Fa "const EC_KEY *key" 162.Fc 163.Ft void 164.Fo EC_KEY_set_conv_form 165.Fa "EC_KEY *key" 166.Fa "point_conversion_form_t cform" 167.Fc 168.Ft void 169.Fo EC_KEY_set_asn1_flag 170.Fa "EC_KEY *key" 171.Fa "int asn1_flag" 172.Fc 173.Ft int 174.Fo EC_KEY_precompute_mult 175.Fa "EC_KEY *key" 176.Fa "BN_CTX *ctx" 177.Fc 178.Ft int 179.Fo EC_KEY_generate_key 180.Fa "EC_KEY *key" 181.Fc 182.Ft int 183.Fo EC_KEY_check_key 184.Fa "const EC_KEY *key" 185.Fc 186.Ft int 187.Fo EC_KEY_set_public_key_affine_coordinates 188.Fa "EC_KEY *key" 189.Fa "BIGNUM *x" 190.Fa "BIGNUM *y" 191.Fc 192.Ft int 193.Fo EC_KEY_print 194.Fa "BIO *bp" 195.Fa "const EC_KEY *key" 196.Fa "int off" 197.Fc 198.Ft int 199.Fo EC_KEY_print_fp 200.Fa "FILE *fp" 201.Fa "const EC_KEY *key" 202.Fa "int off" 203.Fc 204.Sh DESCRIPTION 205An 206.Vt EC_KEY 207represents a public key and (optionally) an associated private key. 208The public key is a point on a curve represented by an 209.Vt EC_POINT , 210see 211.Xr EC_POINT_new 3 . 212The private key is simply a 213.Vt BIGNUM , 214see 215.Xr BN_new 3 . 216.Pp 217A new 218.Vt EC_KEY 219(with no associated curve) can be constructed by calling 220.Fn EC_KEY_new . 221The reference count for the newly created 222.Vt EC_KEY 223is initially set to 1. 224A curve can be associated with the 225.Vt EC_KEY 226by calling 227.Fn EC_KEY_set_group . 228.Pp 229Alternatively a new 230.Vt EC_KEY 231can be constructed by calling 232.Fn EC_KEY_new_by_curve_name 233and supplying the 234.Fa nid 235of the associated curve. 236Refer to 237.Xr EC_GROUP_new 3 238for a description of curve names. 239This function simply wraps calls to 240.Fn EC_KEY_new 241and 242.Fn EC_GROUP_new_by_curve_name . 243.Pp 244Calling 245.Fn EC_KEY_free 246decrements the reference count for the 247.Vt EC_KEY 248object and, if it has dropped to zero, then frees the memory associated 249with it. 250If 251.Fa key 252is a 253.Dv NULL 254pointer, no action occurs. 255.Pp 256.Fn EC_KEY_copy 257copies the contents of the 258.Vt EC_KEY 259in 260.Fa src 261into 262.Fa dst . 263.Pp 264.Fn EC_KEY_dup 265creates a new 266.Vt EC_KEY 267object and copies 268.Fa src 269into it. 270.Pp 271.Fn EC_KEY_up_ref 272increments the reference count associated with the 273.Vt EC_KEY 274object. 275.Pp 276.Fn EC_KEY_generate_key 277generates a new public and private key for the supplied 278.Fa key 279object. 280.Fa key 281must have an 282.Vt EC_GROUP 283object associated with it before calling this function. 284The private key is a random integer (0 < priv_key < order, where order 285is the order of the 286.Vt EC_GROUP 287object). 288The public key is an 289.Vt EC_POINT 290on the curve calculated by multiplying the generator for the curve 291by the private key. 292.Pp 293.Fn EC_KEY_check_key 294performs various sanity checks on the 295.Vt EC_KEY 296object to confirm that it is valid. 297.Pp 298.Fn EC_KEY_set_public_key_affine_coordinates 299sets the public key for 300.Fa key 301based on its affine coordinates, i.e. it constructs an 302.Vt EC_POINT 303object based on the supplied 304.Fa x 305and 306.Fa y 307values and sets the public key to be this 308.Vt EC_POINT . 309It also performs certain sanity checks on the key to confirm that 310it is valid. 311.Pp 312The functions 313.Fn EC_KEY_get0_group , 314.Fn EC_KEY_set_group , 315.Fn EC_KEY_get0_private_key , 316.Fn EC_KEY_set_private_key , 317.Fn EC_KEY_get0_public_key , 318and 319.Fn EC_KEY_set_public_key 320get and set the 321.Vt EC_GROUP 322object, the private key and the 323.Vt EC_POINT 324public key for the 325.Fa key , 326respectively. 327.Pp 328The functions 329.Fn EC_KEY_get_enc_flags 330and 331.Fn EC_KEY_set_enc_flags 332get and set the value of the encoding flags for the 333.Fa key . 334There are two encoding flags currently defined: 335.Dv EC_PKEY_NO_PARAMETERS 336and 337.Dv EC_PKEY_NO_PUBKEY . 338These flags define the behaviour of how the 339.Fa key 340is converted into ASN.1 in a call to 341.Fn i2d_ECPrivateKey . 342If 343.Dv EC_PKEY_NO_PARAMETERS 344is set then the public parameters for the curve 345are not encoded along with the private key. 346If 347.Dv EC_PKEY_NO_PUBKEY 348is set then the public key is not encoded along with the private 349key. 350.Pp 351The format of the external representation of the public key written by 352.Xr i2d_ECPrivateKey 3 , 353such as whether it is stored in a compressed form or not, 354is described by the point_conversion_form. 355See 356.Xr EC_GROUP_copy 3 357for a description of point_conversion_form. 358.Pp 359When reading a private key encoded without an associated public key, 360for example if 361.Dv EC_PKEY_NO_PUBKEY 362was used, 363.Xr d2i_ECPrivateKey 3 364generates the missing public key automatically. 365Private keys encoded without parameters, for example if 366.Dv EC_PKEY_NO_PARAMETERS 367was used, cannot be loaded using 368.Xr d2i_ECPrivateKey 3 . 369.Pp 370The functions 371.Fn EC_KEY_get_conv_form 372and 373.Fn EC_KEY_set_conv_form 374get and set the point_conversion_form for the 375.Fa key . 376For a description of point_conversion_form please refer to 377.Xr EC_GROUP_copy 3 . 378.Pp 379.Fn EC_KEY_set_flags 380sets the flags in the 381.Fa flags 382parameter on the 383.Vt EC_KEY 384object. 385Any flags that are already set are left set. 386The currently defined standard flags are 387.Dv EC_FLAG_NON_FIPS_ALLOW 388and 389.Dv EC_FLAG_FIPS_CHECKED . 390In addition there is the flag 391.Dv EC_FLAG_COFACTOR_ECDH 392which is specific to ECDH and is defined in 393.In openssl/ecdh.h . 394.Fn EC_KEY_get_flags 395returns the current flags that are set for this 396.Vt EC_KEY . 397.Fn EC_KEY_clear_flags 398clears the flags indicated by the 399.Fa flags 400parameter. 401All other flags are left in their existing state. 402.Pp 403.Fn EC_KEY_set_asn1_flag 404sets the asn1_flag on the underlying 405.Vt EC_GROUP 406object (if set). 407Refer to 408.Xr EC_GROUP_copy 3 409for further information on the asn1_flag. 410.Pp 411.Fn EC_KEY_precompute_mult 412stores multiples of the underlying 413.Vt EC_GROUP 414generator for faster point multiplication. 415See also 416.Xr EC_POINT_add 3 . 417.Pp 418.Fn EC_KEY_print 419and 420.Fn EC_KEY_print_fp 421print out the content of 422.Fa key 423to the 424.Vt BIO 425.Fa bp 426or to the 427.Vt FILE 428pointer 429.Fa fp , 430respectively. 431Each line is indented by 432.Fa indent 433spaces. 434.Sh RETURN VALUES 435.Fn EC_KEY_new , 436.Fn EC_KEY_new_by_curve_name , 437and 438.Fn EC_KEY_dup 439return a pointer to the newly created 440.Vt EC_KEY object 441or 442.Dv NULL 443on error. 444.Pp 445.Fn EC_KEY_get_flags 446returns the flags associated with the 447.Vt EC_KEY object . 448.Pp 449.Fn EC_KEY_copy 450returns a pointer to the destination key or 451.Dv NULL 452on error. 453In the latter case, part of the content may already have been copied. 454.Pp 455.Fn EC_KEY_up_ref , 456.Fn EC_KEY_set_group , 457.Fn EC_KEY_set_private_key , 458.Fn EC_KEY_set_public_key , 459.Fn EC_KEY_precompute_mult , 460.Fn EC_KEY_generate_key , 461.Fn EC_KEY_check_key , 462.Fn EC_KEY_set_public_key_affine_coordinates , 463.Fn EC_KEY_print , 464and 465.Fn EC_KEY_print_fp 466return 1 on success or 0 on error. 467.Pp 468.Fn EC_KEY_get0_group 469returns the 470.Vt EC_GROUP 471associated with the 472.Vt EC_KEY . 473.Pp 474.Fn EC_KEY_get0_private_key 475and 476.Fn EC_KEY_get0_public_key 477return the private or public keys, respectively, associated with the 478.Vt EC_KEY . 479.Pp 480.Fn EC_KEY_get_enc_flags 481returns the value of the current encoding flags for the 482.Vt EC_KEY . 483.Pp 484.Fn EC_KEY_get_conv_form 485returns the point_conversion_form for the 486.Vt EC_KEY . 487.Sh SEE ALSO 488.Xr d2i_ECPKParameters 3 , 489.Xr EC_GFp_simple_method 3 , 490.Xr EC_GROUP_copy 3 , 491.Xr EC_GROUP_new 3 , 492.Xr EC_KEY_METHOD_new 3 , 493.Xr EC_POINT_add 3 , 494.Xr EC_POINT_new 3 , 495.Xr ECDH_compute_key 3 , 496.Xr ECDSA_SIG_new 3 , 497.Xr EVP_PKEY_set1_EC_KEY 3 498.Sh HISTORY 499.Fn EC_KEY_new , 500.Fn EC_KEY_new_by_curve_name , 501.Fn EC_KEY_free , 502.Fn EC_KEY_copy , 503.Fn EC_KEY_dup , 504.Fn EC_KEY_up_ref , 505.Fn EC_KEY_get0_group , 506.Fn EC_KEY_set_group , 507.Fn EC_KEY_get0_private_key , 508.Fn EC_KEY_set_private_key , 509.Fn EC_KEY_get0_public_key , 510.Fn EC_KEY_set_public_key , 511.Fn EC_KEY_get_enc_flags , 512.Fn EC_KEY_set_enc_flags , 513.Fn EC_KEY_get_conv_form , 514.Fn EC_KEY_set_conv_form , 515.Fn EC_KEY_set_asn1_flag , 516.Fn EC_KEY_precompute_mult , 517.Fn EC_KEY_generate_key , 518.Fn EC_KEY_check_key , 519.Fn EC_KEY_print , 520and 521.Fn EC_KEY_print_fp 522first appeared in OpenSSL 0.9.8 and have been available since 523.Ox 4.5 . 524.Pp 525.Fn EC_KEY_get_flags , 526.Fn EC_KEY_set_flags , 527.Fn EC_KEY_clear_flags , 528and 529.Fn EC_KEY_set_public_key_affine_coordinates 530first appeared in OpenSSL 1.0.1 and have been available since 531.Ox 5.3 . 532