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