summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EC_POINT_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EC_POINT_new.3')
-rw-r--r--src/lib/libcrypto/man/EC_POINT_new.3566
1 files changed, 0 insertions, 566 deletions
diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3
deleted file mode 100644
index c70755352d..0000000000
--- a/src/lib/libcrypto/man/EC_POINT_new.3
+++ /dev/null
@@ -1,566 +0,0 @@
1.\" $OpenBSD: EC_POINT_new.3,v 1.13 2021/05/13 05:52:28 tb Exp $
2.\" full merge up to: OpenSSL 50db8163 Jul 30 16:56:41 2018 +0100
3.\"
4.\" This file was written by Matt Caswell <matt@openssl.org>.
5.\" Copyright (c) 2013, 2016 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: May 13 2021 $
52.Dt EC_POINT_NEW 3
53.Os
54.Sh NAME
55.Nm EC_POINT_new ,
56.Nm EC_POINT_free ,
57.Nm EC_POINT_clear_free ,
58.Nm EC_POINT_copy ,
59.Nm EC_POINT_dup ,
60.Nm EC_POINT_method_of ,
61.Nm EC_POINT_set_to_infinity ,
62.Nm EC_POINT_set_affine_coordinates ,
63.Nm EC_POINT_set_affine_coordinates_GFp ,
64.Nm EC_POINT_set_affine_coordinates_GF2m ,
65.Nm EC_POINT_get_affine_coordinates ,
66.Nm EC_POINT_get_affine_coordinates_GFp ,
67.Nm EC_POINT_get_affine_coordinates_GF2m ,
68.Nm EC_POINT_set_Jprojective_coordinates_GFp ,
69.Nm EC_POINT_get_Jprojective_coordinates_GFp ,
70.Nm EC_POINT_set_compressed_coordinates ,
71.Nm EC_POINT_set_compressed_coordinates_GFp ,
72.Nm EC_POINT_set_compressed_coordinates_GF2m ,
73.Nm EC_POINT_point2oct ,
74.Nm EC_POINT_oct2point ,
75.Nm EC_POINT_point2bn ,
76.Nm EC_POINT_bn2point ,
77.Nm EC_POINT_point2hex ,
78.Nm EC_POINT_hex2point
79.Nd create, destroy, and manipulate EC_POINT objects
80.Sh SYNOPSIS
81.In openssl/ec.h
82.In openssl/bn.h
83.Ft EC_POINT *
84.Fo EC_POINT_new
85.Fa "const EC_GROUP *group"
86.Fc
87.Ft void
88.Fo EC_POINT_free
89.Fa "EC_POINT *point"
90.Fc
91.Ft void
92.Fo EC_POINT_clear_free
93.Fa "EC_POINT *point"
94.Fc
95.Ft int
96.Fo EC_POINT_copy
97.Fa "EC_POINT *dst"
98.Fa "const EC_POINT *src"
99.Fc
100.Ft EC_POINT *
101.Fo EC_POINT_dup
102.Fa "const EC_POINT *src"
103.Fa "const EC_GROUP *group"
104.Fc
105.Ft const EC_METHOD *
106.Fo EC_POINT_method_of
107.Fa "const EC_POINT *point"
108.Fc
109.Ft int
110.Fo EC_POINT_set_to_infinity
111.Fa "const EC_GROUP *group"
112.Fa "EC_POINT *point"
113.Fc
114.Ft int
115.Fo EC_POINT_set_affine_coordinates
116.Fa "const EC_GROUP *group"
117.Fa "EC_POINT *p"
118.Fa "const BIGNUM *x"
119.Fa "const BIGNUM *y"
120.Fa "BN_CTX *ctx"
121.Fc
122.Ft int
123.Fo EC_POINT_set_affine_coordinates_GFp
124.Fa "const EC_GROUP *group"
125.Fa "EC_POINT *p"
126.Fa "const BIGNUM *x"
127.Fa "const BIGNUM *y"
128.Fa "BN_CTX *ctx"
129.Fc
130.Ft int
131.Fo EC_POINT_set_affine_coordinates_GF2m
132.Fa "const EC_GROUP *group"
133.Fa "EC_POINT *p"
134.Fa "const BIGNUM *x"
135.Fa "const BIGNUM *y"
136.Fa "BN_CTX *ctx"
137.Fc
138.Ft int
139.Fo EC_POINT_get_affine_coordinates
140.Fa "const EC_GROUP *group"
141.Fa "const EC_POINT *p"
142.Fa "BIGNUM *x"
143.Fa "BIGNUM *y"
144.Fa "BN_CTX *ctx"
145.Fc
146.Ft int
147.Fo EC_POINT_get_affine_coordinates_GFp
148.Fa "const EC_GROUP *group"
149.Fa "const EC_POINT *p"
150.Fa "BIGNUM *x"
151.Fa "BIGNUM *y"
152.Fa "BN_CTX *ctx"
153.Fc
154.Ft int
155.Fo EC_POINT_get_affine_coordinates_GF2m
156.Fa "const EC_GROUP *group"
157.Fa "const EC_POINT *p"
158.Fa "BIGNUM *x"
159.Fa "BIGNUM *y"
160.Fa "BN_CTX *ctx"
161.Fc
162.Ft int
163.Fo EC_POINT_set_Jprojective_coordinates_GFp
164.Fa "const EC_GROUP *group"
165.Fa "EC_POINT *p"
166.Fa "const BIGNUM *x"
167.Fa "const BIGNUM *y"
168.Fa "const BIGNUM *z"
169.Fa "BN_CTX *ctx"
170.Fc
171.Ft int
172.Fo EC_POINT_get_Jprojective_coordinates_GFp
173.Fa "const EC_GROUP *group"
174.Fa "const EC_POINT *p"
175.Fa "BIGNUM *x"
176.Fa "BIGNUM *y"
177.Fa "BIGNUM *z"
178.Fa "BN_CTX *ctx"
179.Fc
180.Ft int
181.Fo EC_POINT_set_compressed_coordinates
182.Fa "const EC_GROUP *group"
183.Fa "EC_POINT *p"
184.Fa "const BIGNUM *x"
185.Fa "int y_bit"
186.Fa "BN_CTX *ctx"
187.Fc
188.Ft int
189.Fo EC_POINT_set_compressed_coordinates_GFp
190.Fa "const EC_GROUP *group"
191.Fa "EC_POINT *p"
192.Fa "const BIGNUM *x"
193.Fa "int y_bit"
194.Fa "BN_CTX *ctx"
195.Fc
196.Ft int
197.Fo EC_POINT_set_compressed_coordinates_GF2m
198.Fa "const EC_GROUP *group"
199.Fa "EC_POINT *p"
200.Fa "const BIGNUM *x"
201.Fa "int y_bit"
202.Fa "BN_CTX *ctx"
203.Fc
204.Ft size_t
205.Fo EC_POINT_point2oct
206.Fa "const EC_GROUP *group"
207.Fa "const EC_POINT *p"
208.Fa "point_conversion_form_t form"
209.Fa "unsigned char *buf"
210.Fa "size_t len"
211.Fa "BN_CTX *ctx"
212.Fc
213.Ft int
214.Fo EC_POINT_oct2point
215.Fa "const EC_GROUP *group"
216.Fa "EC_POINT *p"
217.Fa "const unsigned char *buf"
218.Fa "size_t len"
219.Fa "BN_CTX *ctx"
220.Fc
221.Ft BIGNUM *
222.Fo EC_POINT_point2bn
223.Fa "const EC_GROUP *"
224.Fa "const EC_POINT *"
225.Fa "point_conversion_form_t form"
226.Fa "BIGNUM *"
227.Fa "BN_CTX *"
228.Fc
229.Ft EC_POINT *
230.Fo EC_POINT_bn2point
231.Fa "const EC_GROUP *"
232.Fa "const BIGNUM *"
233.Fa "EC_POINT *"
234.Fa "BN_CTX *"
235.Fc
236.Ft char *
237.Fo EC_POINT_point2hex
238.Fa "const EC_GROUP *"
239.Fa "const EC_POINT *"
240.Fa "point_conversion_form_t form"
241.Fa "BN_CTX *"
242.Fc
243.Ft EC_POINT *
244.Fo EC_POINT_hex2point
245.Fa "const EC_GROUP *"
246.Fa "const char *"
247.Fa "EC_POINT *"
248.Fa "BN_CTX *"
249.Fc
250.Sh DESCRIPTION
251An
252.Vt EC_POINT
253represents a point on a curve.
254A curve is represented by an
255.Vt EC_GROUP
256object created by the functions described in
257.Xr EC_GROUP_new 3 .
258.Pp
259A new point is constructed by calling the function
260.Fn EC_POINT_new
261and providing the
262.Fa group
263object that the point relates to.
264.Pp
265.Fn EC_POINT_free
266frees the memory associated with the
267.Vt EC_POINT .
268If
269.Fa point
270is a
271.Dv NULL
272pointer, no action occurs.
273.Pp
274.Fn EC_POINT_clear_free
275destroys any sensitive data held within the
276.Vt EC_POINT
277and then frees its memory.
278If
279.Fa point
280is a
281.Dv NULL
282pointer, no action occurs.
283.Pp
284.Fn EC_POINT_copy
285copies the point
286.Fa src
287into
288.Fa dst .
289Both
290.Fa src
291and
292.Fa dst
293must use the same
294.Vt EC_METHOD .
295.Pp
296.Fn EC_POINT_dup
297creates a new
298.Vt EC_POINT
299object and copies the content from
300.Fa src
301to the newly created
302.Vt EC_POINT
303object.
304.Pp
305.Fn EC_POINT_method_of
306obtains the
307.Vt EC_METHOD
308associated with
309.Fa point .
310.Pp
311A valid point on a curve is the special point at infinity.
312A point is set to be at infinity by calling
313.Fn EC_POINT_set_to_infinity .
314.Pp
315The affine coordinates for a point describe a point in terms of its
316.Fa x
317and
318.Fa y
319position.
320The function
321.Fn EC_POINT_set_affine_coordinates
322sets the
323.Fa x
324and
325.Fa y
326coordinates for the point
327.Fa p
328defined over the curve given in
329.Fa group .
330The function
331.Fn EC_POINT_get_affine_coordinates
332sets
333.Fa x
334and
335.Fa y ,
336either of which may be
337.Dv NULL ,
338to the corresponding coordinates of
339.Fa p .
340.Pp
341The functions
342.Fn EC_POINT_set_affine_coordinates_GFp
343and
344.Fn EC_POINT_set_affine_coordinates_GF2m
345are deprecated synonyms for
346.Fn EC_POINT_set_affine_coordinates
347and the functions
348.Fn EC_POINT_get_affine_coordinates_GFp
349and
350.Fn EC_POINT_get_affine_coordinates_GF2m
351are deprecated synonyms for
352.Fn EC_POINT_get_affine_coordinates .
353.Pp
354As well as the affine coordinates, a point can alternatively be
355described in terms of its Jacobian projective coordinates (for Fp
356curves only).
357Jacobian projective coordinates are expressed as three values
358.Fa x ,
359.Fa y ,
360and
361.Fa z .
362Working in this coordinate system provides more efficient point
363multiplication operations.
364A mapping exists between Jacobian projective coordinates and affine
365coordinates.
366A Jacobian projective coordinate
367.Pq Fa x , y , z
368can be written as an affine coordinate as
369.Pp
370.Dl (x/(z^2), y/(z^3)) .
371.Pp
372Conversion to Jacobian projective from affine coordinates is simple.
373The coordinate
374.Pq Fa x , y
375is mapped to
376.Pq Fa x , y , No 1 .
377To set or get the projective coordinates use
378.Fn EC_POINT_set_Jprojective_coordinates_GFp
379and
380.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
381respectively.
382.Pp
383Points can also be described in terms of their compressed coordinates.
384For a point
385.Pq Fa x , y ,
386for any given value for
387.Fa x
388such that the point is on the curve, there will only ever be two
389possible values for
390.Fa y .
391Therefore, a point can be set using the
392.Fn EC_POINT_set_compressed_coordinates
393function where
394.Fa x
395is the x coordinate and
396.Fa y_bit
397is a value 0 or 1 to identify which of the two possible values for y
398should be used.
399.Pp
400The functions
401.Fn EC_POINT_set_compressed_coordinates_GFp
402and
403.Fn EC_POINT_set_compressed_coordinates_GF2m
404are deprecated synonyms for
405.Fn EC_POINT_set_compressed_coordinates .
406.Pp
407In addition
408.Vt EC_POINT Ns s
409can be converted to and from various external representations.
410Supported representations are octet strings,
411.Vt BIGNUM Ns s ,
412and hexadecimal.
413The format of the external representation is described by the
414point_conversion_form.
415See
416.Xr EC_GROUP_copy 3
417for a description of point_conversion_form.
418Octet strings are stored in a buffer along with an associated buffer
419length.
420A point held in a
421.Vt BIGNUM
422is calculated by converting the point to an octet string and then
423converting that octet string into a
424.Vt BIGNUM
425integer.
426Points in hexadecimal format are stored in a NUL terminated character
427string where each character is one of the printable values 0-9 or A-F
428(or a-f).
429.Pp
430The functions
431.Fn EC_POINT_point2oct ,
432.Fn EC_POINT_oct2point ,
433.Fn EC_POINT_point2bn ,
434.Fn EC_POINT_bn2point ,
435.Fn EC_POINT_point2hex ,
436and
437.Fn EC_POINT_hex2point
438convert from and to
439.Vt EC_POINT Ns s
440for the formats octet string,
441.Vt BIGNUM ,
442and hexadecimal, respectively.
443.Pp
444The function
445.Fn EC_POINT_point2oct
446must be supplied with a
447.Fa buf
448long enough to store the octet string.
449The return value provides the number of octets stored.
450Calling the function with a
451.Dv NULL
452.Fa buf
453will not perform the conversion but will still return the required
454buffer length.
455.Pp
456The function
457.Fn EC_POINT_point2hex
458will allocate sufficient memory to store the hexadecimal string.
459It is the caller's responsibility to free this memory with a subsequent
460call to
461.Xr free 3 .
462.Sh RETURN VALUES
463.Fn EC_POINT_new
464and
465.Fn EC_POINT_dup
466return the newly allocated
467.Vt EC_POINT
468or
469.Dv NULL
470on error.
471.Pp
472The following functions return 1 on success or 0 on error:
473.Fn EC_POINT_copy ,
474.Fn EC_POINT_set_to_infinity ,
475.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
476.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
477.Fn EC_POINT_set_affine_coordinates ,
478.Fn EC_POINT_set_affine_coordinates_GFp ,
479.Fn EC_POINT_set_affine_coordinates_GF2m ,
480.Fn EC_POINT_get_affine_coordinates ,
481.Fn EC_POINT_get_affine_coordinates_GFp ,
482.Fn EC_POINT_get_affine_coordinates_GF2m ,
483.Fn EC_POINT_set_compressed_coordinates ,
484.Fn EC_POINT_set_compressed_coordinates_GFp ,
485.Fn EC_POINT_set_compressed_coordinates_GF2m ,
486and
487.Fn EC_POINT_oct2point .
488.Pp
489.Fn EC_POINT_method_of
490returns the
491.Vt EC_METHOD
492associated with the supplied
493.Vt EC_POINT .
494.Pp
495.Fn EC_POINT_point2oct
496returns the length of the required buffer, or 0 on error.
497.Pp
498.Fn EC_POINT_point2bn
499returns the pointer to the
500.Vt BIGNUM
501supplied or
502.Dv NULL
503on error.
504.Pp
505.Fn EC_POINT_bn2point
506returns the pointer to the
507.Vt EC_POINT
508supplied or
509.Dv NULL
510on error.
511.Pp
512.Fn EC_POINT_point2hex
513returns a pointer to the hex string or
514.Dv NULL
515on error.
516.Pp
517.Fn EC_POINT_hex2point
518returns the pointer to the
519.Vt EC_POINT
520supplied or
521.Dv NULL
522on error.
523.Sh SEE ALSO
524.Xr d2i_ECPKParameters 3 ,
525.Xr EC_GFp_simple_method 3 ,
526.Xr EC_GROUP_copy 3 ,
527.Xr EC_GROUP_new 3 ,
528.Xr EC_KEY_new 3 ,
529.Xr EC_POINT_add 3 ,
530.Xr ECDH_compute_key 3
531.Sh HISTORY
532.Fn EC_POINT_new ,
533.Fn EC_POINT_free ,
534.Fn EC_POINT_clear_free ,
535.Fn EC_POINT_copy ,
536.Fn EC_POINT_method_of ,
537.Fn EC_POINT_set_to_infinity ,
538.Fn EC_POINT_set_affine_coordinates_GFp ,
539.Fn EC_POINT_get_affine_coordinates_GFp ,
540.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
541.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
542.Fn EC_POINT_set_compressed_coordinates_GFp ,
543.Fn EC_POINT_point2oct ,
544and
545.Fn EC_POINT_oct2point
546first appeared in OpenSSL 0.9.7 and have been available since
547.Ox 3.2 .
548.Pp
549.Fn EC_POINT_dup ,
550.Fn EC_POINT_set_affine_coordinates_GF2m ,
551.Fn EC_POINT_get_affine_coordinates_GF2m ,
552.Fn EC_POINT_set_compressed_coordinates_GF2m ,
553.Fn EC_POINT_point2bn ,
554.Fn EC_POINT_bn2point ,
555.Fn EC_POINT_point2hex ,
556and
557.Fn EC_POINT_hex2point
558first appeared in OpenSSL 0.9.8 and have been available since
559.Ox 4.5 .
560.Pp
561.Fn EC_POINT_set_affine_coordinates ,
562.Fn EC_POINT_get_affine_coordinates ,
563and
564.Fn EC_POINT_set_compressed_coordinates
565first appeared in OpenSSL 1.1.1 and have been available since
566.Ox 7.0 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 22:42:05 +0000