1.\" $OpenBSD: EC_GROUP_copy.3,v 1.12 2021/09/14 13:47:59 schwarze Exp $ 2.\" full merge up to: OpenSSL d900a015 Oct 8 14:40:42 2015 +0200 3.\" selective merge up to: OpenSSL 24c23e1f Aug 22 10:51:25 2019 +0530 4.\" 5.\" This file was written by Matt Caswell <matt@openssl.org>, 6.\" Dr. Stephen Henson <steve@openssl.org>, 7.\" and Jayaram X Matta <jayaramx.matta@intel.com>. 8.\" Copyright (c) 2013, 2015, 2019 The OpenSSL Project. All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: September 14 2021 $ 55.Dt EC_GROUP_COPY 3 56.Os 57.Sh NAME 58.Nm EC_GROUP_copy , 59.Nm EC_GROUP_dup , 60.Nm EC_GROUP_method_of , 61.Nm EC_GROUP_set_generator , 62.Nm EC_GROUP_get0_generator , 63.Nm EC_GROUP_get_order , 64.Nm EC_GROUP_order_bits , 65.Nm EC_GROUP_get_cofactor , 66.Nm EC_GROUP_set_curve_name , 67.Nm EC_GROUP_get_curve_name , 68.Nm EC_GROUP_set_asn1_flag , 69.Nm EC_GROUP_get_asn1_flag , 70.Nm EC_GROUP_set_point_conversion_form , 71.Nm EC_GROUP_get_point_conversion_form , 72.Nm EC_GROUP_get0_seed , 73.Nm EC_GROUP_get_seed_len , 74.Nm EC_GROUP_set_seed , 75.Nm EC_GROUP_get_degree , 76.Nm EC_GROUP_check , 77.Nm EC_GROUP_check_discriminant , 78.Nm EC_GROUP_cmp , 79.Nm EC_GROUP_get_basis_type , 80.Nm EC_GROUP_get_trinomial_basis , 81.Nm EC_GROUP_get_pentanomial_basis 82.Nd manipulate EC_GROUP objects 83.Sh SYNOPSIS 84.In openssl/ec.h 85.In openssl/bn.h 86.Ft int 87.Fo EC_GROUP_copy 88.Fa "EC_GROUP *dst" 89.Fa "const EC_GROUP *src" 90.Fc 91.Ft EC_GROUP * 92.Fo EC_GROUP_dup 93.Fa "const EC_GROUP *src" 94.Fc 95.Ft const EC_METHOD * 96.Fo EC_GROUP_method_of 97.Fa "const EC_GROUP *group" 98.Fc 99.Ft int 100.Fo EC_GROUP_set_generator 101.Fa "EC_GROUP *group" 102.Fa "const EC_POINT *generator" 103.Fa "const BIGNUM *order" 104.Fa "const BIGNUM *cofactor" 105.Fc 106.Ft const EC_POINT * 107.Fo EC_GROUP_get0_generator 108.Fa "const EC_GROUP *group" 109.Fc 110.Ft int 111.Fo EC_GROUP_get_order 112.Fa "const EC_GROUP *group" 113.Fa "BIGNUM *order" 114.Fa "BN_CTX *ctx" 115.Fc 116.Ft int 117.Fo EC_GROUP_order_bits 118.Fa "const EC_GROUP *group" 119.Fc 120.Ft int 121.Fo EC_GROUP_get_cofactor 122.Fa "const EC_GROUP *group" 123.Fa "BIGNUM *cofactor" 124.Fa "BN_CTX *ctx" 125.Fc 126.Ft void 127.Fo EC_GROUP_set_curve_name 128.Fa "EC_GROUP *group" 129.Fa "int nid" 130.Fc 131.Ft int 132.Fo EC_GROUP_get_curve_name 133.Fa "const EC_GROUP *group" 134.Fc 135.Ft void 136.Fo EC_GROUP_set_asn1_flag 137.Fa "EC_GROUP *group" 138.Fa "int flag" 139.Fc 140.Ft int 141.Fo EC_GROUP_get_asn1_flag 142.Fa "const EC_GROUP *group" 143.Fc 144.Ft void 145.Fo EC_GROUP_set_point_conversion_form 146.Fa "EC_GROUP *group" 147.Fa "point_conversion_form_t form" 148.Fc 149.Ft point_conversion_form_t 150.Fo EC_GROUP_get_point_conversion_form 151.Fa "const EC_GROUP *" 152.Fc 153.Ft unsigned char * 154.Fo EC_GROUP_get0_seed 155.Fa "const EC_GROUP *x" 156.Fc 157.Ft size_t 158.Fo EC_GROUP_get_seed_len 159.Fa "const EC_GROUP *" 160.Fc 161.Ft size_t 162.Fo EC_GROUP_set_seed 163.Fa "EC_GROUP *" 164.Fa "const unsigned char *" 165.Fa "size_t len" 166.Fc 167.Ft int 168.Fo EC_GROUP_get_degree 169.Fa "const EC_GROUP *group" 170.Fc 171.Ft int 172.Fo EC_GROUP_check 173.Fa "const EC_GROUP *group" 174.Fa "BN_CTX *ctx" 175.Fc 176.Ft int 177.Fo EC_GROUP_check_discriminant 178.Fa "const EC_GROUP *group" 179.Fa "BN_CTX *ctx" 180.Fc 181.Ft int 182.Fo EC_GROUP_cmp 183.Fa "const EC_GROUP *a" 184.Fa "const EC_GROUP *b" 185.Fa "BN_CTX *ctx" 186.Fc 187.Ft int 188.Fo EC_GROUP_get_basis_type 189.Fa "const EC_GROUP *" 190.Fc 191.Ft int 192.Fo EC_GROUP_get_trinomial_basis 193.Fa "const EC_GROUP *" 194.Fa "unsigned int *k" 195.Fc 196.Ft int 197.Fo EC_GROUP_get_pentanomial_basis 198.Fa "const EC_GROUP *" 199.Fa "unsigned int *k1" 200.Fa "unsigned int *k2" 201.Fa "unsigned int *k3" 202.Fc 203.Sh DESCRIPTION 204These functions operate on 205.Vt EC_GROUP 206objects created by the functions described in 207.Xr EC_GROUP_new 3 . 208.Pp 209.Fn EC_GROUP_copy 210copies the curve 211.Fa src 212into 213.Fa dst . 214Both 215.Fa src 216and 217.Fa dst 218must use the same 219.Vt EC_METHOD . 220.Pp 221.Fn EC_GROUP_dup 222creates a new 223.Vt EC_GROUP 224object and copies the content from 225.Fa src 226to the newly created 227.Vt EC_GROUP 228object. 229.Pp 230.Fn EC_GROUP_method_of 231obtains the 232.Vt EC_METHOD 233of 234.Fa group . 235.Pp 236.Fn EC_GROUP_set_generator 237sets curve parameters that must be agreed by all participants using 238the curve. 239These parameters include the 240.Fa generator , 241the 242.Fa order 243and the 244.Fa cofactor . 245The 246.Fa generator 247is a well defined point on the curve chosen for cryptographic 248operations. 249Integers used for point multiplications will be between 0 and 250.Fa order No - 1 . 251The 252.Fa order 253multiplied by the 254.Fa cofactor 255gives the number of points on the curve. 256.Pp 257.Fn EC_GROUP_get0_generator 258returns the generator for the identified 259.Fa group . 260.Pp 261.Fn EC_GROUP_get_order 262retrieves the order of the 263.Fa group 264and copies its value into 265.Fa order . 266It fails if the order of the 267.Fa group 268is not set or set to zero. 269.Pp 270.Fn EC_GROUP_get_cofactor 271retrieves the cofactor of the 272.Fa group 273and copies its value into 274.Fa cofactor . 275It fails if the cofactor of the 276.Fa group 277is not set or set to zero. 278.Pp 279The functions 280.Fn EC_GROUP_set_curve_name 281and 282.Fn EC_GROUP_get_curve_name 283set and get the NID for the curve, respectively (see 284.Xr EC_GROUP_new 3 ) . 285If a curve does not have a NID associated with it, then 286.Fn EC_GROUP_get_curve_name 287will return 288.Dv NID_undef . 289.Pp 290The asn1_flag value is used to determine whether the curve encoding 291uses explicit parameters or a named curve using an ASN.1 OID: 292many applications only support the latter form. 293If asn1_flag is the default value 294.Dv OPENSSL_EC_NAMED_CURVE , 295then the named curve form is used and the parameters must have a 296corresponding named curve NID set. 297If asn1_flags is 298.Dv OPENSSL_EC_EXPLICIT_CURVE , 299the parameters are explicitly encoded. 300The functions 301.Fn EC_GROUP_get_asn1_flag 302and 303.Fn EC_GROUP_set_asn1_flag 304get and set the status of the asn1_flag for the curve. 305.Pp 306The point_conversion_form for a curve controls how 307.Vt EC_POINT 308data is encoded as ASN.1 as defined in X9.62 (ECDSA). 309.Vt point_conversion_form_t 310is an enum defined as follows: 311.Bd -literal 312typedef enum { 313 /** the point is encoded as z||x, where the octet z specifies 314 * which solution of the quadratic equation y is */ 315 POINT_CONVERSION_COMPRESSED = 2, 316 /** the point is encoded as z||x||y, where z is the octet 0x04 */ 317 POINT_CONVERSION_UNCOMPRESSED = 4, 318 /** the point is encoded as z||x||y, where the octet z specifies 319 * which solution of the quadratic equation y is */ 320 POINT_CONVERSION_HYBRID = 6 321} point_conversion_form_t; 322.Ed 323.Pp 324For 325.Dv POINT_CONVERSION_UNCOMPRESSED 326the point is encoded as an octet signifying the UNCOMPRESSED form 327has been used followed by the octets for x, followed by the octets 328for y. 329.Pp 330For any given x coordinate for a point on a curve it is possible to 331derive two possible y values. 332For 333.Dv POINT_CONVERSION_COMPRESSED 334the point is encoded as an octet signifying that the COMPRESSED 335form has been used AND which of the two possible solutions for y 336has been used, followed by the octets for x. 337.Pp 338For 339.Dv POINT_CONVERSION_HYBRID 340the point is encoded as an octet signifying the HYBRID form has 341been used AND which of the two possible solutions for y has been 342used, followed by the octets for x, followed by the octets for y. 343.Pp 344The functions 345.Fn EC_GROUP_set_point_conversion_form 346and 347.Fn EC_GROUP_get_point_conversion_form 348set and get the point_conversion_form for the curve, respectively. 349.Pp 350ANSI X9.62 (ECDSA standard) defines a method of generating the curve 351parameter b from a random number. 352This provides advantages in that a parameter obtained in this way is 353highly unlikely to be susceptible to special purpose attacks, or have 354any trapdoors in it. 355If the seed is present for a curve then the b parameter was generated in 356a verifiable fashion using that seed. 357The OpenSSL EC library does not use this seed value but does enable you 358to inspect it using 359.Fn EC_GROUP_get0_seed . 360This returns a pointer to a memory block containing the seed that was 361used. 362The length of the memory block can be obtained using 363.Fn EC_GROUP_get_seed_len . 364A number of the builtin curves within the library provide seed values 365that can be obtained. 366It is also possible to set a custom seed using 367.Fn EC_GROUP_set_seed 368and passing a pointer to a memory block, along with the length of 369the seed. 370Again, the EC library will not use this seed value, although it will be 371preserved in any ASN.1 based communications. 372.Pp 373.Fn EC_GROUP_get_degree 374gets the degree of the field. 375For Fp fields this will be the number of bits in p. 376For F2^m fields this will be the value m. 377.Pp 378The function 379.Fn EC_GROUP_check_discriminant 380calculates the discriminant for the curve and verifies that it is 381valid. 382For a curve defined over Fp the discriminant is given by the formula 3834*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b. 384In either case for the curve to be valid the discriminant must be 385non-zero. 386.Pp 387The function 388.Fn EC_GROUP_check 389performs a number of checks on a curve to verify that it is valid. 390Checks performed include verifying that the discriminant is non-zero; 391that a generator has been defined; that the generator is on the curve 392and has the correct order. 393.Pp 394.Fn EC_GROUP_cmp 395compares 396.Fa a 397and 398.Fa b 399to determine whether they represent the same curve or not. 400.Pp 401The functions 402.Fn EC_GROUP_get_basis_type , 403.Fn EC_GROUP_get_trinomial_basis , 404and 405.Fn EC_GROUP_get_pentanomial_basis 406should only be called for curves defined over an F2^m field. 407Addition and multiplication operations within an F2^m field are 408performed using an irreducible polynomial function f(x). 409This function is either a trinomial of the form: 410.Pp 411.Dl f(x) = x^m + x^k + 1 with m > k >= 1 412.Pp 413or a pentanomial of the form: 414.Pp 415.Dl f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 416.Pp 417The function 418.Fn EC_GROUP_get_basis_type 419returns a NID identifying whether a trinomial or pentanomial is in 420use for the field. 421The function 422.Fn EC_GROUP_get_trinomial_basis 423must only be called where f(x) is of the trinomial form, and returns 424the value of 425.Fa k . 426Similarly, the function 427.Fn EC_GROUP_get_pentanomial_basis 428must only be called where f(x) is of the pentanomial form, and 429returns the values of 430.Fa k1 , 431.Fa k2 , 432and 433.Fa k3 . 434.Sh RETURN VALUES 435The following functions return 1 on success or 0 on error: 436.Fn EC_GROUP_copy , 437.Fn EC_GROUP_set_generator , 438.Fn EC_GROUP_check , 439.Fn EC_GROUP_check_discriminant , 440.Fn EC_GROUP_get_trinomial_basis , 441and 442.Fn EC_GROUP_get_pentanomial_basis . 443.Pp 444.Fn EC_GROUP_dup 445returns a pointer to the duplicated curve or 446.Dv NULL 447on error. 448.Pp 449.Fn EC_GROUP_method_of 450returns the 451.Vt EC_METHOD 452implementation in use for the given curve or 453.Dv NULL 454on error. 455.Pp 456.Fn EC_GROUP_get0_generator 457returns the generator for the given curve or 458.Dv NULL 459on error. 460.Pp 461.Fn EC_GROUP_get_order 462returns 0 if the order is not set or set to zero for the 463.Fa group 464or if copying into 465.Fa order 466fails, or 1 otherwise. 467.Pp 468.Fn EC_GROUP_order_bits 469returns the number of bits in the group order. 470.Pp 471.Fn EC_GROUP_get_cofactor 472returns 0 if the cofactor is not set or set to zero for the 473.Fa group 474or if copying into 475.Fa cofactor 476fails, or 1 otherwise. 477.Pp 478.Fn EC_GROUP_get_curve_name 479returns the curve name (NID) for the 480.Fa group 481or 482.Dv NID_undef 483if no curve name is associated. 484.Pp 485.Fn EC_GROUP_get_asn1_flag 486returns the ASN.1 flag for the specified 487.Fa group . 488.Pp 489.Fn EC_GROUP_get_point_conversion_form 490returns the point_conversion_form for the 491.Fa group . 492.Pp 493.Fn EC_GROUP_get_degree 494returns the degree for the 495.Fa group 496or 0 if the operation is not supported 497by the underlying group implementation. 498.Pp 499.Fn EC_GROUP_get0_seed 500returns a pointer to the seed that was used to generate the parameter 501b, or 502.Dv NULL 503if the seed is not specified. 504.Fn EC_GROUP_get_seed_len 505returns the length of the seed or 0 if the seed is not specified. 506.Pp 507.Fn EC_GROUP_set_seed 508returns the length of the seed that has been set. 509If the supplied seed is 510.Dv NULL 511or the supplied seed length is 0, the return value will be 1. 512On error 0 is returned. 513.Pp 514.Fn EC_GROUP_cmp 515returns 0 if the curves are equal, 1 if they are not equal, 516or -1 on error. 517.Pp 518.Fn EC_GROUP_get_basis_type 519returns the values 520.Dv NID_X9_62_tpBasis 521or 522.Dv NID_X9_62_ppBasis 523as defined in 524.In openssl/obj_mac.h 525for a trinomial or pentanomial, respectively. 526Alternatively in the event of an error a 0 is returned. 527.Sh SEE ALSO 528.Xr d2i_ECPKParameters 3 , 529.Xr EC_GFp_simple_method 3 , 530.Xr EC_GROUP_new 3 , 531.Xr EC_KEY_new 3 , 532.Xr EC_POINT_add 3 , 533.Xr EC_POINT_new 3 534.Sh HISTORY 535.Fn EC_GROUP_copy , 536.Fn EC_GROUP_method_of , 537.Fn EC_GROUP_set_generator , 538.Fn EC_GROUP_get0_generator , 539.Fn EC_GROUP_get_order , 540and 541.Fn EC_GROUP_get_cofactor 542first appeared in OpenSSL 0.9.7 and have been available since 543.Ox 3.2 . 544.Pp 545.Fn EC_GROUP_dup , 546.Fn EC_GROUP_set_curve_name , 547.Fn EC_GROUP_get_curve_name , 548.Fn EC_GROUP_set_asn1_flag , 549.Fn EC_GROUP_get_asn1_flag , 550.Fn EC_GROUP_set_point_conversion_form , 551.Fn EC_GROUP_get_point_conversion_form , 552.Fn EC_GROUP_get0_seed , 553.Fn EC_GROUP_get_seed_len , 554.Fn EC_GROUP_set_seed , 555.Fn EC_GROUP_get_degree , 556.Fn EC_GROUP_check , 557.Fn EC_GROUP_check_discriminant , 558.Fn EC_GROUP_cmp , 559.Fn EC_GROUP_get_basis_type , 560.Fn EC_GROUP_get_trinomial_basis , 561and 562.Fn EC_GROUP_get_pentanomial_basis 563first appeared in OpenSSL 0.9.8 and has been available since 564.Ox 4.5 . 565.Pp 566.Fn EC_GROUP_order_bits 567first appeared in OpenSSL 1.1.0 and has been available since 568.Ox 7.0 . 569