]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
de34e45a MC |
5 | EC_GROUP_get_ecparameters, |
6 | EC_GROUP_get_ecpkparameters, | |
f585cefc | 7 | EC_GROUP_new_ex, |
de34e45a MC |
8 | EC_GROUP_new, |
9 | EC_GROUP_new_from_ecparameters, | |
60b350a3 | 10 | EC_GROUP_new_from_ecpkparameters, |
de34e45a MC |
11 | EC_GROUP_free, |
12 | EC_GROUP_clear_free, | |
13 | EC_GROUP_new_curve_GFp, | |
14 | EC_GROUP_new_curve_GF2m, | |
f585cefc | 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, | |
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 | |
f585cefc | 30 | EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth); |
aafbe1cc | 31 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); |
60b350a3 RS |
32 | EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) |
33 | EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) | |
aafbe1cc MC |
34 | void EC_GROUP_free(EC_GROUP *group); |
35 | void EC_GROUP_clear_free(EC_GROUP *group); | |
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); | |
f585cefc | 41 | EC_GROUP *EC_GROUP_new_by_curve_name_ex(OPENSSL_CTX *libctx, 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 | |
60b350a3 RS |
57 | ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params) |
58 | ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params) | |
59 | ||
aafbe1cc MC |
60 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); |
61 | ||
62 | =head1 DESCRIPTION | |
63 | ||
64 | Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the | |
65 | prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised | |
66 | elliptic curve equation as follows: | |
67 | ||
68 | y^2 mod p = x^3 +ax + b mod p | |
69 | ||
70 | The second form is those defined over a binary field F2^m where the elements of the field are integers of length at | |
71 | most m bits. For this form the elliptic curve equation is modified to: | |
72 | ||
73 | y^2 + xy = x^3 + ax^2 + b (where b != 0) | |
74 | ||
75 | Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL | |
76 | use a trinomial or a pentanomial for this parameter. | |
77 | ||
f585cefc MC |
78 | A new curve can be constructed by calling EC_GROUP_new_ex, using the implementation provided by B<meth> (see |
79 | L<EC_GFp_simple_method(3)>) and associated with the library context B<ctx> | |
80 | (see L<OPENSSL_CTX(3)>). | |
81 | The B<ctx> parameter may be NULL in which case the default library context is used. | |
82 | It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. | |
60b350a3 RS |
83 | EC_GROUP_new_from_ecparameters() will create a group from the |
84 | specified B<params> and | |
85 | EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. | |
aafbe1cc | 86 | |
f585cefc MC |
87 | EC_GROUP_new is the same as EC_GROUP_new_ex() except that the library context |
88 | used is always the default library context. | |
89 | ||
de34e45a MC |
90 | EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b> |
91 | is the prime for the field. For a curve over F2^m B<p> represents the irreducible polynomial - each bit | |
92 | represents a term in the polynomial. Therefore there will either be three or five bits set dependent on whether | |
93 | the polynomial is a trinomial or a pentanomial. | |
aafbe1cc | 94 | |
de34e45a | 95 | EC_group_get_curve() obtains the previously set curve parameters. |
aafbe1cc | 96 | |
50db8163 MC |
97 | EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for |
98 | backwards compatibility only and should not be used. | |
de34e45a | 99 | |
50db8163 MC |
100 | EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for |
101 | backwards compatibility only and should not be used. | |
de34e45a MC |
102 | |
103 | The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and then the | |
104 | EC_GROUP_set_curve function. An appropriate default implementation method will be used. | |
aafbe1cc MC |
105 | |
106 | Whilst the library can be used to create any curve using the functions described above, there are also a number of | |
107 | predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function | |
108 | EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function | |
109 | will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of | |
110 | curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be | |
111 | provided. The return value is the total number of curves available (whether that number has been populated in B<r> or | |
112 | not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. | |
113 | The EC_builtin_curve structure is defined as follows: | |
114 | ||
1bc74519 RS |
115 | typedef struct { |
116 | int nid; | |
117 | const char *comment; | |
118 | } EC_builtin_curve; | |
aafbe1cc MC |
119 | |
120 | Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. | |
121 | ||
f585cefc MC |
122 | In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name_ex and provide the B<nid> of the curve to |
123 | be constructed and the associated library context to be used in B<ctx> (see L<OPENSSL_CTX(3)>). | |
124 | The B<ctx> value may be NULL in which case the default library context is used. | |
125 | ||
126 | EC_GROUP_new_by_curve_name is the same as EC_GROUP_new_by_curve_name_ex except | |
127 | that the default library context is always used. | |
aafbe1cc MC |
128 | |
129 | EC_GROUP_free frees the memory associated with the EC_GROUP. | |
8fdc3734 | 130 | If B<group> is NULL nothing is done. |
aafbe1cc MC |
131 | |
132 | EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. | |
8fdc3734 | 133 | If B<group> is NULL nothing is done. |
aafbe1cc MC |
134 | |
135 | =head1 RETURN VALUES | |
136 | ||
137 | All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. | |
138 | ||
139 | EC_get_builtin_curves returns the number of builtin curves that are available. | |
140 | ||
141 | EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. | |
142 | ||
143 | =head1 SEE ALSO | |
144 | ||
9e183d22 | 145 | L<crypto(7)>, L<EC_GROUP_copy(3)>, |
9b86974e | 146 | L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, |
f585cefc MC |
147 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>, |
148 | L<OPENSSL_CTX(3)> | |
149 | ||
150 | =head1 HISTORY | |
151 | ||
152 | EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0. | |
aafbe1cc | 153 | |
e2f92610 RS |
154 | =head1 COPYRIGHT |
155 | ||
1212818e | 156 | Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 157 | |
4746f25a | 158 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
159 | this file except in compliance with the License. You can obtain a copy |
160 | in the file LICENSE in the source distribution or at | |
161 | L<https://www.openssl.org/source/license.html>. | |
162 | ||
163 | =cut |