1EC_GROUP_NEW(3ossl)                 OpenSSL                EC_GROUP_NEW(3ossl)
2
3
4

NAME

6       EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters,
7       EC_GROUP_new_from_params, EC_GROUP_new_from_ecparameters,
8       EC_GROUP_new_from_ecpkparameters, EC_GROUP_new, EC_GROUP_free,
9       EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m,
10       EC_GROUP_new_by_curve_name_ex, EC_GROUP_new_by_curve_name,
11       EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_curve_GFp,
12       EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m,
13       EC_GROUP_get_curve_GF2m, EC_get_builtin_curves, OSSL_EC_curve_nid2name
14       - Functions for creating and destroying EC_GROUP objects
15

SYNOPSIS

17        #include <openssl/ec.h>
18
19        EC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[],
20                                           OSSL_LIB_CTX *libctx, const char *propq);
21        EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params);
22        EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params);
23        void EC_GROUP_free(EC_GROUP *group);
24
25        EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
26                                         const BIGNUM *b, BN_CTX *ctx);
27        EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
28                                          const BIGNUM *b, BN_CTX *ctx);
29        EC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq,
30                                                int nid);
31        EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
32
33        int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
34                               const BIGNUM *b, BN_CTX *ctx);
35        int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,
36                               BN_CTX *ctx);
37
38        ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group,
39                                                ECPARAMETERS *params);
40        ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group,
41                                                    ECPKPARAMETERS *params);
42
43        size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
44        const char *OSSL_EC_curve_nid2name(int nid);
45
46       The following functions have been deprecated since OpenSSL 3.0, and can
47       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
48       version value, see openssl_user_macros(7):
49
50        EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
51        void EC_GROUP_clear_free(EC_GROUP *group);
52
53        int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,
54                                   const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
55        int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,
56                                   BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
57        int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,
58                                    const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
59        int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,
60                                    BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
61

DESCRIPTION

