]>
Commit | Line | Data |
---|---|---|
aafbe1cc MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
de34e45a MC |
5 | EC_POINT_set_Jprojective_coordinates_GFp, |
6 | EC_POINT_point2buf, | |
7 | EC_POINT_new, | |
8 | EC_POINT_free, | |
9 | EC_POINT_clear_free, | |
10 | EC_POINT_copy, | |
11 | EC_POINT_dup, | |
12 | EC_POINT_method_of, | |
c952780c RS |
13 | EC_POINT_set_to_infinity, |
14 | EC_POINT_get_Jprojective_coordinates_GFp, | |
de34e45a MC |
15 | EC_POINT_set_affine_coordinates, |
16 | EC_POINT_get_affine_coordinates, | |
17 | EC_POINT_set_compressed_coordinates, | |
c952780c | 18 | EC_POINT_set_affine_coordinates_GFp, |
de34e45a MC |
19 | EC_POINT_get_affine_coordinates_GFp, |
20 | EC_POINT_set_compressed_coordinates_GFp, | |
21 | EC_POINT_set_affine_coordinates_GF2m, | |
22 | EC_POINT_get_affine_coordinates_GF2m, | |
23 | EC_POINT_set_compressed_coordinates_GF2m, | |
24 | EC_POINT_point2oct, | |
25 | EC_POINT_oct2point, | |
26 | EC_POINT_point2bn, | |
27 | EC_POINT_bn2point, | |
28 | EC_POINT_point2hex, | |
c952780c RS |
29 | EC_POINT_hex2point |
30 | - Functions for creating, destroying and manipulating EC_POINT objects | |
aafbe1cc MC |
31 | |
32 | =head1 SYNOPSIS | |
33 | ||
34 | #include <openssl/ec.h> | |
aafbe1cc MC |
35 | |
36 | EC_POINT *EC_POINT_new(const EC_GROUP *group); | |
37 | void EC_POINT_free(EC_POINT *point); | |
38 | void EC_POINT_clear_free(EC_POINT *point); | |
39 | int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); | |
40 | EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); | |
41 | const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); | |
42 | int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); | |
43986596 DSH |
43 | int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, |
44 | EC_POINT *p, | |
45 | const BIGNUM *x, const BIGNUM *y, | |
46 | const BIGNUM *z, BN_CTX *ctx); | |
aafbe1cc | 47 | int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, |
43986596 DSH |
48 | const EC_POINT *p, |
49 | BIGNUM *x, BIGNUM *y, BIGNUM *z, | |
50 | BN_CTX *ctx); | |
de34e45a MC |
51 | int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p, |
52 | const BIGNUM *x, const BIGNUM *y, | |
53 | BN_CTX *ctx); | |
54 | int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p, | |
55 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
56 | int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p, | |
57 | const BIGNUM *x, int y_bit, | |
58 | BN_CTX *ctx); | |
aafbe1cc | 59 | int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, |
43986596 DSH |
60 | const BIGNUM *x, const BIGNUM *y, |
61 | BN_CTX *ctx); | |
aafbe1cc | 62 | int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, |
43986596 DSH |
63 | const EC_POINT *p, |
64 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
65 | int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, | |
66 | EC_POINT *p, | |
67 | const BIGNUM *x, int y_bit, | |
68 | BN_CTX *ctx); | |
aafbe1cc | 69 | int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, |
43986596 DSH |
70 | const BIGNUM *x, const BIGNUM *y, |
71 | BN_CTX *ctx); | |
aafbe1cc | 72 | int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, |
43986596 DSH |
73 | const EC_POINT *p, |
74 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
75 | int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, | |
76 | EC_POINT *p, | |
77 | const BIGNUM *x, int y_bit, | |
78 | BN_CTX *ctx); | |
aafbe1cc | 79 | size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, |
43986596 DSH |
80 | point_conversion_form_t form, |
81 | unsigned char *buf, size_t len, BN_CTX *ctx); | |
82 | size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, | |
83 | point_conversion_form_t form, | |
84 | unsigned char **pbuf, BN_CTX *ctx); | |
aafbe1cc | 85 | int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, |
43986596 DSH |
86 | const unsigned char *buf, size_t len, BN_CTX *ctx); |
87 | BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, | |
88 | point_conversion_form_t form, BIGNUM *bn, | |
89 | BN_CTX *ctx); | |
90 | EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, | |
91 | EC_POINT *p, BN_CTX *ctx); | |
92 | char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, | |
93 | point_conversion_form_t form, BN_CTX *ctx); | |
94 | EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, | |
95 | EC_POINT *p, BN_CTX *ctx); | |
aafbe1cc MC |
96 | |
97 | ||
98 | =head1 DESCRIPTION | |
99 | ||
43986596 DSH |
100 | An B<EC_POINT> structure represents a point on a curve. A new point is |
101 | constructed by calling the function EC_POINT_new() and providing the | |
102 | B<group> object that the point relates to. | |
aafbe1cc | 103 | |
43986596 | 104 | EC_POINT_free() frees the memory associated with the B<EC_POINT>. |
8fdc3734 | 105 | if B<point> is NULL nothing is done. |
aafbe1cc | 106 | |
43986596 DSH |
107 | EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and |
108 | then frees its memory. If B<point> is NULL nothing is done. | |
109 | ||
110 | EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst> | |
111 | must use the same B<EC_METHOD>. | |
112 | ||
113 | EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from | |
114 | B<src> to the newly created B<EC_POINT> object. | |
115 | ||
116 | EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>. | |
117 | ||
118 | A valid point on a curve is the special point at infinity. A point is set to | |
119 | be at infinity by calling EC_POINT_set_to_infinity(). | |
120 | ||
121 | The affine co-ordinates for a point describe a point in terms of its x and y | |
de34e45a MC |
122 | position. The function EC_POINT_set_affine_coordinates() sets the B<x> and B<y> |
123 | co-ordinates for the point B<p> defined over the curve given in B<group>. The | |
124 | function EC_POINT_get_affine_coordinates() sets B<x> and B<y>, either of which | |
125 | may be NULL, to the corresponding coordinates of B<p>. | |
126 | ||
127 | The functions EC_POINT_set_affine_coordinates_GFp() and | |
128 | EC_POINT_set_affine_coordinates_GF2m() are synonyms for | |
50db8163 MC |
129 | EC_POINT_set_affine_coordinates(). They are defined for backwards compatibility |
130 | only and should not be used. | |
de34e45a MC |
131 | |
132 | The functions EC_POINT_get_affine_coordinates_GFp() and | |
133 | EC_POINT_get_affine_coordinates_GF2m() are synonyms for | |
50db8163 MC |
134 | EC_POINT_get_affine_coordinates(). They are defined for backwards compatibility |
135 | only and should not be used. | |
43986596 DSH |
136 | |
137 | As well as the affine co-ordinates, a point can alternatively be described in | |
138 | terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian | |
139 | projective co-ordinates are expressed as three values x, y and z. Working in | |
140 | this co-ordinate system provides more efficient point multiplication | |
141 | operations. A mapping exists between Jacobian projective co-ordinates and | |
142 | affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written | |
143 | as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian | |
14f46560 | 144 | projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped |
43986596 DSH |
145 | to (x, y, 1). To set or get the projective co-ordinates use |
146 | EC_POINT_set_Jprojective_coordinates_GFp() and | |
147 | EC_POINT_get_Jprojective_coordinates_GFp() respectively. | |
148 | ||
149 | Points can also be described in terms of their compressed co-ordinates. For a | |
150 | point (x, y), for any given value for x such that the point is on the curve | |
151 | there will only ever be two possible values for y. Therefore a point can be set | |
de34e45a | 152 | using the EC_POINT_set_compressed_coordinates() function where B<x> is the x |
43986596 DSH |
153 | co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two |
154 | possible values for y should be used. | |
155 | ||
de34e45a MC |
156 | The functions EC_POINT_set_compressed_coordinates_GFp() and |
157 | EC_POINT_set_compressed_coordinates_GF2m() are synonyms for | |
50db8163 MC |
158 | EC_POINT_set_compressed_coordinates(). They are defined for backwards |
159 | compatibility only and should not be used. | |
de34e45a | 160 | |
43986596 DSH |
161 | In addition B<EC_POINT> can be converted to and from various external |
162 | representations. The octet form is the binary encoding of the B<ECPoint> | |
163 | structure (as defined in RFC5480 and used in certificates and TLS records): | |
164 | only the content octets are present, the B<OCTET STRING> tag and length are | |
165 | not included. B<BIGNUM> form is the octet form interpreted as a big endian | |
166 | integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet | |
167 | form converted to a NULL terminated character string where each character | |
168 | is one of the printable values 0-9 or A-F (or a-f). | |
169 | ||
170 | The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), | |
171 | EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from | |
172 | and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively. | |
173 | ||
174 | The function EC_POINT_point2oct() must be supplied with a buffer long enough to | |
175 | store the octet form. The return value provides the number of octets stored. | |
176 | Calling the function with a NULL buffer will not perform the conversion but | |
177 | will still return the required buffer length. | |
178 | ||
179 | The function EC_POINT_point2buf() allocates a buffer of suitable length and | |
180 | writes an EC_POINT to it in octet format. The allocated buffer is written to | |
181 | B<*pbuf> and its length is returned. The caller must free up the allocated | |
182 | buffer with a call to OPENSSL_free(). Since the allocated buffer value is | |
183 | written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>. | |
184 | ||
185 | The function EC_POINT_point2hex() will allocate sufficient memory to store the | |
186 | hexadecimal string. It is the caller's responsibility to free this memory with | |
187 | a subsequent call to OPENSSL_free(). | |
aafbe1cc MC |
188 | |
189 | =head1 RETURN VALUES | |
190 | ||
43986596 DSH |
191 | EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL |
192 | on error. | |
aafbe1cc | 193 | |
43986596 DSH |
194 | The following functions return 1 on success or 0 on error: EC_POINT_copy(), |
195 | EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), | |
196 | EC_POINT_get_Jprojective_coordinates_GFp(), | |
197 | EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), | |
198 | EC_POINT_set_compressed_coordinates_GFp(), | |
199 | EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), | |
200 | EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point(). | |
aafbe1cc MC |
201 | |
202 | EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. | |
203 | ||
6f4b929a | 204 | EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required |
43986596 | 205 | buffer or 0 on error. |
aafbe1cc | 206 | |
43986596 DSH |
207 | EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on |
208 | error. | |
aafbe1cc | 209 | |
43986596 DSH |
210 | EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on |
211 | error. | |
aafbe1cc | 212 | |
43986596 | 213 | EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error. |
aafbe1cc | 214 | |
43986596 DSH |
215 | EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on |
216 | error. | |
aafbe1cc MC |
217 | |
218 | =head1 SEE ALSO | |
219 | ||
9e183d22 | 220 | L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, |
9b86974e RS |
221 | L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, |
222 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> | |
aafbe1cc | 223 | |
e2f92610 RS |
224 | =head1 COPYRIGHT |
225 | ||
0d664759 | 226 | Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 227 | |
4746f25a | 228 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
229 | this file except in compliance with the License. You can obtain a copy |
230 | in the file LICENSE in the source distribution or at | |
231 | L<https://www.openssl.org/source/license.html>. | |
232 | ||
233 | =cut |