1EC_GROUP_NEW(3ossl) OpenSSL EC_GROUP_NEW(3ossl)
2
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
17 #include <openssl/ec.h>
18 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 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 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 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 size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
44 const char *OSSL_EC_curve_nid2name(int nid);
45 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 EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
51 void EC_GROUP_clear_free(EC_GROUP *group);
52 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
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 y^2 mod p = x^3 +ax + b mod p
69 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 y^2 + xy = x^3 + ax^2 + b (where b != 0)
75 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 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 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 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 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 EC_group_get_curve() obtains the previously set curve parameters.
109 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 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 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 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 typedef struct {
138 int nid;
139 const char *comment;
140 } EC_builtin_curve;
141 Each EC_builtin_curve item has a unique integer id (nid), and a human
143 readable comment string describing the curve.
144 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 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 EC_GROUP_free() frees the memory associated with the EC_GROUP. If
157 group is NULL nothing is done.
158 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 OSSL_EC_curve_nid2name() converts a curve nid into the corresponding
166 name.
167
169 All EC_GROUP_new* functions return a pointer to the newly constructed
170 group, or NULL on error.
171 EC_get_builtin_curves() returns the number of built-in curves that are
173 available.
174 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 OSSL_EC_curve_nid2name() returns a character string constant, or NULL
180 on error.
181
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
188 • EC_GROUP_new() was deprecated in OpenSSL 3.0.
189 EC_GROUP_new_by_curve_name_ex() and EC_GROUP_new_from_params() were
191 added in OpenSSL 3.0.
192 • EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use
194 EC_GROUP_free() instead.
195 •
197 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 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>.
2103.1.1 2023-08-31 EC_GROUP_NEW(3ossl)