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