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