]>
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); | |
aafbe1cc | 41 | int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); |
de34e45a MC |
42 | int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p, |
43 | const BIGNUM *x, const BIGNUM *y, | |
44 | BN_CTX *ctx); | |
45 | int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p, | |
46 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
47 | int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p, | |
48 | const BIGNUM *x, int y_bit, | |
49 | BN_CTX *ctx); | |
07caec83 BB |
50 | size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, |
51 | point_conversion_form_t form, | |
52 | unsigned char *buf, size_t len, BN_CTX *ctx); | |
53 | size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, | |
54 | point_conversion_form_t form, | |
55 | unsigned char **pbuf, BN_CTX *ctx); | |
56 | int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, | |
57 | const unsigned char *buf, size_t len, BN_CTX *ctx); | |
07caec83 BB |
58 | char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, |
59 | point_conversion_form_t form, BN_CTX *ctx); | |
60 | EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, | |
61 | EC_POINT *p, BN_CTX *ctx); | |
62 | ||
3dbf8243 MC |
63 | The following functions have been deprecated since OpenSSL 3.0, and can be |
64 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
65 | see L<openssl_user_macros(7)>: | |
07caec83 | 66 | |
23ccae80 | 67 | const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); |
07caec83 BB |
68 | int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, |
69 | EC_POINT *p, | |
70 | const BIGNUM *x, const BIGNUM *y, | |
71 | const BIGNUM *z, BN_CTX *ctx); | |
72 | int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, | |
73 | const EC_POINT *p, | |
74 | BIGNUM *x, BIGNUM *y, BIGNUM *z, | |
75 | BN_CTX *ctx); | |
aafbe1cc | 76 | int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, |
43986596 DSH |
77 | const BIGNUM *x, const BIGNUM *y, |
78 | BN_CTX *ctx); | |
aafbe1cc | 79 | int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, |
43986596 DSH |
80 | const EC_POINT *p, |
81 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
82 | int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, | |
83 | EC_POINT *p, | |
84 | const BIGNUM *x, int y_bit, | |
85 | BN_CTX *ctx); | |
aafbe1cc | 86 | int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, |
43986596 DSH |
87 | const BIGNUM *x, const BIGNUM *y, |
88 | BN_CTX *ctx); | |
aafbe1cc | 89 | int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, |
43986596 DSH |
90 | const EC_POINT *p, |
91 | BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | |
92 | int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, | |
93 | EC_POINT *p, | |
94 | const BIGNUM *x, int y_bit, | |
95 | BN_CTX *ctx); | |
c1131e6a SL |
96 | BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, |
97 | point_conversion_form_t form, BIGNUM *bn, | |
98 | BN_CTX *ctx); | |
99 | EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, | |
100 | EC_POINT *p, BN_CTX *ctx); | |
aafbe1cc MC |
101 | |
102 | =head1 DESCRIPTION | |
103 | ||
43986596 DSH |
104 | An B<EC_POINT> structure represents a point on a curve. A new point is |
105 | constructed by calling the function EC_POINT_new() and providing the | |
106 | B<group> object that the point relates to. | |
aafbe1cc | 107 | |
43986596 | 108 | EC_POINT_free() frees the memory associated with the B<EC_POINT>. |
8fdc3734 | 109 | if B<point> is NULL nothing is done. |
aafbe1cc | 110 | |
43986596 DSH |
111 | EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and |
112 | then frees its memory. If B<point> is NULL nothing is done. | |
113 | ||
114 | EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst> | |
115 | must use the same B<EC_METHOD>. | |
116 | ||
117 | EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from | |
118 | B<src> to the newly created B<EC_POINT> object. | |
119 | ||
120 | EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>. | |
23ccae80 BB |
121 | This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a |
122 | public concept. | |
43986596 DSH |
123 | |
124 | A valid point on a curve is the special point at infinity. A point is set to | |
125 | be at infinity by calling EC_POINT_set_to_infinity(). | |
126 | ||
9a271795 | 127 | The affine coordinates for a point describe a point in terms of its x and y |
de34e45a | 128 | position. The function EC_POINT_set_affine_coordinates() sets the B<x> and B<y> |
9a271795 | 129 | coordinates for the point B<p> defined over the curve given in B<group>. The |
de34e45a MC |
130 | function EC_POINT_get_affine_coordinates() sets B<x> and B<y>, either of which |
131 | may be NULL, to the corresponding coordinates of B<p>. | |
132 | ||
133 | The functions EC_POINT_set_affine_coordinates_GFp() and | |
134 | EC_POINT_set_affine_coordinates_GF2m() are synonyms for | |
50db8163 MC |
135 | EC_POINT_set_affine_coordinates(). They are defined for backwards compatibility |
136 | only and should not be used. | |
de34e45a MC |
137 | |
138 | The functions EC_POINT_get_affine_coordinates_GFp() and | |
139 | EC_POINT_get_affine_coordinates_GF2m() are synonyms for | |
50db8163 MC |
140 | EC_POINT_get_affine_coordinates(). They are defined for backwards compatibility |
141 | only and should not be used. | |
43986596 | 142 | |
9a271795 DP |
143 | As well as the affine coordinates, a point can alternatively be described in |
144 | terms of its Jacobian projective coordinates (for Fp curves only). Jacobian | |
145 | projective coordinates are expressed as three values x, y and z. Working in | |
146 | this coordinate system provides more efficient point multiplication | |
147 | operations. A mapping exists between Jacobian projective coordinates and | |
148 | affine coordinates. A Jacobian projective coordinate (x, y, z) can be written | |
149 | as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian | |
150 | projective from affine coordinates is simple. The coordinate (x, y) is mapped | |
07caec83 | 151 | to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used, |
9a271795 | 152 | to set or get the projective coordinates in older versions use |
43986596 DSH |
153 | EC_POINT_set_Jprojective_coordinates_GFp() and |
154 | EC_POINT_get_Jprojective_coordinates_GFp() respectively. | |
07caec83 BB |
155 | Modern versions should instead use EC_POINT_set_affine_coordinates() and |
156 | EC_POINT_get_affine_coordinates(), performing the conversion manually using the | |
157 | above maps in such rare circumstances. | |
43986596 | 158 | |
9a271795 | 159 | Points can also be described in terms of their compressed coordinates. For a |
43986596 | 160 | point (x, y), for any given value for x such that the point is on the curve |
8c1cbc72 | 161 | there will only ever be two possible values for y. Therefore, a point can be set |
de34e45a | 162 | using the EC_POINT_set_compressed_coordinates() function where B<x> is the x |
9a271795 | 163 | coordinate and B<y_bit> is a value 0 or 1 to identify which of the two |
43986596 DSH |
164 | possible values for y should be used. |
165 | ||
de34e45a MC |
166 | The functions EC_POINT_set_compressed_coordinates_GFp() and |
167 | EC_POINT_set_compressed_coordinates_GF2m() are synonyms for | |
50db8163 MC |
168 | EC_POINT_set_compressed_coordinates(). They are defined for backwards |
169 | compatibility only and should not be used. | |
de34e45a | 170 | |
43986596 DSH |
171 | In addition B<EC_POINT> can be converted to and from various external |
172 | representations. The octet form is the binary encoding of the B<ECPoint> | |
173 | structure (as defined in RFC5480 and used in certificates and TLS records): | |
174 | only the content octets are present, the B<OCTET STRING> tag and length are | |
175 | not included. B<BIGNUM> form is the octet form interpreted as a big endian | |
176 | integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet | |
177 | form converted to a NULL terminated character string where each character | |
178 | is one of the printable values 0-9 or A-F (or a-f). | |
179 | ||
180 | The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), | |
181 | EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from | |
182 | and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively. | |
183 | ||
3cc26f2e NT |
184 | The function EC_POINT_point2oct() encodes the given curve point B<p> as an |
185 | octet string into the buffer B<buf> of size B<len>, using the specified | |
186 | conversion form B<form>. | |
187 | The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve | |
188 | Cryptography") standard. | |
189 | Similarly the function EC_POINT_oct2point() decodes a curve point into B<p> from | |
190 | the octet string contained in the given buffer B<buf> of size B<len>, conforming | |
191 | to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. | |
192 | ||
193 | The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point B<p>, | |
194 | respectively, to the hexadecimal or BIGNUM representation of the same | |
195 | encoding of the function EC_POINT_point2oct(). | |
196 | Vice versa, similarly to the function EC_POINT_oct2point(), the functions | |
197 | EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or | |
198 | BIGNUM representation into the EC_POINT B<p>. | |
199 | ||
200 | Notice that, according to the standard, the octet string encoding of the point | |
201 | at infinity for a given curve is fixed to a single octet of value zero and that, | |
202 | vice versa, a single octet of size zero is decoded as the point at infinity. | |
203 | ||
43986596 DSH |
204 | The function EC_POINT_point2oct() must be supplied with a buffer long enough to |
205 | store the octet form. The return value provides the number of octets stored. | |
206 | Calling the function with a NULL buffer will not perform the conversion but | |
207 | will still return the required buffer length. | |
208 | ||
209 | The function EC_POINT_point2buf() allocates a buffer of suitable length and | |
210 | writes an EC_POINT to it in octet format. The allocated buffer is written to | |
211 | B<*pbuf> and its length is returned. The caller must free up the allocated | |
212 | buffer with a call to OPENSSL_free(). Since the allocated buffer value is | |
213 | written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>. | |
214 | ||
215 | The function EC_POINT_point2hex() will allocate sufficient memory to store the | |
216 | hexadecimal string. It is the caller's responsibility to free this memory with | |
217 | a subsequent call to OPENSSL_free(). | |
aafbe1cc MC |
218 | |
219 | =head1 RETURN VALUES | |
220 | ||
43986596 DSH |
221 | EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL |
222 | on error. | |
aafbe1cc | 223 | |
43986596 DSH |
224 | The following functions return 1 on success or 0 on error: EC_POINT_copy(), |
225 | EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), | |
226 | EC_POINT_get_Jprojective_coordinates_GFp(), | |
227 | EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), | |
228 | EC_POINT_set_compressed_coordinates_GFp(), | |
229 | EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), | |
230 | EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point(). | |
aafbe1cc MC |
231 | |
232 | EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. | |
233 | ||
6f4b929a | 234 | EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required |
43986596 | 235 | buffer or 0 on error. |
aafbe1cc | 236 | |
43986596 DSH |
237 | EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on |
238 | error. | |
aafbe1cc | 239 | |
43986596 DSH |
240 | EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on |
241 | error. | |
aafbe1cc | 242 | |
43986596 | 243 | EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error. |
aafbe1cc | 244 | |
43986596 DSH |
245 | EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on |
246 | error. | |
aafbe1cc MC |
247 | |
248 | =head1 SEE ALSO | |
249 | ||
9e183d22 | 250 | L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, |
9b86974e RS |
251 | L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, |
252 | L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> | |
aafbe1cc | 253 | |
07caec83 BB |
254 | =head1 HISTORY |
255 | ||
23ccae80 | 256 | EC_POINT_method_of(), |
07caec83 BB |
257 | EC_POINT_set_Jprojective_coordinates_GFp(), |
258 | EC_POINT_get_Jprojective_coordinates_GFp(), | |
259 | EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), | |
260 | EC_POINT_set_compressed_coordinates_GFp(), | |
261 | EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), | |
c1131e6a SL |
262 | EC_POINT_set_compressed_coordinates_GF2m(), |
263 | EC_POINT_point2bn(), and EC_POINT_bn2point() were deprecated in OpenSSL 3.0. | |
264 | ||
07caec83 BB |
265 | |
266 | B<EC_POINT_set_affine_coordinates>, B<EC_POINT_get_affine_coordinates>, | |
267 | and B<EC_POINT_set_compressed_coordinates> were | |
268 | added in OpenSSL 1.1.1. | |
269 | ||
e2f92610 RS |
270 | =head1 COPYRIGHT |
271 | ||
da1c088f | 272 | Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 273 | |
4746f25a | 274 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
275 | this file except in compliance with the License. You can obtain a copy |
276 | in the file LICENSE in the source distribution or at | |
277 | L<https://www.openssl.org/source/license.html>. | |
278 | ||
279 | =cut |