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