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