1.\" $OpenBSD: EC_GROUP_copy.3,v 1.14 2023/06/28 18:07:07 tb 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: June 28 2023 $ 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.Nd manipulate EC_GROUP objects 81.Sh SYNOPSIS 82.In openssl/ec.h 83.In openssl/bn.h 84.Ft int 85.Fo EC_GROUP_copy 86.Fa "EC_GROUP *dst" 87.Fa "const EC_GROUP *src" 88.Fc 89.Ft EC_GROUP * 90.Fo EC_GROUP_dup 91.Fa "const EC_GROUP *src" 92.Fc 93.Ft const EC_METHOD * 94.Fo EC_GROUP_method_of 95.Fa "const EC_GROUP *group" 96.Fc 97.Ft int 98.Fo EC_GROUP_set_generator 99.Fa "EC_GROUP *group" 100.Fa "const EC_POINT *generator" 101.Fa "const BIGNUM *order" 102.Fa "const BIGNUM *cofactor" 103.Fc 104.Ft const EC_POINT * 105.Fo EC_GROUP_get0_generator 106.Fa "const EC_GROUP *group" 107.Fc 108.Ft int 109.Fo EC_GROUP_get_order 110.Fa "const EC_GROUP *group" 111.Fa "BIGNUM *order" 112.Fa "BN_CTX *ctx" 113.Fc 114.Ft int 115.Fo EC_GROUP_order_bits 116.Fa "const EC_GROUP *group" 117.Fc 118.Ft int 119.Fo EC_GROUP_get_cofactor 120.Fa "const EC_GROUP *group" 121.Fa "BIGNUM *cofactor" 122.Fa "BN_CTX *ctx" 123.Fc 124.Ft void 125.Fo EC_GROUP_set_curve_name 126.Fa "EC_GROUP *group" 127.Fa "int nid" 128.Fc 129.Ft int 130.Fo EC_GROUP_get_curve_name 131.Fa "const EC_GROUP *group" 132.Fc 133.Ft void 134.Fo EC_GROUP_set_asn1_flag 135.Fa "EC_GROUP *group" 136.Fa "int flag" 137.Fc 138.Ft int 139.Fo EC_GROUP_get_asn1_flag 140.Fa "const EC_GROUP *group" 141.Fc 142.Ft void 143.Fo EC_GROUP_set_point_conversion_form 144.Fa "EC_GROUP *group" 145.Fa "point_conversion_form_t form" 146.Fc 147.Ft point_conversion_form_t 148.Fo EC_GROUP_get_point_conversion_form 149.Fa "const EC_GROUP *" 150.Fc 151.Ft unsigned char * 152.Fo EC_GROUP_get0_seed 153.Fa "const EC_GROUP *x" 154.Fc 155.Ft size_t 156.Fo EC_GROUP_get_seed_len 157.Fa "const EC_GROUP *" 158.Fc 159.Ft size_t 160.Fo EC_GROUP_set_seed 161.Fa "EC_GROUP *" 162.Fa "const unsigned char *" 163.Fa "size_t len" 164.Fc 165.Ft int 166.Fo EC_GROUP_get_degree 167.Fa "const EC_GROUP *group" 168.Fc 169.Ft int 170.Fo EC_GROUP_check 171.Fa "const EC_GROUP *group" 172.Fa "BN_CTX *ctx" 173.Fc 174.Ft int 175.Fo EC_GROUP_check_discriminant 176.Fa "const EC_GROUP *group" 177.Fa "BN_CTX *ctx" 178.Fc 179.Ft int 180.Fo EC_GROUP_cmp 181.Fa "const EC_GROUP *a" 182.Fa "const EC_GROUP *b" 183.Fa "BN_CTX *ctx" 184.Fc 185.Ft int 186.Fo EC_GROUP_get_basis_type 187.Fa "const EC_GROUP *" 188.Fc 189.Sh DESCRIPTION 190These functions operate on 191.Vt EC_GROUP 192objects created by the functions described in 193.Xr EC_GROUP_new 3 . 194.Pp 195.Fn EC_GROUP_copy 196copies the curve 197.Fa src 198into 199.Fa dst . 200Both 201.Fa src 202and 203.Fa dst 204must use the same 205.Vt EC_METHOD . 206.Pp 207.Fn EC_GROUP_dup 208creates a new 209.Vt EC_GROUP 210object and copies the content from 211.Fa src 212to the newly created 213.Vt EC_GROUP 214object. 215.Pp 216.Fn EC_GROUP_method_of 217obtains the 218.Vt EC_METHOD 219of 220.Fa group . 221.Pp 222.Fn EC_GROUP_set_generator 223sets curve parameters that must be agreed by all participants using 224the curve. 225These parameters include the 226.Fa generator , 227the 228.Fa order 229and the 230.Fa cofactor . 231The 232.Fa generator 233is a well defined point on the curve chosen for cryptographic 234operations. 235Integers used for point multiplications will be between 0 and 236.Fa order No - 1 . 237The 238.Fa order 239multiplied by the 240.Fa cofactor 241gives the number of points on the curve. 242.Pp 243.Fn EC_GROUP_get0_generator 244returns the generator for the identified 245.Fa group . 246.Pp 247.Fn EC_GROUP_get_order 248retrieves the order of the 249.Fa group 250and copies its value into 251.Fa order . 252It fails if the order of the 253.Fa group 254is not set or set to zero. 255.Pp 256.Fn EC_GROUP_get_cofactor 257retrieves the cofactor of the 258.Fa group 259and copies its value into 260.Fa cofactor . 261It fails if the cofactor of the 262.Fa group 263is not set or set to zero. 264.Pp 265The functions 266.Fn EC_GROUP_set_curve_name 267and 268.Fn EC_GROUP_get_curve_name 269set and get the NID for the curve, respectively (see 270.Xr EC_GROUP_new 3 ) . 271If a curve does not have a NID associated with it, then 272.Fn EC_GROUP_get_curve_name 273will return 274.Dv NID_undef . 275.Pp 276The asn1_flag value is used to determine whether the curve encoding 277uses explicit parameters or a named curve using an ASN.1 OID: 278many applications only support the latter form. 279If asn1_flag is the default value 280.Dv OPENSSL_EC_NAMED_CURVE , 281then the named curve form is used and the parameters must have a 282corresponding named curve NID set. 283If asn1_flags is 284.Dv OPENSSL_EC_EXPLICIT_CURVE , 285the parameters are explicitly encoded. 286The functions 287.Fn EC_GROUP_get_asn1_flag 288and 289.Fn EC_GROUP_set_asn1_flag 290get and set the status of the asn1_flag for the curve. 291.Pp 292The point_conversion_form for a curve controls how 293.Vt EC_POINT 294data is encoded as ASN.1 as defined in X9.62 (ECDSA). 295.Vt point_conversion_form_t 296is an enum defined as follows: 297.Bd -literal 298typedef enum { 299 /** the point is encoded as z||x, where the octet z specifies 300 * which solution of the quadratic equation y is */ 301 POINT_CONVERSION_COMPRESSED = 2, 302 /** the point is encoded as z||x||y, where z is the octet 0x04 */ 303 POINT_CONVERSION_UNCOMPRESSED = 4, 304 /** the point is encoded as z||x||y, where the octet z specifies 305 * which solution of the quadratic equation y is */ 306 POINT_CONVERSION_HYBRID = 6 307} point_conversion_form_t; 308.Ed 309.Pp 310For 311.Dv POINT_CONVERSION_UNCOMPRESSED 312the point is encoded as an octet signifying the UNCOMPRESSED form 313has been used followed by the octets for x, followed by the octets 314for y. 315.Pp 316For any given x coordinate for a point on a curve it is possible to 317derive two possible y values. 318For 319.Dv POINT_CONVERSION_COMPRESSED 320the point is encoded as an octet signifying that the COMPRESSED 321form has been used AND which of the two possible solutions for y 322has been used, followed by the octets for x. 323.Pp 324For 325.Dv POINT_CONVERSION_HYBRID 326the point is encoded as an octet signifying the HYBRID form has 327been used AND which of the two possible solutions for y has been 328used, followed by the octets for x, followed by the octets for y. 329.Pp 330The functions 331.Fn EC_GROUP_set_point_conversion_form 332and 333.Fn EC_GROUP_get_point_conversion_form 334set and get the point_conversion_form for the curve, respectively. 335.Pp 336ANSI X9.62 (ECDSA standard) defines a method of generating the curve 337parameter b from a random number. 338This provides advantages in that a parameter obtained in this way is 339highly unlikely to be susceptible to special purpose attacks, or have 340any trapdoors in it. 341If the seed is present for a curve then the b parameter was generated in 342a verifiable fashion using that seed. 343The OpenSSL EC library does not use this seed value but does enable you 344to inspect it using 345.Fn EC_GROUP_get0_seed . 346This returns a pointer to a memory block containing the seed that was 347used. 348The length of the memory block can be obtained using 349.Fn EC_GROUP_get_seed_len . 350A number of the builtin curves within the library provide seed values 351that can be obtained. 352It is also possible to set a custom seed using 353.Fn EC_GROUP_set_seed 354and passing a pointer to a memory block, along with the length of 355the seed. 356Again, the EC library will not use this seed value, although it will be 357preserved in any ASN.1 based communications. 358.Pp 359.Fn EC_GROUP_get_degree 360gets the degree of the field. 361For Fp fields this will be the number of bits in p. 362For F2^m fields this will be the value m. 363.Pp 364The function 365.Fn EC_GROUP_check_discriminant 366calculates the discriminant for the curve and verifies that it is 367valid. 368For a curve defined over Fp the discriminant is given by the formula 3694*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b. 370In either case for the curve to be valid the discriminant must be 371non-zero. 372.Pp 373The function 374.Fn EC_GROUP_check 375performs a number of checks on a curve to verify that it is valid. 376Checks performed include verifying that the discriminant is non-zero; 377that a generator has been defined; that the generator is on the curve 378and has the correct order. 379.Pp 380.Fn EC_GROUP_cmp 381compares 382.Fa a 383and 384.Fa b 385to determine whether they represent the same curve or not. 386.Pp 387.Fn EC_GROUP_get_basis_type 388always returns 0 and is only provided for compatibility. 389.Sh RETURN VALUES 390The following functions return 1 on success or 0 on error: 391.Fn EC_GROUP_copy , 392.Fn EC_GROUP_set_generator , 393.Fn EC_GROUP_check , 394and 395.Fn EC_GROUP_check_discriminant . 396.Pp 397.Fn EC_GROUP_dup 398returns a pointer to the duplicated curve or 399.Dv NULL 400on error. 401.Pp 402.Fn EC_GROUP_method_of 403returns the 404.Vt EC_METHOD 405implementation in use for the given curve or 406.Dv NULL 407on error. 408.Pp 409.Fn EC_GROUP_get0_generator 410returns the generator for the given curve or 411.Dv NULL 412on error. 413.Pp 414.Fn EC_GROUP_get_order 415returns 0 if the order is not set or set to zero for the 416.Fa group 417or if copying into 418.Fa order 419fails, or 1 otherwise. 420.Pp 421.Fn EC_GROUP_order_bits 422returns the number of bits in the group order. 423.Pp 424.Fn EC_GROUP_get_cofactor 425returns 0 if the cofactor is not set or set to zero for the 426.Fa group 427or if copying into 428.Fa cofactor 429fails, or 1 otherwise. 430.Pp 431.Fn EC_GROUP_get_curve_name 432returns the curve name (NID) for the 433.Fa group 434or 435.Dv NID_undef 436if no curve name is associated. 437.Pp 438.Fn EC_GROUP_get_asn1_flag 439returns the ASN.1 flag for the specified 440.Fa group . 441.Pp 442.Fn EC_GROUP_get_point_conversion_form 443returns the point_conversion_form for the 444.Fa group . 445.Pp 446.Fn EC_GROUP_get_degree 447returns the degree for the 448.Fa group 449or 0 if the operation is not supported 450by the underlying group implementation. 451.Pp 452.Fn EC_GROUP_get0_seed 453returns a pointer to the seed that was used to generate the parameter 454b, or 455.Dv NULL 456if the seed is not specified. 457.Fn EC_GROUP_get_seed_len 458returns the length of the seed or 0 if the seed is not specified. 459.Pp 460.Fn EC_GROUP_set_seed 461returns the length of the seed that has been set. 462If the supplied seed is 463.Dv NULL 464or the supplied seed length is 0, the return value will be 1. 465On error 0 is returned. 466.Pp 467.Fn EC_GROUP_cmp 468returns 0 if the curves are equal, 1 if they are not equal, 469or -1 on error. 470.Pp 471.Fn EC_GROUP_get_basis_type 472always returns 0. 473.Sh SEE ALSO 474.Xr d2i_ECPKParameters 3 , 475.Xr EC_GFp_simple_method 3 , 476.Xr EC_GROUP_new 3 , 477.Xr EC_KEY_new 3 , 478.Xr EC_POINT_add 3 , 479.Xr EC_POINT_new 3 480.Sh HISTORY 481.Fn EC_GROUP_copy , 482.Fn EC_GROUP_method_of , 483.Fn EC_GROUP_set_generator , 484.Fn EC_GROUP_get0_generator , 485.Fn EC_GROUP_get_order , 486and 487.Fn EC_GROUP_get_cofactor 488first appeared in OpenSSL 0.9.7 and have been available since 489.Ox 3.2 . 490.Pp 491.Fn EC_GROUP_dup , 492.Fn EC_GROUP_set_curve_name , 493.Fn EC_GROUP_get_curve_name , 494.Fn EC_GROUP_set_asn1_flag , 495.Fn EC_GROUP_get_asn1_flag , 496.Fn EC_GROUP_set_point_conversion_form , 497.Fn EC_GROUP_get_point_conversion_form , 498.Fn EC_GROUP_get0_seed , 499.Fn EC_GROUP_get_seed_len , 500.Fn EC_GROUP_set_seed , 501.Fn EC_GROUP_get_degree , 502.Fn EC_GROUP_check , 503.Fn EC_GROUP_check_discriminant , 504.Fn EC_GROUP_cmp , 505and 506.Fn EC_GROUP_get_basis_type 507first appeared in OpenSSL 0.9.8 and have been available since 508.Ox 4.5 . 509.Pp 510.Fn EC_GROUP_order_bits 511first appeared in OpenSSL 1.1.0 and has been available since 512.Ox 7.0 . 513