63       Within the library there are two forms of elliptic curve that are of
64       interest.  The first form is those defined over the prime field Fp. The
65       elements of Fp are the integers 0 to p-1, where p is a prime number.
66       This gives us a revised elliptic curve equation as follows:
67
68       y^2 mod p = x^3 +ax + b mod p
69
70       The second form is those defined over a binary field F2^m where the
71       elements of the field are integers of length at most m bits. For this
72       form the elliptic curve equation is modified to:
73
74       y^2 + xy = x^3 + ax^2 + b (where b != 0)
75
76       Operations in a binary field are performed relative to an irreducible
77       polynomial. All such curves with OpenSSL use a trinomial or a
78       pentanomial for this parameter.
79
80       Although deprecated since OpenSSL 3.0 and should no longer be used, a
81       new curve can be constructed by calling EC_GROUP_new(), using the
82       implementation provided by meth (see EC_GFp_simple_method(3)) and
83       associated with the library context ctx (see OSSL_LIB_CTX(3)).  The ctx
84       parameter may be NULL in which case the default library context is
85       used.  It is then necessary to call EC_GROUP_set_curve() to set the
86       curve parameters.  Applications should instead use one of the other
87       EC_GROUP_new_* constructors.
88
89       EC_GROUP_new_from_params() creates a group with parameters specified by
90       params.  The library context libctx (see OSSL_LIB_CTX(3)) and property
91       query string propq are used to fetch algorithms from providers.  params
92       may be either a list of explicit params or a named group, The values
93       for ctx and propq may be NULL.  The params that can be used are
94       described in EVP_PKEY-EC(7).
95
96       EC_GROUP_new_from_ecparameters() will create a group from the specified
97       params and EC_GROUP_new_from_ecpkparameters() will create a group from
98       the specific PK params.
99
100       EC_GROUP_set_curve() sets the curve parameters p, a and b. For a curve
101       over Fp p is the prime for the field. For a curve over F2^m p
102       represents the irreducible polynomial - each bit represents a term in
103       the polynomial.  Therefore, there will either be three or five bits set
104       dependent on whether the polynomial is a trinomial or a pentanomial.
105       In either case, a and b represents the coefficients a and b from the
106       relevant equation introduced above.
107
108       EC_group_get_curve() obtains the previously set curve parameters.
109
110       EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for
111       EC_GROUP_set_curve(). They are defined for backwards compatibility only
112       and should not be used.
113
114       EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for
115       EC_GROUP_get_curve(). They are defined for backwards compatibility only
116       and should not be used.
117
118       The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m()
119       are shortcuts for calling EC_GROUP_new() and then the
120       EC_GROUP_set_curve() function.  An appropriate default implementation
121       method will be used.
122
123       Whilst the library can be used to create any curve using the functions
124       described above, there are also a number of predefined curves that are
125       available. In order to obtain a list of all of the predefined curves,
126       call the function EC_get_builtin_curves(). The parameter r should be an
127       array of EC_builtin_curve structures of size nitems. The function will
128       populate the r array with information about the built-in curves. If
129       nitems is less than the total number of curves available, then the
130       first nitems curves will be returned. Otherwise the total number of
131       curves will be provided. The return value is the total number of curves
132       available (whether that number has been populated in r or not). Passing
133       a NULL r, or setting nitems to 0 will do nothing other than return the
134       total number of curves available.  The EC_builtin_curve structure is
135       defined as follows:
136
137        typedef struct {
138               int nid;
139               const char *comment;
140               } EC_builtin_curve;
141
142       Each EC_builtin_curve item has a unique integer id (nid), and a human
143       readable comment string describing the curve.
144
145       In order to construct a built-in curve use the function
146       EC_GROUP_new_by_curve_name_ex() and provide the nid of the curve to be
147       constructed, the associated library context to be used in ctx (see
148       OSSL_LIB_CTX(3)) and any property query string in propq. The ctx value
149       may be NULL in which case the default library context is used. The
150       propq value may also be NULL.
151
152       EC_GROUP_new_by_curve_name() is the same as
153       EC_GROUP_new_by_curve_name_ex() except that the default library context
154       is always used along with a NULL property query string.
155
156       EC_GROUP_free() frees the memory associated with the EC_GROUP.  If
157       group is NULL nothing is done.
158
159       EC_GROUP_clear_free() is deprecated: it was meant to destroy any
160       sensitive data held within the EC_GROUP and then free its memory, but
161       since all the data stored in the EC_GROUP is public anyway, this
162       function is unnecessary.  Its use can be safely replaced with
163       EC_GROUP_free().  If group is NULL nothing is done.
164
165       OSSL_EC_curve_nid2name() converts a curve nid into the corresponding
166       name.
167

RETURN VALUES

169       All EC_GROUP_new* functions return a pointer to the newly constructed
170       group, or NULL on error.
171
172       EC_get_builtin_curves() returns the number of built-in curves that are
173       available.
174
175       EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(),
176       EC_GROUP_set_curve_GF2m(), EC_GROUP_get_curve_GF2m() return 1 on
177       success or 0 on error.
178
179       OSSL_EC_curve_nid2name() returns a character string constant, or NULL
180       on error.
181

SEE ALSO

183       crypto(7), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3),
184       EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3),
185       OSSL_LIB_CTX(3), EVP_PKEY-EC(7)
186

HISTORY

188EC_GROUP_new() was deprecated in OpenSSL 3.0.
189
190         EC_GROUP_new_by_curve_name_ex() and EC_GROUP_new_from_params() were
191         added in OpenSSL 3.0.
192
193EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use
194         EC_GROUP_free() instead.
195
196
197
198
199          EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(),
200          EC_GROUP_set_curve_GF2m() and EC_GROUP_get_curve_GF2m() were deprecated in
201          OpenSSL 3.0; use EC_GROUP_set_curve() and EC_GROUP_get_curve() instead.
202
204       Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved.
205
206       Licensed under the Apache License 2.0 (the "License").  You may not use
207       this file except in compliance with the License.  You can obtain a copy
208       in the file LICENSE in the source distribution or at
209       <https://www.openssl.org/source/license.html>.
210
211
212
2133.1.1                             2023-08-31               EC_GROUP_NEW(3ossl)
Impressum