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