1.\" $OpenBSD: EC_KEY_new.3,v 1.18 2023/08/29 10:07:42 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: August 29 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 ECDH-specific flag 391.Dv EC_FLAG_COFACTOR_ECDH . 392.Fn EC_KEY_get_flags 393returns the current flags that are set for this 394.Vt EC_KEY . 395.Fn EC_KEY_clear_flags 396clears the flags indicated by the 397.Fa flags 398parameter. 399All other flags are left in their existing state. 400.Pp 401.Fn EC_KEY_set_asn1_flag 402sets the asn1_flag on the underlying 403.Vt EC_GROUP 404object (if set). 405Refer to 406.Xr EC_GROUP_copy 3 407for further information on the asn1_flag. 408.Pp 409.Fn EC_KEY_precompute_mult 410stores multiples of the underlying 411.Vt EC_GROUP 412generator for faster point multiplication. 413See also 414.Xr EC_POINT_add 3 . 415.Pp 416.Fn EC_KEY_print 417and 418.Fn EC_KEY_print_fp 419print out the content of 420.Fa key 421to the 422.Vt BIO 423.Fa bp 424or to the 425.Vt FILE 426pointer 427.Fa fp , 428respectively. 429Each line is indented by 430.Fa indent 431spaces. 432.Sh RETURN VALUES 433.Fn EC_KEY_new , 434.Fn EC_KEY_new_by_curve_name , 435and 436.Fn EC_KEY_dup 437return a pointer to the newly created 438.Vt EC_KEY object 439or 440.Dv NULL 441on error. 442.Pp 443.Fn EC_KEY_get_flags 444returns the flags associated with the 445.Vt EC_KEY object . 446.Pp 447.Fn EC_KEY_copy 448returns a pointer to the destination key or 449.Dv NULL 450on error. 451In the latter case, part of the content may already have been copied. 452.Pp 453.Fn EC_KEY_up_ref , 454.Fn EC_KEY_set_group , 455.Fn EC_KEY_set_private_key , 456.Fn EC_KEY_set_public_key , 457.Fn EC_KEY_precompute_mult , 458.Fn EC_KEY_generate_key , 459.Fn EC_KEY_check_key , 460.Fn EC_KEY_set_public_key_affine_coordinates , 461.Fn EC_KEY_print , 462and 463.Fn EC_KEY_print_fp 464return 1 on success or 0 on error. 465.Pp 466.Fn EC_KEY_get0_group 467returns the 468.Vt EC_GROUP 469associated with the 470.Vt EC_KEY . 471.Pp 472.Fn EC_KEY_get0_private_key 473and 474.Fn EC_KEY_get0_public_key 475return the private or public keys, respectively, associated with the 476.Vt EC_KEY . 477.Pp 478.Fn EC_KEY_get_enc_flags 479returns the value of the current encoding flags for the 480.Vt EC_KEY . 481.Pp 482.Fn EC_KEY_get_conv_form 483returns the point_conversion_form for the 484.Vt EC_KEY . 485.Sh SEE ALSO 486.Xr d2i_ECPKParameters 3 , 487.Xr EC_GFp_simple_method 3 , 488.Xr EC_GROUP_copy 3 , 489.Xr EC_GROUP_new 3 , 490.Xr EC_KEY_METHOD_new 3 , 491.Xr EC_POINT_add 3 , 492.Xr EC_POINT_new 3 , 493.Xr ECDH_compute_key 3 , 494.Xr ECDSA_SIG_new 3 , 495.Xr EVP_PKEY_set1_EC_KEY 3 496.Sh HISTORY 497.Fn EC_KEY_new , 498.Fn EC_KEY_new_by_curve_name , 499.Fn EC_KEY_free , 500.Fn EC_KEY_copy , 501.Fn EC_KEY_dup , 502.Fn EC_KEY_up_ref , 503.Fn EC_KEY_get0_group , 504.Fn EC_KEY_set_group , 505.Fn EC_KEY_get0_private_key , 506.Fn EC_KEY_set_private_key , 507.Fn EC_KEY_get0_public_key , 508.Fn EC_KEY_set_public_key , 509.Fn EC_KEY_get_enc_flags , 510.Fn EC_KEY_set_enc_flags , 511.Fn EC_KEY_get_conv_form , 512.Fn EC_KEY_set_conv_form , 513.Fn EC_KEY_set_asn1_flag , 514.Fn EC_KEY_precompute_mult , 515.Fn EC_KEY_generate_key , 516.Fn EC_KEY_check_key , 517.Fn EC_KEY_print , 518and 519.Fn EC_KEY_print_fp 520first appeared in OpenSSL 0.9.8 and have been available since 521.Ox 4.5 . 522.Pp 523.Fn EC_KEY_get_flags , 524.Fn EC_KEY_set_flags , 525.Fn EC_KEY_clear_flags , 526and 527.Fn EC_KEY_set_public_key_affine_coordinates 528first appeared in OpenSSL 1.0.1 and have been available since 529.Ox 5.3 . 530