1.\" $OpenBSD: EC_KEY_new.3,v 1.16 2020/09/08 03:25:15 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: September 8 2020 $ 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_get_key_method_data , 76.Nm EC_KEY_insert_key_method_data , 77.Nm EC_KEY_set_asn1_flag , 78.Nm EC_KEY_precompute_mult , 79.Nm EC_KEY_generate_key , 80.Nm EC_KEY_check_key , 81.Nm EC_KEY_set_public_key_affine_coordinates , 82.Nm EC_KEY_print , 83.Nm EC_KEY_print_fp 84.Nd create, destroy and manipulate EC_KEY objects 85.Sh SYNOPSIS 86.In openssl/ec.h 87.In openssl/bn.h 88.Ft EC_KEY * 89.Fn EC_KEY_new void 90.Ft int 91.Fo EC_KEY_get_flags 92.Fa "const EC_KEY *key" 93.Fc 94.Ft void 95.Fo EC_KEY_set_flags 96.Fa "EC_KEY *key" 97.Fa "int flags" 98.Fc 99.Ft void 100.Fo EC_KEY_clear_flags 101.Fa "EC_KEY *key" 102.Fa "int flags" 103.Fc 104.Ft EC_KEY * 105.Fo EC_KEY_new_by_curve_name 106.Fa "int nid" 107.Fc 108.Ft void 109.Fo EC_KEY_free 110.Fa "EC_KEY *key" 111.Fc 112.Ft EC_KEY * 113.Fo EC_KEY_copy 114.Fa "EC_KEY *dst" 115.Fa "const EC_KEY *src" 116.Fc 117.Ft EC_KEY * 118.Fo EC_KEY_dup 119.Fa "const EC_KEY *src" 120.Fc 121.Ft int 122.Fo EC_KEY_up_ref 123.Fa "EC_KEY *key" 124.Fc 125.Ft const EC_GROUP * 126.Fo EC_KEY_get0_group 127.Fa "const EC_KEY *key" 128.Fc 129.Ft int 130.Fo EC_KEY_set_group 131.Fa "EC_KEY *key" 132.Fa "const EC_GROUP *group" 133.Fc 134.Ft const BIGNUM * 135.Fo EC_KEY_get0_private_key 136.Fa "const EC_KEY *key" 137.Fc 138.Ft int 139.Fo EC_KEY_set_private_key 140.Fa "EC_KEY *key" 141.Fa "const BIGNUM *prv" 142.Fc 143.Ft const EC_POINT * 144.Fo EC_KEY_get0_public_key 145.Fa "const EC_KEY *key" 146.Fc 147.Ft int 148.Fo EC_KEY_set_public_key 149.Fa "EC_KEY *key" 150.Fa "const EC_POINT *pub" 151.Fc 152.Ft unsigned int 153.Fo EC_KEY_get_enc_flags 154.Fa "const EC_KEY *key" 155.Fc 156.Ft void 157.Fo EC_KEY_set_enc_flags 158.Fa "EC_KEY *key" 159.Fa "unsigned int flags" 160.Fc 161.Ft point_conversion_form_t 162.Fo EC_KEY_get_conv_form 163.Fa "const EC_KEY *key" 164.Fc 165.Ft void 166.Fo EC_KEY_set_conv_form 167.Fa "EC_KEY *key" 168.Fa "point_conversion_form_t cform" 169.Fc 170.Ft void * 171.Fo EC_KEY_get_key_method_data 172.Fa "EC_KEY *key" 173.Fa "void *(*dup_func)(void *)" 174.Fa "void (*free_func)(void *)" 175.Fa "void (*clear_free_func)(void *)" 176.Fc 177.Ft void 178.Fo EC_KEY_insert_key_method_data 179.Fa "EC_KEY *key" 180.Fa "void *data" 181.Fa "void *(*dup_func)(void *)" 182.Fa "void (*free_func)(void *)" 183.Fa "void (*clear_free_func)(void *)" 184.Fc 185.Ft void 186.Fo EC_KEY_set_asn1_flag 187.Fa "EC_KEY *key" 188.Fa "int asn1_flag" 189.Fc 190.Ft int 191.Fo EC_KEY_precompute_mult 192.Fa "EC_KEY *key" 193.Fa "BN_CTX *ctx" 194.Fc 195.Ft int 196.Fo EC_KEY_generate_key 197.Fa "EC_KEY *key" 198.Fc 199.Ft int 200.Fo EC_KEY_check_key 201.Fa "const EC_KEY *key" 202.Fc 203.Ft int 204.Fo EC_KEY_set_public_key_affine_coordinates 205.Fa "EC_KEY *key" 206.Fa "BIGNUM *x" 207.Fa "BIGNUM *y" 208.Fc 209.Ft int 210.Fo EC_KEY_print 211.Fa "BIO *bp" 212.Fa "const EC_KEY *key" 213.Fa "int off" 214.Fc 215.Ft int 216.Fo EC_KEY_print_fp 217.Fa "FILE *fp" 218.Fa "const EC_KEY *key" 219.Fa "int off" 220.Fc 221.Sh DESCRIPTION 222An 223.Vt EC_KEY 224represents a public key and (optionally) an associated private key. 225The public key is a point on a curve represented by an 226.Vt EC_POINT , 227see 228.Xr EC_POINT_new 3 . 229The private key is simply a 230.Vt BIGNUM , 231see 232.Xr BN_new 3 . 233.Pp 234A new 235.Vt EC_KEY 236(with no associated curve) can be constructed by calling 237.Fn EC_KEY_new . 238The reference count for the newly created 239.Vt EC_KEY 240is initially set to 1. 241A curve can be associated with the 242.Vt EC_KEY 243by calling 244.Fn EC_KEY_set_group . 245.Pp 246Alternatively a new 247.Vt EC_KEY 248can be constructed by calling 249.Fn EC_KEY_new_by_curve_name 250and supplying the 251.Fa nid 252of the associated curve. 253Refer to 254.Xr EC_GROUP_new 3 255for a description of curve names. 256This function simply wraps calls to 257.Fn EC_KEY_new 258and 259.Fn EC_GROUP_new_by_curve_name . 260.Pp 261Calling 262.Fn EC_KEY_free 263decrements the reference count for the 264.Vt EC_KEY 265object and, if it has dropped to zero, then frees the memory associated 266with it. 267If 268.Fa key 269is a 270.Dv NULL 271pointer, no action occurs. 272.Pp 273.Fn EC_KEY_copy 274copies the contents of the 275.Vt EC_KEY 276in 277.Fa src 278into 279.Fa dst . 280.Pp 281.Fn EC_KEY_dup 282creates a new 283.Vt EC_KEY 284object and copies 285.Fa src 286into it. 287.Pp 288.Fn EC_KEY_up_ref 289increments the reference count associated with the 290.Vt EC_KEY 291object. 292.Pp 293.Fn EC_KEY_generate_key 294generates a new public and private key for the supplied 295.Fa key 296object. 297.Fa key 298must have an 299.Vt EC_GROUP 300object associated with it before calling this function. 301The private key is a random integer (0 < priv_key < order, where order 302is the order of the 303.Vt EC_GROUP 304object). 305The public key is an 306.Vt EC_POINT 307on the curve calculated by multiplying the generator for the curve 308by the private key. 309.Pp 310.Fn EC_KEY_check_key 311performs various sanity checks on the 312.Vt EC_KEY 313object to confirm that it is valid. 314.Pp 315.Fn EC_KEY_set_public_key_affine_coordinates 316sets the public key for 317.Fa key 318based on its affine coordinates, i.e. it constructs an 319.Vt EC_POINT 320object based on the supplied 321.Fa x 322and 323.Fa y 324values and sets the public key to be this 325.Vt EC_POINT . 326It also performs certain sanity checks on the key to confirm that 327it is valid. 328.Pp 329The functions 330.Fn EC_KEY_get0_group , 331.Fn EC_KEY_set_group , 332.Fn EC_KEY_get0_private_key , 333.Fn EC_KEY_set_private_key , 334.Fn EC_KEY_get0_public_key , 335and 336.Fn EC_KEY_set_public_key 337get and set the 338.Vt EC_GROUP 339object, the private key and the 340.Vt EC_POINT 341public key for the 342.Fa key , 343respectively. 344.Pp 345The functions 346.Fn EC_KEY_get_enc_flags 347and 348.Fn EC_KEY_set_enc_flags 349get and set the value of the encoding flags for the 350.Fa key . 351There are two encoding flags currently defined: 352.Dv EC_PKEY_NO_PARAMETERS 353and 354.Dv EC_PKEY_NO_PUBKEY . 355These flags define the behaviour of how the 356.Fa key 357is converted into ASN.1 in a call to 358.Fn i2d_ECPrivateKey . 359If 360.Dv EC_PKEY_NO_PARAMETERS 361is set then the public parameters for the curve 362are not encoded along with the private key. 363If 364.Dv EC_PKEY_NO_PUBKEY 365is set then the public key is not encoded along with the private 366key. 367.Pp 368The format of the external representation of the public key written by 369.Xr i2d_ECPrivateKey 3 , 370such as whether it is stored in a compressed form or not, 371is described by the point_conversion_form. 372See 373.Xr EC_GROUP_copy 3 374for a description of point_conversion_form. 375.Pp 376When reading a private key encoded without an associated public key, 377for example if 378.Dv EC_PKEY_NO_PUBKEY 379was used, 380.Xr d2i_ECPrivateKey 3 381generates the missing public key automatically. 382Private keys encoded without parameters, for example if 383.Dv EC_PKEY_NO_PARAMETERS 384was used, cannot be loaded using 385.Xr d2i_ECPrivateKey 3 . 386.Pp 387The functions 388.Fn EC_KEY_get_conv_form 389and 390.Fn EC_KEY_set_conv_form 391get and set the point_conversion_form for the 392.Fa key . 393For a description of point_conversion_form please refer to 394.Xr EC_GROUP_copy 3 . 395.Pp 396.Fn EC_KEY_insert_key_method_data 397and 398.Fn EC_KEY_get_key_method_data 399enable the caller to associate arbitrary additional data specific 400to the elliptic curve scheme being used with the 401.Vt EC_KEY 402object. 403This data is treated as a "black box" by the EC library. 404The data to be stored by 405.Fn EC_KEY_insert_key_method_data 406is provided in the 407.Fa data 408parameter, which must have associated functions for duplicating, freeing 409and "clear_freeing" the data item. 410If a subsequent 411.Fn EC_KEY_get_key_method_data 412call is issued, the functions for duplicating, freeing and 413"clear_freeing" the data item must be provided again, and they must 414be the same as they were when the data item was inserted. 415.Pp 416.Fn EC_KEY_set_flags 417sets the flags in the 418.Fa flags 419parameter on the 420.Vt EC_KEY 421object. 422Any flags that are already set are left set. 423The currently defined standard flags are 424.Dv EC_FLAG_NON_FIPS_ALLOW 425and 426.Dv EC_FLAG_FIPS_CHECKED . 427In addition there is the flag 428.Dv EC_FLAG_COFACTOR_ECDH 429which is specific to ECDH and is defined in 430.In openssl/ecdh.h . 431.Fn EC_KEY_get_flags 432returns the current flags that are set for this 433.Vt EC_KEY . 434.Fn EC_KEY_clear_flags 435clears the flags indicated by the 436.Fa flags 437parameter. 438All other flags are left in their existing state. 439.Pp 440.Fn EC_KEY_set_asn1_flag 441sets the asn1_flag on the underlying 442.Vt EC_GROUP 443object (if set). 444Refer to 445.Xr EC_GROUP_copy 3 446for further information on the asn1_flag. 447.Pp 448.Fn EC_KEY_precompute_mult 449stores multiples of the underlying 450.Vt EC_GROUP 451generator for faster point multiplication. 452See also 453.Xr EC_POINT_add 3 . 454.Pp 455.Fn EC_KEY_print 456and 457.Fn EC_KEY_print_fp 458print out the content of 459.Fa key 460to the 461.Vt BIO 462.Fa bp 463or to the 464.Vt FILE 465pointer 466.Fa fp , 467respectively. 468Each line is indented by 469.Fa indent 470spaces. 471.Sh RETURN VALUES 472.Fn EC_KEY_new , 473.Fn EC_KEY_new_by_curve_name , 474and 475.Fn EC_KEY_dup 476return a pointer to the newly created 477.Vt EC_KEY object 478or 479.Dv NULL 480on error. 481.Pp 482.Fn EC_KEY_get_flags 483returns the flags associated with the 484.Vt EC_KEY object . 485.Pp 486.Fn EC_KEY_copy 487returns a pointer to the destination key or 488.Dv NULL 489on error. 490In the latter case, part of the content may already have been copied. 491.Pp 492.Fn EC_KEY_up_ref , 493.Fn EC_KEY_set_group , 494.Fn EC_KEY_set_private_key , 495.Fn EC_KEY_set_public_key , 496.Fn EC_KEY_precompute_mult , 497.Fn EC_KEY_generate_key , 498.Fn EC_KEY_check_key , 499.Fn EC_KEY_set_public_key_affine_coordinates , 500.Fn EC_KEY_print , 501and 502.Fn EC_KEY_print_fp 503return 1 on success or 0 on error. 504.Pp 505.Fn EC_KEY_get0_group 506returns the 507.Vt EC_GROUP 508associated with the 509.Vt EC_KEY . 510.Pp 511.Fn EC_KEY_get0_private_key 512and 513.Fn EC_KEY_get0_public_key 514return the private or public keys, respectively, associated with the 515.Vt EC_KEY . 516.Pp 517.Fn EC_KEY_get_enc_flags 518returns the value of the current encoding flags for the 519.Vt EC_KEY . 520.Pp 521.Fn EC_KEY_get_conv_form 522returns the point_conversion_form for the 523.Vt EC_KEY . 524.Sh SEE ALSO 525.Xr d2i_ECPKParameters 3 , 526.Xr EC_GFp_simple_method 3 , 527.Xr EC_GROUP_copy 3 , 528.Xr EC_GROUP_new 3 , 529.Xr EC_KEY_METHOD_new 3 , 530.Xr EC_POINT_add 3 , 531.Xr EC_POINT_new 3 , 532.Xr ECDH_compute_key 3 , 533.Xr ECDSA_SIG_new 3 , 534.Xr EVP_PKEY_set1_EC_KEY 3 535.Sh HISTORY 536.Fn EC_KEY_new , 537.Fn EC_KEY_new_by_curve_name , 538.Fn EC_KEY_free , 539.Fn EC_KEY_copy , 540.Fn EC_KEY_dup , 541.Fn EC_KEY_up_ref , 542.Fn EC_KEY_get0_group , 543.Fn EC_KEY_set_group , 544.Fn EC_KEY_get0_private_key , 545.Fn EC_KEY_set_private_key , 546.Fn EC_KEY_get0_public_key , 547.Fn EC_KEY_set_public_key , 548.Fn EC_KEY_get_enc_flags , 549.Fn EC_KEY_set_enc_flags , 550.Fn EC_KEY_get_conv_form , 551.Fn EC_KEY_set_conv_form , 552.Fn EC_KEY_get_key_method_data , 553.Fn EC_KEY_insert_key_method_data , 554.Fn EC_KEY_set_asn1_flag , 555.Fn EC_KEY_precompute_mult , 556.Fn EC_KEY_generate_key , 557.Fn EC_KEY_check_key , 558.Fn EC_KEY_print , 559and 560.Fn EC_KEY_print_fp 561first appeared in OpenSSL 0.9.8 and have been available since 562.Ox 4.5 . 563.Pp 564.Fn EC_KEY_get_flags , 565.Fn EC_KEY_set_flags , 566.Fn EC_KEY_clear_flags , 567and 568.Fn EC_KEY_set_public_key_affine_coordinates 569first appeared in OpenSSL 1.0.1 and have been available since 570.Ox 5.3 . 571