]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
de34e45a MC |
5 | EC_GROUP_get_ecparameters, |
6 | EC_GROUP_get_ecpkparameters, | |
c0f39ded | 7 | EC_GROUP_new_from_params, |
a8aad913 | 8 | EC_GROUP_to_params, |
de34e45a | 9 | EC_GROUP_new_from_ecparameters, |
60b350a3 | 10 | EC_GROUP_new_from_ecpkparameters, |
c0f39ded | 11 | EC_GROUP_new, |
de34e45a MC |
12 | EC_GROUP_free, |
13 | EC_GROUP_clear_free, | |
14 | EC_GROUP_new_curve_GFp, | |
15 | EC_GROUP_new_curve_GF2m, | |
d8652be0 | 16 | EC_GROUP_new_by_curve_name_ex, |
de34e45a MC |
17 | EC_GROUP_new_by_curve_name, |
18 | EC_GROUP_set_curve, | |
19 | EC_GROUP_get_curve, | |
20 | EC_GROUP_set_curve_GFp, | |
21 | EC_GROUP_get_curve_GFp, | |
22 | EC_GROUP_set_curve_GF2m, | |
23 | EC_GROUP_get_curve_GF2m, | |
f9253152 DDO |
24 | EC_get_builtin_curves, |
25 | OSSL_EC_curve_nid2name - | |
26 | Functions for creating and destroying EC_GROUP objects | |
aafbe1cc MC |
27 | |
28 | =head1 SYNOPSIS | |
29 | ||
30 | #include <openssl/ec.h> | |
aafbe1cc | 31 | |
c0f39ded | 32 | EC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[], |
b4250010 | 33 | OSSL_LIB_CTX *libctx, const char *propq); |
a8aad913 OM |
34 | OSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx, |
35 | const char *propq, BN_CTX *bnctx); | |
f64f17c3 SL |
36 | EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params); |
37 | EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params); | |
aafbe1cc | 38 | void EC_GROUP_free(EC_GROUP *group); |
aafbe1cc | 39 | |
e9b77246 BB |
40 | EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, |
41 | const BIGNUM *b, BN_CTX *ctx); | |
42 | EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, | |
43 | const BIGNUM *b, BN_CTX *ctx); | |
b4250010 | 44 | EC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq, |
d8652be0 | 45 | int nid); |
aafbe1cc MC |
46 | EC_GROUP *EC_GROUP_new_by_curve_name(int nid); |
47 | ||
de34e45a MC |
48 | int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, |
49 | const BIGNUM *b, BN_CTX *ctx); | |
50 | int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, | |
51 | BN_CTX *ctx); | |
aafbe1cc | 52 | |
f64f17c3 SL |
53 | ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, |
54 | ECPARAMETERS *params); | |
55 | ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, | |
56 | ECPKPARAMETERS *params); | |
60b350a3 | 57 | |
aafbe1cc | 58 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); |
f9253152 | 59 | const char *OSSL_EC_curve_nid2name(int nid); |
aafbe1cc | 60 | |
3dbf8243 MC |
61 | The following functions have been deprecated since OpenSSL 3.0, and can be |
62 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
63 | see L<openssl_user_macros(7)>: | |
4a7a4972 | 64 | |
23ccae80 | 65 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); |
4a7a4972 NT |
66 | void EC_GROUP_clear_free(EC_GROUP *group); |
67 | ||
e52b4215 SL |
68 | int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, |
69 | const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
70 | int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, | |
71 | BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | |
72 | int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, | |
73 | const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
74 | int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, | |
75 | BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | |
76 | ||
aafbe1cc MC |
77 | =head1 DESCRIPTION |
78 | ||
4fc55c1d NT |
79 | Within the library there are two forms of elliptic curve that are of interest. |
80 | The first form is those defined over the prime field Fp. The elements of Fp are | |
81 | the integers 0 to p-1, where p is a prime number. This gives us a revised | |
aafbe1cc MC |
82 | elliptic curve equation as follows: |
83 | ||
84 | y^2 mod p = x^3 +ax + b mod p | |
85 | ||
4fc55c1d NT |
86 | The second form is those defined over a binary field F2^m where the elements of |
87 | the field are integers of length at most m bits. For this form the elliptic | |
88 | curve equation is modified to: | |
aafbe1cc MC |
89 | |
90 | y^2 + xy = x^3 + ax^2 + b (where b != 0) | |
91 | ||
4fc55c1d NT |
92 | Operations in a binary field are performed relative to an |
93 | B<irreducible polynomial>. All such curves with OpenSSL use a trinomial or a | |
94 | pentanomial for this parameter. | |
aafbe1cc | 95 | |
23ccae80 BB |
96 | Although deprecated since OpenSSL 3.0 and should no longer be used, |
97 | a new curve can be constructed by calling EC_GROUP_new(), using the | |
2da8d4eb | 98 | implementation provided by I<meth> (see L<EC_GFp_simple_method(3)>) and |
b4250010 | 99 | associated with the library context I<ctx> (see L<OSSL_LIB_CTX(3)>). |
2da8d4eb | 100 | The I<ctx> parameter may be NULL in which case the default library context is |
4fc55c1d | 101 | used. |
f585cefc | 102 | It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. |
23ccae80 BB |
103 | Applications should instead use one of the other EC_GROUP_new_* constructors. |
104 | ||
c0f39ded | 105 | EC_GROUP_new_from_params() creates a group with parameters specified by I<params>. |
b4250010 | 106 | The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) and property query string |
c0f39ded SL |
107 | I<propq> are used to fetch algorithms from providers. |
108 | I<params> may be either a list of explicit params or a named group, | |
109 | The values for I<ctx> and I<propq> may be NULL. | |
110 | The I<params> that can be used are described in | |
111 | L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>. | |
112 | ||
a8aad913 OM |
113 | EC_GROUP_to_params creates an OSSL_PARAM array with the corresponding parameters |
114 | describing the given EC_GROUP. The resulting parameters may contain parameters | |
115 | describing a named or explicit curve depending on the EC_GROUP. | |
116 | The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) and property query string | |
117 | I<propq> are used to fetch algorithms from providers. | |
118 | I<bnctx> is an optional preallocated BN_CTX (to save the overhead of allocating | |
119 | and freeing the structure in a loop). | |
120 | The values for I<libctx>, I<propq> and I<bnctx> may be NULL. | |
121 | The caller is responsible for freeing the OSSL_PARAM pointer returned. | |
122 | ||
60b350a3 | 123 | EC_GROUP_new_from_ecparameters() will create a group from the |
2da8d4eb | 124 | specified I<params> and |
4fc55c1d | 125 | EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK |
2da8d4eb | 126 | I<params>. |
aafbe1cc | 127 | |
2da8d4eb MC |
128 | EC_GROUP_set_curve() sets the curve parameters I<p>, I<a> and I<b>. For a curve |
129 | over Fp I<p> is the prime for the field. For a curve over F2^m I<p> represents | |
4fc55c1d | 130 | the irreducible polynomial - each bit represents a term in the polynomial. |
8c1cbc72 | 131 | Therefore, there will either be three or five bits set dependent on whether the |
4fc55c1d | 132 | polynomial is a trinomial or a pentanomial. |
2da8d4eb | 133 | In either case, I<a> and I<b> represents the coefficients a and b from the |
eb2ff040 | 134 | relevant equation introduced above. |
aafbe1cc | 135 | |
de34e45a | 136 | EC_group_get_curve() obtains the previously set curve parameters. |
aafbe1cc | 137 | |
4fc55c1d NT |
138 | EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for |
139 | EC_GROUP_set_curve(). They are defined for backwards compatibility only and | |
140 | should not be used. | |
141 | ||
142 | EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for | |
143 | EC_GROUP_get_curve(). They are defined for backwards compatibility only and | |
144 | should not be used. | |
145 | ||
146 | The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are | |
147 | shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function. | |
148 | An appropriate default implementation method will be used. | |
149 | ||
150 | Whilst the library can be used to create any curve using the functions described | |
151 | above, there are also a number of predefined curves that are available. In order | |
152 | to obtain a list of all of the predefined curves, call the function | |
2da8d4eb MC |
153 | EC_get_builtin_curves(). The parameter I<r> should be an array of |
154 | EC_builtin_curve structures of size I<nitems>. The function will populate the | |
155 | I<r> array with information about the built-in curves. If I<nitems> is less than | |
156 | the total number of curves available, then the first I<nitems> curves will be | |
4fc55c1d NT |
157 | returned. Otherwise the total number of curves will be provided. The return |
158 | value is the total number of curves available (whether that number has been | |
2da8d4eb | 159 | populated in I<r> or not). Passing a NULL I<r>, or setting I<nitems> to 0 will |
4fc55c1d | 160 | do nothing other than return the total number of curves available. |
aafbe1cc MC |
161 | The EC_builtin_curve structure is defined as follows: |
162 | ||
1bc74519 RS |
163 | typedef struct { |
164 | int nid; | |
165 | const char *comment; | |
166 | } EC_builtin_curve; | |
aafbe1cc | 167 | |
2da8d4eb | 168 | Each EC_builtin_curve item has a unique integer id (I<nid>), and a human |
4fc55c1d | 169 | readable comment string describing the curve. |
aafbe1cc | 170 | |
4fc55c1d | 171 | In order to construct a built-in curve use the function |
d8652be0 | 172 | EC_GROUP_new_by_curve_name_ex() and provide the I<nid> of the curve to |
2da8d4eb | 173 | be constructed, the associated library context to be used in I<ctx> (see |
b4250010 | 174 | L<OSSL_LIB_CTX(3)>) and any property query string in I<propq>. The I<ctx> value |
2da8d4eb MC |
175 | may be NULL in which case the default library context is used. The I<propq> |
176 | value may also be NULL. | |
f585cefc | 177 | |
2da8d4eb | 178 | EC_GROUP_new_by_curve_name() is the same as |
d8652be0 | 179 | EC_GROUP_new_by_curve_name_ex() except that the default library context |
2da8d4eb | 180 | is always used along with a NULL property query string. |
aafbe1cc | 181 | |
4fc55c1d | 182 | EC_GROUP_free() frees the memory associated with the EC_GROUP. |
2da8d4eb | 183 | If I<group> is NULL nothing is done. |
aafbe1cc | 184 | |
4fc55c1d | 185 | EC_GROUP_clear_free() is deprecated: it was meant to destroy any sensitive data |
4a7a4972 NT |
186 | held within the EC_GROUP and then free its memory, but since all the data stored |
187 | in the EC_GROUP is public anyway, this function is unnecessary. | |
4fc55c1d | 188 | Its use can be safely replaced with EC_GROUP_free(). |
2da8d4eb | 189 | If I<group> is NULL nothing is done. |
aafbe1cc | 190 | |
f9253152 DDO |
191 | OSSL_EC_curve_nid2name() converts a curve I<nid> into the corresponding name. |
192 | ||
aafbe1cc MC |
193 | =head1 RETURN VALUES |
194 | ||
4fc55c1d NT |
195 | All EC_GROUP_new* functions return a pointer to the newly constructed group, or |
196 | NULL on error. | |
aafbe1cc | 197 | |
4fc55c1d NT |
198 | EC_get_builtin_curves() returns the number of built-in curves that are |
199 | available. | |
aafbe1cc | 200 | |
4fc55c1d NT |
201 | EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), |
202 | EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error. | |
aafbe1cc | 203 | |
f9253152 DDO |
204 | OSSL_EC_curve_nid2name() returns a character string constant, or NULL on error. |
205 | ||
aafbe1cc MC |
206 | =head1 SEE ALSO |
207 | ||
9e183d22 | 208 | L<crypto(7)>, L<EC_GROUP_copy(3)>, |
9b86974e | 209 | L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, |
f585cefc | 210 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>, |
b4250010 | 211 | L<OSSL_LIB_CTX(3)>, L<EVP_PKEY-EC(7)> |
f585cefc MC |
212 | |
213 | =head1 HISTORY | |
214 | ||
4a7a4972 NT |
215 | =over 2 |
216 | ||
217 | =item * | |
218 | ||
23ccae80 BB |
219 | EC_GROUP_new() was deprecated in OpenSSL 3.0. |
220 | ||
d8652be0 | 221 | EC_GROUP_new_by_curve_name_ex() and EC_GROUP_new_from_params() were |
c0f39ded | 222 | added in OpenSSL 3.0. |
aafbe1cc | 223 | |
4a7a4972 NT |
224 | =item * |
225 | ||
4fc55c1d NT |
226 | EC_GROUP_clear_free() was deprecated in OpenSSL 3.0; use EC_GROUP_free() |
227 | instead. | |
4a7a4972 | 228 | |
e52b4215 SL |
229 | =item * |
230 | ||
231 | EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), | |
232 | EC_GROUP_set_curve_GF2m() and EC_GROUP_get_curve_GF2m() were deprecated in | |
233 | OpenSSL 3.0; use EC_GROUP_set_curve() and EC_GROUP_get_curve() instead. | |
234 | ||
4a7a4972 NT |
235 | =back |
236 | ||
e2f92610 RS |
237 | =head1 COPYRIGHT |
238 | ||
e52b4215 | 239 | Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 240 | |
4746f25a | 241 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
242 | this file except in compliance with the License. You can obtain a copy |
243 | in the file LICENSE in the source distribution or at | |
244 | L<https://www.openssl.org/source/license.html>. | |
245 | ||
246 | =cut |