1.\" $OpenBSD: EC_GROUP_new.3,v 1.13 2021/05/11 04:22:32 tb Exp $ 2.\" OpenSSL 6328d367 Sat Jul 4 21:58:30 2020 +0200 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2013 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: May 11 2021 $ 52.Dt EC_GROUP_NEW 3 53.Os 54.Sh NAME 55.Nm EC_GROUP_new , 56.Nm EC_GROUP_free , 57.Nm EC_GROUP_clear_free , 58.Nm EC_GROUP_new_curve_GFp , 59.Nm EC_GROUP_new_curve_GF2m , 60.Nm EC_GROUP_new_by_curve_name , 61.Nm EC_GROUP_set_curve , 62.Nm EC_GROUP_get_curve , 63.Nm EC_GROUP_set_curve_GFp , 64.Nm EC_GROUP_get_curve_GFp , 65.Nm EC_GROUP_set_curve_GF2m , 66.Nm EC_GROUP_get_curve_GF2m , 67.Nm EC_get_builtin_curves 68.Nd create and destroy EC_GROUP objects 69.Sh SYNOPSIS 70.In openssl/ec.h 71.In openssl/bn.h 72.Ft EC_GROUP * 73.Fo EC_GROUP_new 74.Fa "const EC_METHOD *meth" 75.Fc 76.Ft void 77.Fo EC_GROUP_free 78.Fa "EC_GROUP *group" 79.Fc 80.Ft void 81.Fo EC_GROUP_clear_free 82.Fa "EC_GROUP *group" 83.Fc 84.Ft EC_GROUP * 85.Fo EC_GROUP_new_curve_GFp 86.Fa "const BIGNUM *p" 87.Fa "const BIGNUM *a" 88.Fa "const BIGNUM *b" 89.Fa "BN_CTX *ctx" 90.Fc 91.Ft EC_GROUP * 92.Fo EC_GROUP_new_curve_GF2m 93.Fa "const BIGNUM *p" 94.Fa "const BIGNUM *a" 95.Fa "const BIGNUM *b" 96.Fa "BN_CTX *ctx" 97.Fc 98.Ft EC_GROUP * 99.Fo EC_GROUP_new_by_curve_name 100.Fa "int nid" 101.Fc 102.Ft int 103.Fo EC_GROUP_set_curve 104.Fa "EC_GROUP *group" 105.Fa "const BIGNUM *p" 106.Fa "const BIGNUM *a" 107.Fa "const BIGNUM *b" 108.Fa "BN_CTX *ctx" 109.Fc 110.Ft int 111.Fo EC_GROUP_get_curve 112.Fa "const EC_GROUP *group" 113.Fa "BIGNUM *p" 114.Fa "BIGNUM *a" 115.Fa "BIGNUM *b" 116.Fa "BN_CTX *ctx" 117.Fc 118.Ft int 119.Fo EC_GROUP_set_curve_GFp 120.Fa "EC_GROUP *group" 121.Fa "const BIGNUM *p" 122.Fa "const BIGNUM *a" 123.Fa "const BIGNUM *b" 124.Fa "BN_CTX *ctx" 125.Fc 126.Ft int 127.Fo EC_GROUP_get_curve_GFp 128.Fa "const EC_GROUP *group" 129.Fa "BIGNUM *p" 130.Fa "BIGNUM *a" 131.Fa "BIGNUM *b" 132.Fa "BN_CTX *ctx" 133.Fc 134.Ft int 135.Fo EC_GROUP_set_curve_GF2m 136.Fa "EC_GROUP *group" 137.Fa "const BIGNUM *p" 138.Fa "const BIGNUM *a" 139.Fa "const BIGNUM *b" 140.Fa "BN_CTX *ctx" 141.Fc 142.Ft int 143.Fo EC_GROUP_get_curve_GF2m 144.Fa "const EC_GROUP *group" 145.Fa "BIGNUM *p" 146.Fa "BIGNUM *a" 147.Fa "BIGNUM *b" 148.Fa "BN_CTX *ctx" 149.Fc 150.Ft size_t 151.Fo EC_get_builtin_curves 152.Fa "EC_builtin_curve *r" 153.Fa "size_t nitems" 154.Fc 155.Sh DESCRIPTION 156The EC library provides functions for performing operations on 157elliptic curves over finite fields. 158In general, an elliptic curve satisfies an equation of the form: 159.Pp 160.Dl y^2 = x^3 + ax + b 161.Pp 162Within the library there are two forms of elliptic curves that are of 163interest. 164The first form is those defined over the prime field Fp. 165The elements of Fp are the integers 0 to p-1, where 166.Fa p 167is a prime number. 168This gives us a revised elliptic curve equation as follows: 169.Pp 170.Dl y^2 mod p = x^3 + ax + b mod p 171.Pp 172The second form is those defined over a binary field F2^m where the 173elements of the field are integers of length at most m bits. 174For this form the elliptic curve equation is modified to: 175.Pp 176.Dl y^2 + xy = x^3 + ax^2 + b (where b != 0) 177.Pp 178Operations in a binary field are performed relative to an irreducible 179polynomial. 180All such curves with OpenSSL use a trinomial or a pentanomial for this 181parameter. 182.Pp 183An 184.Vt EC_GROUP 185structure is used to represent the definition of an elliptic curve. 186A new curve can be constructed by calling 187.Fn EC_GROUP_new , 188using the implementation provided by 189.Fa meth 190(see 191.Xr EC_GFp_simple_method 3 ) . 192It is then necessary to call 193.Fn EC_GROUP_set_curve 194to set the curve parameters. 195.Pp 196.Fn EC_GROUP_set_curve 197sets the curve parameters 198.Fa p , 199.Fa a , 200and 201.Fa b . 202For a curve over Fp, 203.Fa p 204is the prime for the field. 205For a curve over F2^m 206.Fa p 207represents the irreducible polynomial - each bit represents a term in 208the polynomial. 209Therefore, there will either be three or five bits set dependent on 210whether the polynomial is a trinomial or a pentanomial. 211In either case, 212.Fa a 213and 214.Fa b 215represent the coefficients of the curve equation. 216.Pp 217.Fn EC_GROUP_set_curve_GFp 218and 219.Fn EC_GROUP_set_curve_GF2m 220are deprecated synonyms for 221.Fn EC_GROUP_set_curve . 222.Pp 223.Fn EC_GROUP_get_curve 224obtains the previously set curve parameters. 225.Pp 226.Fn EC_GROUP_get_curve_GFp 227and 228.Fn EC_GROUP_get_curve_GF2m 229are deprecated synonyms for 230.Fn EC_GROUP_get_curve . 231.Pp 232The functions 233.Fn EC_GROUP_new_curve_GFp 234and 235.Fn EC_GROUP_new_curve_GF2m 236are shortcuts for calling 237.Fn EC_GROUP_new 238and the appropriate 239.Fn EC_GROUP_set_curve_* 240function. 241An appropriate default implementation method will be used. 242.Pp 243Whilst the library can be used to create any curve using the functions 244described above, there are also a number of predefined curves that are 245available. 246In order to obtain a list of all of the predefined curves, call the 247function 248.Fn EC_get_builtin_curves . 249The parameter 250.Fa r 251should be an array of 252.Vt EC_builtin_cure 253structures of size 254.Fa nitems . 255The function will populate the 256.Fa r 257array with information about the builtin curves. 258If 259.Fa nitems 260is less than the total number of curves available, then the first 261.Fa nitems 262curves will be returned. 263Otherwise the total number of curves will be provided. 264The return value is the total number of curves available (whether that 265number has been populated in 266.Fa r 267or not). 268Passing a 269.Dv NULL 270.Fa r , 271or setting 272.Fa nitems 273to 0, will do nothing other than return the total number of curves 274available. 275The 276.Vt EC_builtin_curve 277structure is defined as follows: 278.Bd -literal 279typedef struct { 280 int nid; 281 const char *comment; 282} EC_builtin_curve; 283.Ed 284.Pp 285Each 286.Vt EC_builtin_curve 287item has a unique integer ID 288.Pq Fa nid 289and a human readable comment string describing the curve. 290.Pp 291In order to construct a builtin curve use the function 292.Fn EC_GROUP_new_by_curve_name 293and provide the 294.Fa nid 295of the curve to be constructed. 296.Pp 297.Fn EC_GROUP_free 298frees the memory associated with the 299.Vt EC_GROUP . 300If 301.Fa group 302is a 303.Dv NULL 304pointer, no action occurs. 305.Pp 306.Fn EC_GROUP_clear_free 307destroys any sensitive data held within the 308.Vt EC_GROUP 309and then frees its memory. 310If 311.Fa group 312is a 313.Dv NULL 314pointer, no action occurs. 315.Sh RETURN VALUES 316All 317.Fn EC_GROUP_new* 318functions return a pointer to the newly constructed group or 319.Dv NULL 320on error. 321.Pp 322.Fn EC_get_builtin_curves 323returns the number of builtin curves that are available. 324.Pp 325.Fn EC_GROUP_set_curve , 326.Fn EC_GROUP_get_curve , 327.Fn EC_GROUP_set_curve_GFp , 328.Fn EC_GROUP_get_curve_GFp , 329.Fn EC_GROUP_set_curve_GF2m , 330and 331.Fn EC_GROUP_get_curve_GF2m 332return 1 on success or 0 on error. 333.Sh SEE ALSO 334.Xr crypto 3 , 335.Xr d2i_ECPKParameters 3 , 336.Xr EC_GFp_simple_method 3 , 337.Xr EC_GROUP_copy 3 , 338.Xr EC_KEY_new 3 , 339.Xr EC_POINT_add 3 , 340.Xr EC_POINT_new 3 , 341.Xr ECDH_compute_key 3 , 342.Xr ECDSA_SIG_new 3 343.Sh HISTORY 344.Fn EC_GROUP_new , 345.Fn EC_GROUP_free , 346.Fn EC_GROUP_clear_free , 347.Fn EC_GROUP_new_curve_GFp , 348.Fn EC_GROUP_set_curve_GFp , 349and 350.Fn EC_GROUP_get_curve_GFp 351first appeared in OpenSSL 0.9.7 and have been available since 352.Ox 3.2 . 353.Pp 354.Fn EC_GROUP_new_curve_GF2m , 355.Fn EC_GROUP_new_by_curve_name , 356.Fn EC_GROUP_set_curve_GF2m , 357.Fn EC_GROUP_get_curve_GF2m , 358and 359.Fn EC_get_builtin_curves 360first appeared in OpenSSL 0.9.8 and have been available since 361.Ox 4.5 . 362.Fn EC_GROUP_set_curve 363and 364.Fn EC_GROUP_get_curve 365first appeared in OpenSSL 1.1.1 and have been available since 366.Ox 7.0 . 367