]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, |
6 | EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, | |
7 | EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, | |
8 | EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, | |
9 | EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, | |
10 | EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, | |
11 | EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, | |
12 | EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, | |
13 | EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, | |
14 | EC_GROUP_get_pentanomial_basis | |
15 | - Functions for manipulating EC_GROUP objects | |
aafbe1cc MC |
16 | |
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/ec.h> | |
aafbe1cc MC |
20 | |
21 | int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); | |
22 | EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); | |
23 | ||
24 | const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); | |
25 | ||
e9b77246 BB |
26 | int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, |
27 | const BIGNUM *order, const BIGNUM *cofactor); | |
aafbe1cc MC |
28 | const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); |
29 | ||
30 | int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); | |
be2e334f | 31 | const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group); |
14f46560 | 32 | int EC_GROUP_order_bits(const EC_GROUP *group); |
aafbe1cc | 33 | int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); |
be2e334f | 34 | const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group); |
aafbe1cc MC |
35 | |
36 | void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); | |
37 | int EC_GROUP_get_curve_name(const EC_GROUP *group); | |
38 | ||
39 | void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); | |
40 | int EC_GROUP_get_asn1_flag(const EC_GROUP *group); | |
41 | ||
42 | void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); | |
43 | point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); | |
44 | ||
45 | unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); | |
46 | size_t EC_GROUP_get_seed_len(const EC_GROUP *); | |
47 | size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); | |
48 | ||
49 | int EC_GROUP_get_degree(const EC_GROUP *group); | |
50 | ||
51 | int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); | |
52 | ||
53 | int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); | |
54 | ||
55 | int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); | |
56 | ||
57 | int EC_GROUP_get_basis_type(const EC_GROUP *); | |
58 | int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); | |
1bc74519 | 59 | int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, |
e9b77246 | 60 | unsigned int *k2, unsigned int *k3); |
aafbe1cc MC |
61 | |
62 | =head1 DESCRIPTION | |
63 | ||
64 | EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. | |
65 | ||
66 | EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created | |
67 | EC_GROUP object. | |
68 | ||
69 | EC_GROUP_method_of obtains the EC_METHOD of B<group>. | |
70 | ||
0d4fb843 F |
71 | EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These |
72 | parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the | |
aafbe1cc | 73 | curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and |
186bb907 | 74 | n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve. |
aafbe1cc MC |
75 | |
76 | EC_GROUP_get0_generator returns the generator for the identified B<group>. | |
77 | ||
78 | The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters | |
79 | with the respective order and cofactors for the B<group>. | |
80 | ||
81 | The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively | |
9b86974e | 82 | (see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name |
aafbe1cc MC |
83 | will return 0. |
84 | ||
146ca72c DSH |
85 | The asn1_flag value is used to determine whether the curve encoding uses |
86 | explicit parameters or a named curve using an ASN1 OID: many applications only | |
87 | support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the | |
88 | named curve form is used and the parameters must have a corresponding | |
89 | named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the | |
90 | parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and | |
91 | EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. | |
92 | Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for | |
93 | previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL | |
94 | 1.1.0 the default form was to use explicit parameters (meaning that | |
95 | applications would have to explicitly set the named curve form) in OpenSSL | |
96 | 1.1.0 and later the named curve form is the default. | |
aafbe1cc | 97 | |
186bb907 | 98 | The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). |
1bc74519 | 99 | point_conversion_form_t is an enum defined as follows: |
aafbe1cc MC |
100 | |
101 | typedef enum { | |
1bc74519 RS |
102 | /** the point is encoded as z||x, where the octet z specifies |
103 | * which solution of the quadratic equation y is */ | |
104 | POINT_CONVERSION_COMPRESSED = 2, | |
14f46560 | 105 | /** the point is encoded as z||x||y, where z is the octet 0x04 */ |
1bc74519 RS |
106 | POINT_CONVERSION_UNCOMPRESSED = 4, |
107 | /** the point is encoded as z||x||y, where the octet z specifies | |
aafbe1cc | 108 | * which solution of the quadratic equation y is */ |
1bc74519 | 109 | POINT_CONVERSION_HYBRID = 6 |
aafbe1cc MC |
110 | } point_conversion_form_t; |
111 | ||
aafbe1cc MC |
112 | For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by |
113 | the octets for x, followed by the octets for y. | |
114 | ||
115 | For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For | |
116 | POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of | |
1bc74519 | 117 | the two possible solutions for y has been used, followed by the octets for x. |
aafbe1cc MC |
118 | |
119 | For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two | |
120 | possible solutions for y has been used, followed by the octets for x, followed by the octets for y. | |
121 | ||
122 | The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form | |
123 | for the curve respectively. | |
124 | ||
125 | ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages | |
126 | in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. | |
127 | If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library | |
128 | does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block | |
129 | containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the | |
130 | builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using | |
131 | EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use | |
132 | this seed value, although it will be preserved in any ASN1 based communications. | |
133 | ||
134 | EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be | |
135 | the value m. | |
136 | ||
137 | The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid. | |
138 | For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is | |
139 | simply b. In either case for the curve to be valid the discriminant must be non zero. | |
140 | ||
141 | The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include | |
142 | verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has | |
143 | the correct order. | |
144 | ||
145 | EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not. | |
146 | ||
147 | The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves | |
148 | defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial | |
149 | function f(x). This function is either a trinomial of the form: | |
150 | ||
151 | f(x) = x^m + x^k + 1 with m > k >= 1 | |
152 | ||
153 | or a pentanomial of the form: | |
154 | ||
155 | f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 | |
156 | ||
157 | The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The | |
186bb907 | 158 | function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly |
aafbe1cc MC |
159 | the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>, |
160 | B<k2> and B<k3> respectively. | |
161 | ||
162 | =head1 RETURN VALUES | |
163 | ||
164 | The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, | |
165 | EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. | |
166 | ||
167 | EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. | |
168 | ||
169 | EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. | |
170 | ||
171 | EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. | |
172 | ||
173 | EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form | |
174 | and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the | |
175 | specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0. | |
176 | ||
be2e334f DSH |
177 | EC_GROUP_get0_order() returns an internal pointer to the group order. |
178 | EC_GROUP_get_order_bits() returns the number of bits in the group order. | |
179 | EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor. | |
180 | ||
aafbe1cc MC |
181 | EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not |
182 | specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. | |
183 | ||
184 | EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is | |
d900a015 | 185 | 0, the return value will be 1. On error 0 is returned. |
aafbe1cc MC |
186 | |
187 | EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. | |
188 | ||
189 | EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a | |
190 | trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. | |
191 | ||
192 | =head1 SEE ALSO | |
193 | ||
9e183d22 | 194 | L<crypto(7)>, L<EC_GROUP_new(3)>, |
9b86974e RS |
195 | L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, |
196 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> | |
aafbe1cc | 197 | |
e2f92610 RS |
198 | =head1 COPYRIGHT |
199 | ||
9e183d22 | 200 | Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
201 | |
202 | Licensed under the OpenSSL license (the "License"). You may not use | |
203 | this file except in compliance with the License. You can obtain a copy | |
204 | in the file LICENSE in the source distribution or at | |
205 | L<https://www.openssl.org/source/license.html>. | |
206 | ||
207 | =cut |