1.\" $OpenBSD: EC_GROUP_new.3,v 1.15 2023/04/27 09:35:20 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: April 27 2023 $ 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_by_curve_name , 60.Nm EC_GROUP_set_curve , 61.Nm EC_GROUP_get_curve , 62.Nm EC_GROUP_set_curve_GFp , 63.Nm EC_GROUP_get_curve_GFp , 64.Nm EC_get_builtin_curves 65.Nd create and destroy EC_GROUP objects 66.Sh SYNOPSIS 67.In openssl/ec.h 68.In openssl/bn.h 69.Ft EC_GROUP * 70.Fo EC_GROUP_new 71.Fa "const EC_METHOD *meth" 72.Fc 73.Ft void 74.Fo EC_GROUP_free 75.Fa "EC_GROUP *group" 76.Fc 77.Ft void 78.Fo EC_GROUP_clear_free 79.Fa "EC_GROUP *group" 80.Fc 81.Ft EC_GROUP * 82.Fo EC_GROUP_new_curve_GFp 83.Fa "const BIGNUM *p" 84.Fa "const BIGNUM *a" 85.Fa "const BIGNUM *b" 86.Fa "BN_CTX *ctx" 87.Fc 88.Ft EC_GROUP * 89.Fo EC_GROUP_new_by_curve_name 90.Fa "int nid" 91.Fc 92.Ft int 93.Fo EC_GROUP_set_curve 94.Fa "EC_GROUP *group" 95.Fa "const BIGNUM *p" 96.Fa "const BIGNUM *a" 97.Fa "const BIGNUM *b" 98.Fa "BN_CTX *ctx" 99.Fc 100.Ft int 101.Fo EC_GROUP_get_curve 102.Fa "const EC_GROUP *group" 103.Fa "BIGNUM *p" 104.Fa "BIGNUM *a" 105.Fa "BIGNUM *b" 106.Fa "BN_CTX *ctx" 107.Fc 108.Ft int 109.Fo EC_GROUP_set_curve_GFp 110.Fa "EC_GROUP *group" 111.Fa "const BIGNUM *p" 112.Fa "const BIGNUM *a" 113.Fa "const BIGNUM *b" 114.Fa "BN_CTX *ctx" 115.Fc 116.Ft int 117.Fo EC_GROUP_get_curve_GFp 118.Fa "const EC_GROUP *group" 119.Fa "BIGNUM *p" 120.Fa "BIGNUM *a" 121.Fa "BIGNUM *b" 122.Fa "BN_CTX *ctx" 123.Fc 124.Ft size_t 125.Fo EC_get_builtin_curves 126.Fa "EC_builtin_curve *r" 127.Fa "size_t nitems" 128.Fc 129.Sh DESCRIPTION 130The EC library provides functions for performing operations on 131elliptic curves over finite fields. 132In general, an elliptic curve satisfies an equation of the form: 133.Pp 134.Dl y^2 = x^3 + ax + b 135.Pp 136An 137.Vt EC_GROUP 138structure is used to represent the definition of an elliptic curve. 139A new curve can be constructed by calling 140.Fn EC_GROUP_new , 141using the implementation provided by 142.Fa meth 143(see 144.Xr EC_GFp_simple_method 3 ) . 145It is then necessary to call 146.Fn EC_GROUP_set_curve 147to set the curve parameters. 148.Pp 149.Fn EC_GROUP_set_curve 150sets the curve parameters 151.Fa p , 152.Fa a , 153and 154.Fa b , 155where 156.Fa a 157and 158.Fa b 159represent the coefficients of the curve equation. 160.Pp 161.Fn EC_GROUP_set_curve_GFp 162is a deprecated synonym for 163.Fn EC_GROUP_set_curve . 164.Pp 165.Fn EC_GROUP_get_curve 166obtains the previously set curve parameters. 167.Pp 168.Fn EC_GROUP_get_curve_GFp 169is a deprecated synonym for 170.Fn EC_GROUP_get_curve . 171.Pp 172The function 173.Fn EC_GROUP_new_curve_GFp 174is a shortcut for calling 175.Fn EC_GROUP_new 176and 177.Fn EC_GROUP_set_curve . 178An appropriate default implementation method will be used. 179.Pp 180Whilst the library can be used to create any curve using the functions 181described above, there are also a number of predefined curves that are 182available. 183In order to obtain a list of all of the predefined curves, call the 184function 185.Fn EC_get_builtin_curves . 186The parameter 187.Fa r 188should be an array of 189.Vt EC_builtin_cure 190structures of size 191.Fa nitems . 192The function will populate the 193.Fa r 194array with information about the builtin curves. 195If 196.Fa nitems 197is less than the total number of curves available, then the first 198.Fa nitems 199curves will be returned. 200Otherwise the total number of curves will be provided. 201The return value is the total number of curves available (whether that 202number has been populated in 203.Fa r 204or not). 205Passing a 206.Dv NULL 207.Fa r , 208or setting 209.Fa nitems 210to 0, will do nothing other than return the total number of curves 211available. 212The 213.Vt EC_builtin_curve 214structure is defined as follows: 215.Bd -literal 216typedef struct { 217 int nid; 218 const char *comment; 219} EC_builtin_curve; 220.Ed 221.Pp 222Each 223.Vt EC_builtin_curve 224item has a unique integer ID 225.Pq Fa nid 226and a human readable comment string describing the curve. 227.Pp 228In order to construct a builtin curve, use the function 229.Fn EC_GROUP_new_by_curve_name 230and provide the 231.Fa nid 232of the curve to be constructed. 233.Pp 234.Fn EC_GROUP_free 235frees the memory associated with the 236.Vt EC_GROUP . 237If 238.Fa group 239is a 240.Dv NULL 241pointer, no action occurs. 242.Pp 243.Fn EC_GROUP_clear_free 244destroys any sensitive data held within the 245.Vt EC_GROUP 246and then frees its memory. 247If 248.Fa group 249is a 250.Dv NULL 251pointer, no action occurs. 252.Sh RETURN VALUES 253All 254.Fn EC_GROUP_new* 255functions return a pointer to the newly constructed group or 256.Dv NULL 257on error. 258.Pp 259.Fn EC_get_builtin_curves 260returns the number of builtin curves that are available. 261.Pp 262.Fn EC_GROUP_set_curve , 263.Fn EC_GROUP_get_curve , 264.Fn EC_GROUP_set_curve_GFp , 265and 266.Fn EC_GROUP_get_curve_GFp 267return 1 on success or 0 on error. 268.Sh SEE ALSO 269.Xr crypto 3 , 270.Xr d2i_ECPKParameters 3 , 271.Xr EC_GFp_simple_method 3 , 272.Xr EC_GROUP_copy 3 , 273.Xr EC_KEY_new 3 , 274.Xr EC_POINT_add 3 , 275.Xr EC_POINT_new 3 , 276.Xr ECDH_compute_key 3 , 277.Xr ECDSA_SIG_new 3 278.Sh HISTORY 279.Fn EC_GROUP_new , 280.Fn EC_GROUP_free , 281.Fn EC_GROUP_clear_free , 282.Fn EC_GROUP_new_curve_GFp , 283.Fn EC_GROUP_set_curve_GFp , 284and 285.Fn EC_GROUP_get_curve_GFp 286first appeared in OpenSSL 0.9.7 and have been available since 287.Ox 3.2 . 288.Pp 289.Fn EC_GROUP_new_by_curve_name , 290and 291.Fn EC_get_builtin_curves 292first appeared in OpenSSL 0.9.8 and have been available since 293.Ox 4.5 . 294.Fn EC_GROUP_set_curve 295and 296.Fn EC_GROUP_get_curve 297first appeared in OpenSSL 1.1.1 and have been available since 298.Ox 7.0 . 299