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