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.3409
1 files changed, 409 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3
new file mode 100644
index 0000000000..cd0dcaf986
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_POINT_new.3
@@ -0,0 +1,409 @@
1.Dd $Mdocdate: November 2 2016 $
2.Dt EC_POINT_NEW 3
3.Os
4.Sh NAME
5.Nm EC_POINT_new ,
6.Nm EC_POINT_free ,
7.Nm EC_POINT_clear_free ,
8.Nm EC_POINT_copy ,
9.Nm EC_POINT_dup ,
10.Nm EC_POINT_method_of ,
11.Nm EC_POINT_set_to_infinity ,
12.Nm EC_POINT_set_Jprojective_coordinates ,
13.Nm EC_POINT_get_Jprojective_coordinates_GFp ,
14.Nm EC_POINT_set_affine_coordinates_GFp ,
15.Nm EC_POINT_get_affine_coordinates_GFp ,
16.Nm EC_POINT_set_compressed_coordinates_GFp ,
17.Nm EC_POINT_set_affine_coordinates_GF2m ,
18.Nm EC_POINT_get_affine_coordinates_GF2m ,
19.Nm EC_POINT_set_compressed_coordinates_GF2m ,
20.Nm EC_POINT_point2oct ,
21.Nm EC_POINT_oct2point ,
22.Nm EC_POINT_point2bn ,
23.Nm EC_POINT_bn2point ,
24.Nm EC_POINT_point2hex ,
25.Nm EC_POINT_hex2point
26.Nd create, destroy, and manipulate EC_POINT objects
27.Sh SYNOPSIS
28.In openssl/ec.h
29.In openssl/bn.h
30.Ft EC_POINT *
31.Fo EC_POINT_new
32.Fa "const EC_GROUP *group"
33.Fc
34.Ft void
35.Fo EC_POINT_free
36.Fa "EC_POINT *point"
37.Fc
38.Ft void
39.Fo EC_POINT_clear_free
40.Fa "EC_POINT *point"
41.Fc
42.Ft int
43.Fo EC_POINT_copy
44.Fa "EC_POINT *dst"
45.Fa "const EC_POINT *src"
46.Fc
47.Ft EC_POINT *
48.Fo EC_POINT_dup
49.Fa "const EC_POINT *src"
50.Fa "const EC_GROUP *group"
51.Fc
52.Ft const EC_METHOD *
53.Fo EC_POINT_method_of
54.Fa "const EC_POINT *point"
55.Fc
56.Ft int
57.Fo EC_POINT_set_to_infinity
58.Fa "const EC_GROUP *group"
59.Fa "EC_POINT *point"
60.Fc
61.Ft int
62.Fo EC_POINT_set_Jprojective_coordinates_GFp
63.Fa "const EC_GROUP *group"
64.Fa "EC_POINT *p"
65.Fa "const BIGNUM *x"
66.Fa "const BIGNUM *y"
67.Fa "const BIGNUM *z"
68.Fa "BN_CTX *ctx"
69.Fc
70.Ft int
71.Fo EC_POINT_get_Jprojective_coordinates_GFp
72.Fa "const EC_GROUP *group"
73.Fa "const EC_POINT *p"
74.Fa "BIGNUM *x"
75.Fa "BIGNUM *y"
76.Fa "BIGNUM *z"
77.Fa "BN_CTX *ctx"
78.Fc
79.Ft int
80.Fo EC_POINT_set_affine_coordinates_GFp
81.Fa "const EC_GROUP *group"
82.Fa "EC_POINT *p"
83.Fa "const BIGNUM *x"
84.Fa "const BIGNUM *y"
85.Fa "BN_CTX *ctx"
86.Fc
87.Ft int
88.Fo EC_POINT_get_affine_coordinates_GFp
89.Fa "const EC_GROUP *group"
90.Fa "const EC_POINT *p"
91.Fa "BIGNUM *x"
92.Fa "BIGNUM *y"
93.Fa "BN_CTX *ctx"
94.Fc
95.Ft int
96.Fo EC_POINT_set_compressed_coordinates_GFp
97.Fa "const EC_GROUP *group"
98.Fa "EC_POINT *p"
99.Fa "const BIGNUM *x"
100.Fa "int y_bit"
101.Fa "BN_CTX *ctx"
102.Fc
103.Ft int
104.Fo EC_POINT_set_affine_coordinates_GF2m
105.Fa "const EC_GROUP *group"
106.Fa "EC_POINT *p"
107.Fa "const BIGNUM *x"
108.Fa "const BIGNUM *y"
109.Fa "BN_CTX *ctx"
110.Fc
111.Ft int
112.Fo EC_POINT_get_affine_coordinates_GF2m
113.Fa "const EC_GROUP *group"
114.Fa "const EC_POINT *p"
115.Fa "BIGNUM *x"
116.Fa "BIGNUM *y"
117.Fa "BN_CTX *ctx"
118.Fc
119.Ft int
120.Fo EC_POINT_set_compressed_coordinates_GF2m
121.Fa "const EC_GROUP *group"
122.Fa "EC_POINT *p"
123.Fa "const BIGNUM *x"
124.Fa "int y_bit"
125.Fa "BN_CTX *ctx"
126.Fc
127.Ft size_t
128.Fo EC_POINT_point2oct
129.Fa "const EC_GROUP *group"
130.Fa "const EC_POINT *p"
131.Fa "point_conversion_form_t form"
132.Fa "unsigned char *buf"
133.Fa "size_t len"
134.Fa "BN_CTX *ctx"
135.Fc
136.Ft int
137.Fo EC_POINT_oct2point
138.Fa "const EC_GROUP *group"
139.Fa "EC_POINT *p"
140.Fa "const unsigned char *buf"
141.Fa "size_t len"
142.Fa "BN_CTX *ctx"
143.Fc
144.Ft BIGNUM *
145.Fo EC_POINT_point2bn
146.Fa "const EC_GROUP *"
147.Fa "const EC_POINT *"
148.Fa "point_conversion_form_t form"
149.Fa "BIGNUM *"
150.Fa "BN_CTX *"
151.Fc
152.Ft EC_POINT *
153.Fo EC_POINT_bn2point
154.Fa "const EC_GROUP *"
155.Fa "const BIGNUM *"
156.Fa "EC_POINT *"
157.Fa "BN_CTX *"
158.Fc
159.Ft char *
160.Fo EC_POINT_point2hex
161.Fa "const EC_GROUP *"
162.Fa "const EC_POINT *"
163.Fa "point_conversion_form_t form"
164.Fa "BN_CTX *"
165.Fc
166.Ft EC_POINT *
167.Fo EC_POINT_hex2point
168.Fa "const EC_GROUP *"
169.Fa "const char *"
170.Fa "EC_POINT *"
171.Fa "BN_CTX *"
172.Fc
173.Sh DESCRIPTION
174An
175.Vt EC_POINT
176represents a point on a curve.
177A new point is constructed by calling the function
178.Fn EC_POINT_new
179and providing the
180.Fa group
181object that the point relates to.
182.Pp
183.Fn EC_POINT_free
184frees the memory associated with the
185.Vt EC_POINT .
186.Pp
187.Fn EC_POINT_clear_free
188destroys any sensitive data held within the
189.Vt EC_POINT
190and then frees its memory.
191.Pp
192.Fn EC_POINT_copy
193copies the point
194.Fa src
195into
196.Fa dst .
197Both
198.Fa src
199and
200.Fa dst
201must use the same
202.Vt EC_METHOD .
203.Pp
204.Fn EC_POINT_dup
205creates a new
206.Vt EC_POINT
207object and copies the content from
208.Fa src
209to the newly created
210.Vt EC_POINT
211object.
212.Pp
213.Fn EC_POINT_method_of
214obtains the
215.Vt EC_METHOD
216associated with
217.Fa point .
218.Pp
219A valid point on a curve is the special point at infinity.
220A point is set to be at infinity by calling
221.Fn EC_POINT_set_to_infinity .
222.Pp
223The affine coordinates for a point describe a point in terms of its
224.Fa x
225and
226.Fa y
227position.
228The functions
229.Fn EC_POINT_set_affine_coordinates_GFp
230and
231.Fn EC_POINT_set_affine_coordinates_GF2m
232set the
233.Fa x
234and
235.Fa y
236coordinates for the point
237.Fa p
238defined over the curve given in
239.Fa group .
240.Pp
241As well as the affine coordinates, a point can alternatively be
242described in terms of its Jacobian projective coordinates (for Fp
243curves only).
244Jacobian projective coordinates are expressed as three values
245.Fa x ,
246.Fa y ,
247and
248.Fa z .
249Working in this coordinate system provides more efficient point
250multiplication operations.
251A mapping exists between Jacobian projective coordinates and affine
252coordinates.
253A Jacobian projective coordinate
254.Pq Fa x , y , z
255can be written as an affine coordinate as
256.Pp
257.Dl (x/(z^2), y/(z^3)) .
258.Pp
259Conversion to Jacobian projective to affine coordinates is simple.
260The coordinate
261.Pq Fa x , y
262is mapped to
263.Pq Fa x , y , No 1 .
264To set or get the projective coordinates use
265.Fn EC_POINT_set_Jprojective_coordinates_GFp
266and
267.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
268respectively.
269.Pp
270Points can also be described in terms of their compressed coordinates.
271For a point
272.Pq Fa x , y ,
273for any given value for
274.Fa x
275such that the point is on the curve, there will only ever be two
276possible values for
277.Fa y .
278Therefore a point can be set using the
279.Fn EC_POINT_set_compressed_coordinates_GFp
280and
281.Fn EC_POINT_set_compressed_coordinates_GF2m
282functions where
283.Fa x
284is the x coordinate and
285.Fa y_bit
286is a value 0 or 1 to identify which of the two possible values for y
287should be used.
288.Pp
289In addition
290.Vt EC_POINT Ns s
291can be converted to and from various external representations.
292Supported representations are octet strings,
293.Vt BIGNUM Ns s ,
294and hexadecimal.
295The format of the external representation is described by the
296point_conversion_form.
297See
298.Xr EC_GROUP_copy 3
299for a description of point_conversion_form.
300Octet strings are stored in a buffer along with an associated buffer
301length.
302A point held in a
303.Vt BIGNUM
304is calculated by converting the point to an octet string and then
305converting that octet string into a
306.Vt BIGNUM
307integer.
308Points in hexadecimal format are stored in a NUL terminated character
309string where each character is one of the printable values 0-9 or A-F
310(or a-f).
311.Pp
312The functions
313.Fn EC_POINT_point2oct ,
314.Fn EC_POINT_oct2point ,
315.Fn EC_POINT_point2bn ,
316.Fn EC_POINT_bn2point ,
317.Fn EC_POINT_point2hex ,
318and
319.Fn EC_POINT_hex2point
320convert from and to
321.Vt EC_POINT Ns s
322for the formats octet string,
323.Vt BIGNUM ,
324and hexadecimal, respectively.
325.Pp
326The function
327.Fn EC_POINT_point2oct
328must be supplied with a
329.Fa buf
330long enough to store the octet string.
331The return value provides the number of octets stored.
332Calling the function with a
333.Dv NULL
334.Fa buf
335will not perform the conversion but will still return the required
336buffer length.
337.Pp
338The function
339.Fn EC_POINT_point2hex
340will allocate sufficient memory to store the hexadecimal string.
341It is the caller's responsibility to free this memory with a subsequent
342call to
343.Xr free 3 .
344.Sh RETURN VALUES
345.Fn EC_POINT_new
346and
347.Fn EC_POINT_dup
348return the newly allocated
349.Vt EC_POINT
350or
351.Dv NULL
352on error.
353.Pp
354The following functions return 1 on success or 0 on error:
355.Fn EC_POINT_copy ,
356.Fn EC_POINT_set_to_infinity ,
357.Fn EC_POINT_set_Jprojective_coordinates_GFp ,
358.Fn EC_POINT_get_Jprojective_coordinates_GFp ,
359.Fn EC_POINT_set_affine_coordinates_GFp ,
360.Fn EC_POINT_get_affine_coordinates_GFp ,
361.Fn EC_POINT_set_compressed_coordinates_GFp ,
362.Fn EC_POINT_set_affine_coordinates_GF2m ,
363.Fn EC_POINT_get_affine_coordinates_GF2m ,
364.Fn EC_POINT_set_compressed_coordinates_GF2m ,
365and
366.Fn EC_POINT_oct2point .
367.Pp
368.Fn EC_POINT_method_of
369returns the
370.Vt EC_METHOD
371associated with the supplied
372.Vt EC_POINT .
373.Pp
374.Fn EC_POINT_point2oct
375returns the length of the required buffer, or 0 on error.
376.Pp
377.Fn EC_POINT_point2bn
378returns the pointer to the
379.Vt BIGNUM
380supplied or
381.Vt NULL
382on error.
383.Pp
384.Fn EC_POINT_bn2point
385returns the pointer to the
386.Vt EC_POINT
387supplied or
388.Dv NULL
389on error.
390.Pp
391.Fn EC_POINT_point2hex
392returns a pointer to the hex string or
393.Dv NULL
394on error.
395.Pp
396.Fn EC_POINT_hex2point
397returns the pointer to the
398.Vt EC_POINT supplied or
399.Dv NULL
400on error.
401.Sh SEE ALSO
402.Xr crypto 3 ,
403.Xr d2i_ECPKParameters 3 ,
404.Xr ec 3 ,
405.Xr EC_GFp_simple_method 3 ,
406.Xr EC_GROUP_copy 3 ,
407.Xr EC_GROUP_new 3 ,
408.Xr EC_KEY_new 3 ,
409.Xr EC_POINT_add 3
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 23:50:48 +0000