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