]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
60b350a3 RS |
5 | EC_GROUP_new, EC_GROUP_new_from_ecparameters, |
6 | EC_GROUP_new_from_ecpkparameters, | |
7 | EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, | |
8 | EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, | |
9 | EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, | |
10 | EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> | |
11 | objects. | |
aafbe1cc MC |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/ec.h> | |
16 | #include <openssl/bn.h> | |
17 | ||
18 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); | |
60b350a3 RS |
19 | EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) |
20 | EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) | |
aafbe1cc MC |
21 | void EC_GROUP_free(EC_GROUP *group); |
22 | void EC_GROUP_clear_free(EC_GROUP *group); | |
23 | ||
24 | EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
25 | EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
26 | EC_GROUP *EC_GROUP_new_by_curve_name(int nid); | |
27 | ||
28 | int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
29 | int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | |
30 | int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | |
31 | int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | |
32 | ||
60b350a3 RS |
33 | ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params) |
34 | ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params) | |
35 | ||
aafbe1cc MC |
36 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); |
37 | ||
38 | =head1 DESCRIPTION | |
39 | ||
40 | Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the | |
41 | 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 | |
42 | elliptic curve equation as follows: | |
43 | ||
44 | y^2 mod p = x^3 +ax + b mod p | |
45 | ||
46 | The second form is those defined over a binary field F2^m where the elements of the field are integers of length at | |
47 | most m bits. For this form the elliptic curve equation is modified to: | |
48 | ||
49 | y^2 + xy = x^3 + ax^2 + b (where b != 0) | |
50 | ||
51 | Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL | |
52 | use a trinomial or a pentanomial for this parameter. | |
53 | ||
54 | A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see | |
9b86974e | 55 | L<EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or |
186bb907 | 56 | EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. |
60b350a3 RS |
57 | EC_GROUP_new_from_ecparameters() will create a group from the |
58 | specified B<params> and | |
59 | EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. | |
aafbe1cc MC |
60 | |
61 | EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>. | |
62 | EC_group_get_curve_GFp obtains the previously set curve parameters. | |
63 | ||
64 | EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents | |
186bb907 AM |
65 | the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three |
66 | or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. | |
aafbe1cc MC |
67 | EC_group_get_curve_GF2m obtains the previously set curve parameters. |
68 | ||
69 | The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the | |
70 | appropriate EC_group_set_curve function. An appropriate default implementation method will be used. | |
71 | ||
72 | Whilst the library can be used to create any curve using the functions described above, there are also a number of | |
73 | predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function | |
74 | EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function | |
75 | will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of | |
76 | curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be | |
77 | provided. The return value is the total number of curves available (whether that number has been populated in B<r> or | |
78 | not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. | |
79 | The EC_builtin_curve structure is defined as follows: | |
80 | ||
81 | typedef struct { | |
82 | int nid; | |
83 | const char *comment; | |
84 | } EC_builtin_curve; | |
85 | ||
86 | Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. | |
87 | ||
88 | In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to | |
89 | be constructed. | |
90 | ||
91 | EC_GROUP_free frees the memory associated with the EC_GROUP. | |
8fdc3734 | 92 | If B<group> is NULL nothing is done. |
aafbe1cc MC |
93 | |
94 | EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. | |
8fdc3734 | 95 | If B<group> is NULL nothing is done. |
aafbe1cc MC |
96 | |
97 | =head1 RETURN VALUES | |
98 | ||
99 | All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. | |
100 | ||
101 | EC_get_builtin_curves returns the number of builtin curves that are available. | |
102 | ||
103 | 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. | |
104 | ||
105 | =head1 SEE ALSO | |
106 | ||
9b86974e RS |
107 | L<crypto(3)>, L<ec(3)>, L<EC_GROUP_copy(3)>, |
108 | L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, | |
109 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> | |
aafbe1cc MC |
110 | |
111 | =cut |