Debian Codegraph @

upstream/debian-unstable/man3/EC_POINT_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EC_POINT_NEW 3SSL"
58 .TH EC_POINT_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EC_POINT_set_Jprojective_coordinates_GFp,
65 EC_POINT_point2buf,
66 EC_POINT_new,
67 EC_POINT_free,
68 EC_POINT_clear_free,
69 EC_POINT_copy,
70 EC_POINT_dup,
71 EC_POINT_method_of,
72 EC_POINT_set_to_infinity,
73 EC_POINT_get_Jprojective_coordinates_GFp,
74 EC_POINT_set_affine_coordinates,
75 EC_POINT_get_affine_coordinates,
76 EC_POINT_set_compressed_coordinates,
77 EC_POINT_set_affine_coordinates_GFp,
78 EC_POINT_get_affine_coordinates_GFp,
79 EC_POINT_set_compressed_coordinates_GFp,
80 EC_POINT_set_affine_coordinates_GF2m,
81 EC_POINT_get_affine_coordinates_GF2m,
82 EC_POINT_set_compressed_coordinates_GF2m,
83 EC_POINT_point2oct,
84 EC_POINT_oct2point,
85 EC_POINT_point2bn,
86 EC_POINT_bn2point,
87 EC_POINT_point2hex,
88 EC_POINT_hex2point
89 \&\- Functions for creating, destroying and manipulating EC_POINT objects
90 .SH SYNOPSIS
91 .IX Header "SYNOPSIS"
92 .Vb 1
93 \& #include <openssl/ec.h>
94 \&
95 \& EC_POINT *EC_POINT_new(const EC_GROUP *group);
96 \& void EC_POINT_free(EC_POINT *point);
97 \& void EC_POINT_clear_free(EC_POINT *point);
98 \& int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
99 \& EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
100 \& int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
101 \& int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
102 \& const BIGNUM *x, const BIGNUM *y,
103 \& BN_CTX *ctx);
104 \& int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,
105 \& BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
106 \& int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,
107 \& const BIGNUM *x, int y_bit,
108 \& BN_CTX *ctx);
109 \& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
110 \& point_conversion_form_t form,
111 \& unsigned char *buf, size_t len, BN_CTX *ctx);
112 \& size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,
113 \& point_conversion_form_t form,
114 \& unsigned char **pbuf, BN_CTX *ctx);
115 \& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
116 \& const unsigned char *buf, size_t len, BN_CTX *ctx);
117 \& char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,
118 \& point_conversion_form_t form, BN_CTX *ctx);
119 \& EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,
120 \& EC_POINT *p, BN_CTX *ctx);
121 .Ve
122 .PP
123 The following functions have been deprecated since OpenSSL 3.0, and can be
124 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
125 see \fBopenssl_user_macros\fR\|(7):
126 .PP
127 .Vb 10
128 \& const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
129 \& int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
130 \& EC_POINT *p,
131 \& const BIGNUM *x, const BIGNUM *y,
132 \& const BIGNUM *z, BN_CTX *ctx);
133 \& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
134 \& const EC_POINT *p,
135 \& BIGNUM *x, BIGNUM *y, BIGNUM *z,
136 \& BN_CTX *ctx);
137 \& int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
138 \& const BIGNUM *x, const BIGNUM *y,
139 \& BN_CTX *ctx);
140 \& int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
141 \& const EC_POINT *p,
142 \& BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
143 \& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,
144 \& EC_POINT *p,
145 \& const BIGNUM *x, int y_bit,
146 \& BN_CTX *ctx);
147 \& int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
148 \& const BIGNUM *x, const BIGNUM *y,
149 \& BN_CTX *ctx);
150 \& int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
151 \& const EC_POINT *p,
152 \& BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
153 \& int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,
154 \& EC_POINT *p,
155 \& const BIGNUM *x, int y_bit,
156 \& BN_CTX *ctx);
157 \& BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,
158 \& point_conversion_form_t form, BIGNUM *bn,
159 \& BN_CTX *ctx);
160 \& EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,
161 \& EC_POINT *p, BN_CTX *ctx);
162 .Ve
163 .SH DESCRIPTION
164 .IX Header "DESCRIPTION"
165 An \fBEC_POINT\fR structure represents a point on a curve. A new point is
166 constructed by calling the function \fBEC_POINT_new()\fR and providing the
167 \&\fBgroup\fR object that the point relates to.
168 .PP
169 \&\fBEC_POINT_free()\fR frees the memory associated with the \fBEC_POINT\fR.
170 if \fBpoint\fR is NULL nothing is done.
171 .PP
172 \&\fBEC_POINT_clear_free()\fR destroys any sensitive data held within the EC_POINT and
173 then frees its memory. If \fBpoint\fR is NULL nothing is done.
174 .PP
175 \&\fBEC_POINT_copy()\fR copies the point \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR
176 must use the same \fBEC_METHOD\fR.
177 .PP
178 \&\fBEC_POINT_dup()\fR creates a new \fBEC_POINT\fR object and copies the content from
179 \&\fBsrc\fR to the newly created \fBEC_POINT\fR object.
180 .PP
181 \&\fBEC_POINT_method_of()\fR obtains the \fBEC_METHOD\fR associated with \fBpoint\fR.
182 This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a
183 public concept.
184 .PP
185 A valid point on a curve is the special point at infinity. A point is set to
186 be at infinity by calling \fBEC_POINT_set_to_infinity()\fR.
187 .PP
188 The affine coordinates for a point describe a point in terms of its x and y
189 position. The function \fBEC_POINT_set_affine_coordinates()\fR sets the \fBx\fR and \fBy\fR
190 coordinates for the point \fBp\fR defined over the curve given in \fBgroup\fR. The
191 function \fBEC_POINT_get_affine_coordinates()\fR sets \fBx\fR and \fBy\fR, either of which
192 may be NULL, to the corresponding coordinates of \fBp\fR.
193 .PP
194 The functions \fBEC_POINT_set_affine_coordinates_GFp()\fR and
195 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR are synonyms for
196 \&\fBEC_POINT_set_affine_coordinates()\fR. They are defined for backwards compatibility
197 only and should not be used.
198 .PP
199 The functions \fBEC_POINT_get_affine_coordinates_GFp()\fR and
200 \&\fBEC_POINT_get_affine_coordinates_GF2m()\fR are synonyms for
201 \&\fBEC_POINT_get_affine_coordinates()\fR. They are defined for backwards compatibility
202 only and should not be used.
203 .PP
204 As well as the affine coordinates, a point can alternatively be described in
205 terms of its Jacobian projective coordinates (for Fp curves only). Jacobian
206 projective coordinates are expressed as three values x, y and z. Working in
207 this coordinate system provides more efficient point multiplication
208 operations. A mapping exists between Jacobian projective coordinates and
209 affine coordinates. A Jacobian projective coordinate (x, y, z) can be written
210 as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian
211 projective from affine coordinates is simple. The coordinate (x, y) is mapped
212 to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used,
213 to set or get the projective coordinates in older versions use
214 \&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR and
215 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR respectively.
216 Modern versions should instead use \fBEC_POINT_set_affine_coordinates()\fR and
217 \&\fBEC_POINT_get_affine_coordinates()\fR, performing the conversion manually using the
218 above maps in such rare circumstances.
219 .PP
220 Points can also be described in terms of their compressed coordinates. For a
221 point (x, y), for any given value for x such that the point is on the curve
222 there will only ever be two possible values for y. Therefore, a point can be set
223 using the \fBEC_POINT_set_compressed_coordinates()\fR function where \fBx\fR is the x
224 coordinate and \fBy_bit\fR is a value 0 or 1 to identify which of the two
225 possible values for y should be used.
226 .PP
227 The functions \fBEC_POINT_set_compressed_coordinates_GFp()\fR and
228 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR are synonyms for
229 \&\fBEC_POINT_set_compressed_coordinates()\fR. They are defined for backwards
230 compatibility only and should not be used.
231 .PP
232 In addition \fBEC_POINT\fR can be converted to and from various external
233 representations. The octet form is the binary encoding of the \fBECPoint\fR
234 structure (as defined in RFC5480 and used in certificates and TLS records):
235 only the content octets are present, the \fBOCTET STRING\fR tag and length are
236 not included. \fBBIGNUM\fR form is the octet form interpreted as a big endian
237 integer converted to a \fBBIGNUM\fR structure. Hexadecimal form is the octet
238 form converted to a NULL terminated character string where each character
239 is one of the printable values 0\-9 or A\-F (or a\-f).
240 .PP
241 The functions \fBEC_POINT_point2oct()\fR, \fBEC_POINT_oct2point()\fR, \fBEC_POINT_point2bn()\fR,
242 \&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2hex()\fR and \fBEC_POINT_hex2point()\fR convert from
243 and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.
244 .PP
245 The function \fBEC_POINT_point2oct()\fR encodes the given curve point \fBp\fR as an
246 octet string into the buffer \fBbuf\fR of size \fBlen\fR, using the specified
247 conversion form \fBform\fR.
248 The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
249 Cryptography") standard.
250 Similarly the function \fBEC_POINT_oct2point()\fR decodes a curve point into \fBp\fR from
251 the octet string contained in the given buffer \fBbuf\fR of size \fBlen\fR, conforming
252 to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
253 .PP
254 The functions \fBEC_POINT_point2hex()\fR and \fBEC_POINT_point2bn()\fR convert a point \fBp\fR,
255 respectively, to the hexadecimal or BIGNUM representation of the same
256 encoding of the function \fBEC_POINT_point2oct()\fR.
257 Vice versa, similarly to the function \fBEC_POINT_oct2point()\fR, the functions
258 \&\fBEC_POINT_hex2point()\fR and \fBEC_POINT_point2bn()\fR decode the hexadecimal or
259 BIGNUM representation into the EC_POINT \fBp\fR.
260 .PP
261 Notice that, according to the standard, the octet string encoding of the point
262 at infinity for a given curve is fixed to a single octet of value zero and that,
263 vice versa, a single octet of size zero is decoded as the point at infinity.
264 .PP
265 The function \fBEC_POINT_point2oct()\fR must be supplied with a buffer long enough to
266 store the octet form. The return value provides the number of octets stored.
267 Calling the function with a NULL buffer will not perform the conversion but
268 will still return the required buffer length.
269 .PP
270 The function \fBEC_POINT_point2buf()\fR allocates a buffer of suitable length and
271 writes an EC_POINT to it in octet format. The allocated buffer is written to
272 \&\fB*pbuf\fR and its length is returned. The caller must free up the allocated
273 buffer with a call to \fBOPENSSL_free()\fR. Since the allocated buffer value is
274 written to \fB*pbuf\fR the \fBpbuf\fR parameter \fBMUST NOT\fR be \fBNULL\fR.
275 .PP
276 The function \fBEC_POINT_point2hex()\fR will allocate sufficient memory to store the
277 hexadecimal string. It is the caller's responsibility to free this memory with
278 a subsequent call to \fBOPENSSL_free()\fR.
279 .SH "RETURN VALUES"
280 .IX Header "RETURN VALUES"
281 \&\fBEC_POINT_new()\fR and \fBEC_POINT_dup()\fR return the newly allocated EC_POINT or NULL
282 on error.
283 .PP
284 The following functions return 1 on success or 0 on error: \fBEC_POINT_copy()\fR,
285 \&\fBEC_POINT_set_to_infinity()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR,
286 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR,
287 \&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR,
288 \&\fBEC_POINT_set_compressed_coordinates_GFp()\fR,
289 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR,
290 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR and \fBEC_POINT_oct2point()\fR.
291 .PP
292 EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
293 .PP
294 \&\fBEC_POINT_point2oct()\fR and \fBEC_POINT_point2buf()\fR return the length of the required
295 buffer or 0 on error.
296 .PP
297 \&\fBEC_POINT_point2bn()\fR returns the pointer to the BIGNUM supplied, or NULL on
298 error.
299 .PP
300 \&\fBEC_POINT_bn2point()\fR returns the pointer to the EC_POINT supplied, or NULL on
301 error.
302 .PP
303 \&\fBEC_POINT_point2hex()\fR returns a pointer to the hex string, or NULL on error.
304 .PP
305 \&\fBEC_POINT_hex2point()\fR returns the pointer to the EC_POINT supplied, or NULL on
306 error.
307 .SH "SEE ALSO"
308 .IX Header "SEE ALSO"
309 \&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3),
310 \&\fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3),
311 \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3)
312 .SH HISTORY
313 .IX Header "HISTORY"
314 \&\fBEC_POINT_method_of()\fR,
315 \&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR,
316 \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR,
317 \&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR,
318 \&\fBEC_POINT_set_compressed_coordinates_GFp()\fR,
319 \&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR,
320 \&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR,
321 \&\fBEC_POINT_point2bn()\fR, and \fBEC_POINT_bn2point()\fR were deprecated in OpenSSL 3.0.
322 .PP
323 \&\fBEC_POINT_set_affine_coordinates\fR, \fBEC_POINT_get_affine_coordinates\fR,
324 and \fBEC_POINT_set_compressed_coordinates\fR were
325 added in OpenSSL 1.1.1.
326 .SH COPYRIGHT
327 .IX Header "COPYRIGHT"
328 Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved.
329 .PP
330 Licensed under the Apache License 2.0 (the "License"). You may not use
331 this file except in compliance with the License. You can obtain a copy
332 in the file LICENSE in the source distribution or at
333 <https://www.openssl.org/source/license.html>.