summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authortb <>2025-04-25 19:57:12 +0000
committertb <>2025-04-25 19:57:12 +0000
commitcb56cb39e4330bac5b137be25dddcb89c34eee5e (patch)
tree861ff688d2e1eb96feb6980c81276954e5ebafe4 /src
parent120a986cb6f325a834aa58315f1c744f3d9c8165 (diff)
downloadopenbsd-cb56cb39e4330bac5b137be25dddcb89c34eee5e.tar.gz
openbsd-cb56cb39e4330bac5b137be25dddcb89c34eee5e.tar.bz2
openbsd-cb56cb39e4330bac5b137be25dddcb89c34eee5e.zip
Rework EC documentation
This replaces the giant, poor quality and outdated EC_GROUP_copy.3, EC_GROUP_new.3, and EC_POINT_new.3 manuals with seven new manuals written from scratch. * EC_GROUP_new_by_curve_name() is the entry point for builtin curves, * EC_GROUP_new_curve_GFp() describes lower level API that should not usually be needed apart from a handful of accessors. * EC_GROUP_check() contains two functions that applications should not need because either you know for certain something is an elliptic curve (so these checks are pointless) or you should not use it. * EC_GROUP_get_curve_name() describes some low level ASN.1 footguns and corresponding getters. * EC_POINT_new() contains the simple EC_POINT allocation and freeing API * EC_POINT_get_affine_coordinates() contains the coordinate accessors * EC_POINT_point2oct() is about encoding elliptic curve points While all this is quite far from perfect, the diff is getting too big and it will be easier to improve this in tree. It is definitely more repetitive than I would like it to be. Reviews, tweaks and general feedback are of course welcome. discussed with jsing
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_check.3157
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_copy.3492
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_get_curve_name.3264
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new.3353
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new_by_curve_name.3310
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3450
-rw-r--r--src/lib/libcrypto/man/EC_KEY_METHOD_new.313
-rw-r--r--src/lib/libcrypto/man/EC_KEY_new.321
-rw-r--r--src/lib/libcrypto/man/EC_POINT_add.318
-rw-r--r--src/lib/libcrypto/man/EC_POINT_get_affine_coordinates.3215
-rw-r--r--src/lib/libcrypto/man/EC_POINT_new.3506
-rw-r--r--src/lib/libcrypto/man/EC_POINT_point2oct.3431
-rw-r--r--src/lib/libcrypto/man/Makefile10
13 files changed, 1998 insertions, 1242 deletions
diff --git a/src/lib/libcrypto/man/EC_GROUP_check.3 b/src/lib/libcrypto/man/EC_GROUP_check.3
new file mode 100644
index 0000000000..e000be212b
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_check.3
@@ -0,0 +1,157 @@
1.\" $OpenBSD: EC_GROUP_check.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_GROUP_CHECK 3
19.Os
20.Sh NAME
21.Nm EC_GROUP_check_discriminant ,
22.Nm EC_GROUP_check
23.Nd partially check validity of
24.Vt EC_GROUP
25objects
26.Sh SYNOPSIS
27.In openssl/bn.h
28.In openssl/ec.h
29.Pp
30Deprecated:
31.Pp
32.Ft "int"
33.Fo EC_GROUP_check_discriminant
34.Fa "const EC_GROUP *group"
35.Fa "BN_CTX *ctx"
36.Fc
37.Ft "int"
38.Fo EC_GROUP_check
39.Fa "const EC_GROUP *group"
40.Fa "BN_CTX *ctx"
41.Fc
42.Sh DESCRIPTION
43These functions are deprecated.
44Only standardized curves built into the library should be used, see
45.Xr EC_GROUP_new_by_curve_name 3 .
46For builtin curves far more thorough checks than the minimal checks
47performed by these functions have been performed.
48.Pp
49These functions have an optional
50.Fa ctx
51argument which is used to avoid the cost of repeated allocation of
52auxiliary
53.Vt BIGNUM
54objects.
55.Pp
56.Fn EC_GROUP_check_discriminant
57can be called after
58.Xr EC_GROUP_new_curve_GFp 3
59to verify that
60.Fa group Ns 's
61parameters have non-zero discriminant 4a^3 + 27b^2 modulo p.
62Assuming that
63.Fa p
64is a prime number larger than three
65this implies that the Weierstrass equation defines an elliptic curve.
66.Pp
67.Fn EC_GROUP_check
68partially verifies that
69.Fa group
70represents an an elliptic curve and that
71.Fa generator
72is a point on the curve whose order divides
73.Fa order .
74It checks with
75.Fn EC_GROUP_check_discriminant
76that the discriminant is non-zero
77and then verifies that that
78.Fa order
79is non-zero and that the product
80.Fa generator No * Fa order
81is the point at infinity.
82This implies that
83.Fa order
84is an integer multiple of the
85.Fa generator Ns 's
86.Fa order .
87The verification that
88.Fa p
89is a prime
90and that
91.Fa order
92is the
93.Fa generator Ns 's
94order are skipped because they are too expensive.
95.Sh RETURN VALUES
96.Fn EC_GROUP_check_discriminant
97returns 1 on success and 0 on failure.
98Failure modes include that the discriminant is zero modulo
99.Fa p
100and memory allocation failure.
101.Pp
102.Fn EC_GROUP_check
103returns 1 on success and 0 on failure.
104.Sh ERRORS
105Diagnostics for
106.Fn EC_GROUP_check
107that can be retrieved with
108.Xr ERR_get_error 3 ,
109.Xr ERR_GET_REASON 3 ,
110and
111.Xr ERR_reason_error_string 3
112include:
113.Bl -tag -width Ds
114.It Dv EC_R_DISCRIMINANT_IS_ZERO Qq "discriminant is zero"
115.Fn EC_GROUP_check_discriminant
116failed because the discriminant is zero or for some other reason.
117.It Dv EC_R_UNDEFINED_GENERATOR Qq "undefined generator"
118no generator is set on
119.Fa group ,
120for example because a call to
121.Xr EC_GROUP_set_generator 3
122is missing.
123.It Dv EC_R_POINT_IS_NOT_ON_CURVE Qq "point is not on curve"
124a generator is set, but it is not a point on the curve represented by
125.Fa group .
126.It Dv EC_R_UNDEFINED_ORDER Qq "undefined order"
127the
128.Fa order
129set on
130.Fa group
131is zero.
132.It Dv EC_R_INVALID_GROUP_ORDER Qq "invalid group order"
133.Fa generator No * Fa order
134is not the point at infinity.
135.El
136.Sh SEE ALSO
137.Xr BN_CTX_new 3 ,
138.Xr BN_is_zero 3 ,
139.Xr crypto 3 ,
140.Xr d2i_ECPKParameters 3 ,
141.Xr EC_GROUP_get_curve_name 3 ,
142.Xr EC_GROUP_new_by_curve_name 3 ,
143.Xr EC_GROUP_new_curve_GFp 3 ,
144.Xr EC_KEY_METHOD_new 3 ,
145.Xr EC_KEY_new 3 ,
146.Xr EC_POINT_add 3 ,
147.Xr EC_POINT_get_affine_coordinates 3 ,
148.Xr EC_POINT_new 3 ,
149.Xr EC_POINT_point2oct 3 ,
150.Xr ECDH_compute_key 3 ,
151.Xr ECDSA_SIG_new 3
152.Sh HISTORY
153.Fn EC_GROUP_check
154and
155.Fn EC_GROUP_check_discriminant
156first appeared in OpenSSL 0.9.8 and have been available since
157.Ox 4.5 .
diff --git a/src/lib/libcrypto/man/EC_GROUP_copy.3 b/src/lib/libcrypto/man/EC_GROUP_copy.3
deleted file mode 100644
index 2e5e798236..0000000000
--- a/src/lib/libcrypto/man/EC_GROUP_copy.3
+++ /dev/null
@@ -1,492 +0,0 @@
1.\" $OpenBSD: EC_GROUP_copy.3,v 1.16 2025/03/08 16:40:59 tb Exp $
2.\" full merge up to: OpenSSL d900a015 Oct 8 14:40:42 2015 +0200
3.\" selective merge up to: OpenSSL 24c23e1f Aug 22 10:51:25 2019 +0530
4.\"
5.\" This file was written by Matt Caswell <matt@openssl.org>,
6.\" Dr. Stephen Henson <steve@openssl.org>,
7.\" and Jayaram X Matta <jayaramx.matta@intel.com>.
8.\" Copyright (c) 2013, 2015, 2019 The OpenSSL Project. All rights reserved.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\"
14.\" 1. Redistributions of source code must retain the above copyright
15.\" notice, this list of conditions and the following disclaimer.
16.\"
17.\" 2. Redistributions in binary form must reproduce the above copyright
18.\" notice, this list of conditions and the following disclaimer in
19.\" the documentation and/or other materials provided with the
20.\" distribution.
21.\"
22.\" 3. All advertising materials mentioning features or use of this
23.\" software must display the following acknowledgment:
24.\" "This product includes software developed by the OpenSSL Project
25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
26.\"
27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
28.\" endorse or promote products derived from this software without
29.\" prior written permission. For written permission, please contact
30.\" openssl-core@openssl.org.
31.\"
32.\" 5. Products derived from this software may not be called "OpenSSL"
33.\" nor may "OpenSSL" appear in their names without prior written
34.\" permission of the OpenSSL Project.
35.\"
36.\" 6. Redistributions of any form whatsoever must retain the following
37.\" acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
40.\"
41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
52.\" OF THE POSSIBILITY OF SUCH DAMAGE.
53.\"
54.Dd $Mdocdate: March 8 2025 $
55.Dt EC_GROUP_COPY 3
56.Os
57.Sh NAME
58.Nm EC_GROUP_copy ,
59.Nm EC_GROUP_dup ,
60.Nm EC_GROUP_set_generator ,
61.Nm EC_GROUP_get0_generator ,
62.Nm EC_GROUP_get_order ,
63.Nm EC_GROUP_order_bits ,
64.Nm EC_GROUP_get_cofactor ,
65.Nm EC_GROUP_set_curve_name ,
66.Nm EC_GROUP_get_curve_name ,
67.Nm EC_GROUP_set_asn1_flag ,
68.Nm EC_GROUP_get_asn1_flag ,
69.Nm EC_GROUP_set_point_conversion_form ,
70.Nm EC_GROUP_get_point_conversion_form ,
71.Nm EC_GROUP_get0_seed ,
72.Nm EC_GROUP_get_seed_len ,
73.Nm EC_GROUP_set_seed ,
74.Nm EC_GROUP_get_degree ,
75.Nm EC_GROUP_check ,
76.Nm EC_GROUP_check_discriminant ,
77.Nm EC_GROUP_cmp ,
78.Nm EC_GROUP_get_basis_type
79.Nd manipulate EC_GROUP objects
80.Sh SYNOPSIS
81.In openssl/ec.h
82.In openssl/bn.h
83.Ft int
84.Fo EC_GROUP_copy
85.Fa "EC_GROUP *dst"
86.Fa "const EC_GROUP *src"
87.Fc
88.Ft EC_GROUP *
89.Fo EC_GROUP_dup
90.Fa "const EC_GROUP *src"
91.Fc
92.Ft int
93.Fo EC_GROUP_set_generator
94.Fa "EC_GROUP *group"
95.Fa "const EC_POINT *generator"
96.Fa "const BIGNUM *order"
97.Fa "const BIGNUM *cofactor"
98.Fc
99.Ft const EC_POINT *
100.Fo EC_GROUP_get0_generator
101.Fa "const EC_GROUP *group"
102.Fc
103.Ft int
104.Fo EC_GROUP_get_order
105.Fa "const EC_GROUP *group"
106.Fa "BIGNUM *order"
107.Fa "BN_CTX *ctx"
108.Fc
109.Ft int
110.Fo EC_GROUP_order_bits
111.Fa "const EC_GROUP *group"
112.Fc
113.Ft int
114.Fo EC_GROUP_get_cofactor
115.Fa "const EC_GROUP *group"
116.Fa "BIGNUM *cofactor"
117.Fa "BN_CTX *ctx"
118.Fc
119.Ft void
120.Fo EC_GROUP_set_curve_name
121.Fa "EC_GROUP *group"
122.Fa "int nid"
123.Fc
124.Ft int
125.Fo EC_GROUP_get_curve_name
126.Fa "const EC_GROUP *group"
127.Fc
128.Ft void
129.Fo EC_GROUP_set_asn1_flag
130.Fa "EC_GROUP *group"
131.Fa "int flag"
132.Fc
133.Ft int
134.Fo EC_GROUP_get_asn1_flag
135.Fa "const EC_GROUP *group"
136.Fc
137.Ft void
138.Fo EC_GROUP_set_point_conversion_form
139.Fa "EC_GROUP *group"
140.Fa "point_conversion_form_t form"
141.Fc
142.Ft point_conversion_form_t
143.Fo EC_GROUP_get_point_conversion_form
144.Fa "const EC_GROUP *"
145.Fc
146.Ft unsigned char *
147.Fo EC_GROUP_get0_seed
148.Fa "const EC_GROUP *x"
149.Fc
150.Ft size_t
151.Fo EC_GROUP_get_seed_len
152.Fa "const EC_GROUP *"
153.Fc
154.Ft size_t
155.Fo EC_GROUP_set_seed
156.Fa "EC_GROUP *"
157.Fa "const unsigned char *"
158.Fa "size_t len"
159.Fc
160.Ft int
161.Fo EC_GROUP_get_degree
162.Fa "const EC_GROUP *group"
163.Fc
164.Ft int
165.Fo EC_GROUP_check
166.Fa "const EC_GROUP *group"
167.Fa "BN_CTX *ctx"
168.Fc
169.Ft int
170.Fo EC_GROUP_check_discriminant
171.Fa "const EC_GROUP *group"
172.Fa "BN_CTX *ctx"
173.Fc
174.Ft int
175.Fo EC_GROUP_cmp
176.Fa "const EC_GROUP *a"
177.Fa "const EC_GROUP *b"
178.Fa "BN_CTX *ctx"
179.Fc
180.Ft int
181.Fo EC_GROUP_get_basis_type
182.Fa "const EC_GROUP *"
183.Fc
184.Sh DESCRIPTION
185These functions operate on
186.Vt EC_GROUP
187objects created by the functions described in
188.Xr EC_GROUP_new 3 .
189.Pp
190.Fn EC_GROUP_copy
191copies the curve
192.Fa src
193into
194.Fa dst .
195Both
196.Fa src
197and
198.Fa dst
199must use the same
200.Vt EC_METHOD .
201.Pp
202.Fn EC_GROUP_dup
203creates a new
204.Vt EC_GROUP
205object and copies the content from
206.Fa src
207to the newly created
208.Vt EC_GROUP
209object.
210.Pp
211.Fn EC_GROUP_set_generator
212sets curve parameters that must be agreed by all participants using
213the curve.
214These parameters include the
215.Fa generator ,
216the
217.Fa order
218and the
219.Fa cofactor .
220The
221.Fa generator
222is a well defined point on the curve chosen for cryptographic
223operations.
224Integers used for point multiplications will be between 0 and
225.Fa order No - 1 .
226The
227.Fa order
228multiplied by the
229.Fa cofactor
230gives the number of points on the curve.
231.Pp
232.Fn EC_GROUP_get0_generator
233returns the generator for the identified
234.Fa group .
235.Pp
236.Fn EC_GROUP_get_order
237retrieves the order of the
238.Fa group
239and copies its value into
240.Fa order .
241It fails if the order of the
242.Fa group
243is not set or set to zero.
244.Pp
245.Fn EC_GROUP_get_cofactor
246retrieves the cofactor of the
247.Fa group
248and copies its value into
249.Fa cofactor .
250It fails if the cofactor of the
251.Fa group
252is not set or set to zero.
253.Pp
254The functions
255.Fn EC_GROUP_set_curve_name
256and
257.Fn EC_GROUP_get_curve_name
258set and get the NID for the curve, respectively (see
259.Xr EC_GROUP_new 3 ) .
260If a curve does not have a NID associated with it, then
261.Fn EC_GROUP_get_curve_name
262will return
263.Dv NID_undef .
264.Pp
265The asn1_flag value is used to determine whether the curve encoding
266uses explicit parameters or a named curve using an ASN.1 OID:
267many applications only support the latter form.
268If asn1_flag is the default value
269.Dv OPENSSL_EC_NAMED_CURVE ,
270then the named curve form is used and the parameters must have a
271corresponding named curve NID set.
272If asn1_flags is
273.Dv OPENSSL_EC_EXPLICIT_CURVE ,
274the parameters are explicitly encoded.
275The functions
276.Fn EC_GROUP_get_asn1_flag
277and
278.Fn EC_GROUP_set_asn1_flag
279get and set the status of the asn1_flag for the curve.
280.Pp
281The point_conversion_form for a curve controls how
282.Vt EC_POINT
283data is encoded as ASN.1 as defined in X9.62 (ECDSA).
284.Vt point_conversion_form_t
285is an enum defined as follows:
286.Bd -literal
287typedef enum {
288 /** the point is encoded as z||x, where the octet z specifies
289 * which solution of the quadratic equation y is */
290 POINT_CONVERSION_COMPRESSED = 2,
291 /** the point is encoded as z||x||y, where z is the octet 0x04 */
292 POINT_CONVERSION_UNCOMPRESSED = 4,
293 /** the point is encoded as z||x||y, where the octet z specifies
294 * which solution of the quadratic equation y is */
295 POINT_CONVERSION_HYBRID = 6
296} point_conversion_form_t;
297.Ed
298.Pp
299For
300.Dv POINT_CONVERSION_UNCOMPRESSED
301the point is encoded as an octet signifying the UNCOMPRESSED form
302has been used followed by the octets for x, followed by the octets
303for y.
304.Pp
305For any given x coordinate for a point on a curve it is possible to
306derive two possible y values.
307For
308.Dv POINT_CONVERSION_COMPRESSED
309the point is encoded as an octet signifying that the COMPRESSED
310form has been used AND which of the two possible solutions for y
311has been used, followed by the octets for x.
312.Pp
313For
314.Dv POINT_CONVERSION_HYBRID
315the point is encoded as an octet signifying the HYBRID form has
316been used AND which of the two possible solutions for y has been
317used, followed by the octets for x, followed by the octets for y.
318.Pp
319The functions
320.Fn EC_GROUP_set_point_conversion_form
321and
322.Fn EC_GROUP_get_point_conversion_form
323set and get the point_conversion_form for the curve, respectively.
324.Pp
325ANSI X9.62 (ECDSA standard) defines a method of generating the curve
326parameter b from a random number.
327This provides advantages in that a parameter obtained in this way is
328highly unlikely to be susceptible to special purpose attacks, or have
329any trapdoors in it.
330If the seed is present for a curve then the b parameter was generated in
331a verifiable fashion using that seed.
332The OpenSSL EC library does not use this seed value but does enable you
333to inspect it using
334.Fn EC_GROUP_get0_seed .
335This returns a pointer to a memory block containing the seed that was
336used.
337The length of the memory block can be obtained using
338.Fn EC_GROUP_get_seed_len .
339A number of the builtin curves within the library provide seed values
340that can be obtained.
341It is also possible to set a custom seed using
342.Fn EC_GROUP_set_seed
343and passing a pointer to a memory block, along with the length of
344the seed.
345Again, the EC library will not use this seed value, although it will be
346preserved in any ASN.1 based communications.
347.Pp
348.Fn EC_GROUP_get_degree
349gets the degree of the field.
350For Fp fields this will be the number of bits in p.
351For F2^m fields this will be the value m.
352.Pp
353The function
354.Fn EC_GROUP_check_discriminant
355calculates the discriminant for the curve and verifies that it is
356valid.
357For a curve defined over Fp the discriminant is given by the formula
3584*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b.
359In either case for the curve to be valid the discriminant must be
360non-zero.
361.Pp
362The function
363.Fn EC_GROUP_check
364performs a number of checks on a curve to verify that it is valid.
365Checks performed include verifying that the discriminant is non-zero;
366that a generator has been defined; that the generator is on the curve
367and has the correct order.
368.Pp
369.Fn EC_GROUP_cmp
370compares
371.Fa a
372and
373.Fa b
374to determine whether they represent the same curve or not.
375.Pp
376.Fn EC_GROUP_get_basis_type
377always returns 0 and is only provided for compatibility.
378.Sh RETURN VALUES
379The following functions return 1 on success or 0 on error:
380.Fn EC_GROUP_copy ,
381.Fn EC_GROUP_set_generator ,
382.Fn EC_GROUP_check ,
383and
384.Fn EC_GROUP_check_discriminant .
385.Pp
386.Fn EC_GROUP_dup
387returns a pointer to the duplicated curve or
388.Dv NULL
389on error.
390.Pp
391.Fn EC_GROUP_get0_generator
392returns the generator for the given curve or
393.Dv NULL
394on error.
395.Pp
396.Fn EC_GROUP_get_order
397returns 0 if the order is not set or set to zero for the
398.Fa group
399or if copying into
400.Fa order
401fails, or 1 otherwise.
402.Pp
403.Fn EC_GROUP_order_bits
404returns the number of bits in the group order.
405.Pp
406.Fn EC_GROUP_get_cofactor
407returns 0 if the cofactor is not set or set to zero for the
408.Fa group
409or if copying into
410.Fa cofactor
411fails, or 1 otherwise.
412.Pp
413.Fn EC_GROUP_get_curve_name
414returns the curve name (NID) for the
415.Fa group
416or
417.Dv NID_undef
418if no curve name is associated.
419.Pp
420.Fn EC_GROUP_get_asn1_flag
421returns the ASN.1 flag for the specified
422.Fa group .
423.Pp
424.Fn EC_GROUP_get_point_conversion_form
425returns the point_conversion_form for the
426.Fa group .
427.Pp
428.Fn EC_GROUP_get_degree
429returns the degree for the
430.Fa group
431or 0 if the operation is not supported
432by the underlying group implementation.
433.Pp
434.Fn EC_GROUP_get0_seed
435returns a pointer to the seed that was used to generate the parameter
436b, or
437.Dv NULL
438if the seed is not specified.
439.Fn EC_GROUP_get_seed_len
440returns the length of the seed or 0 if the seed is not specified.
441.Pp
442.Fn EC_GROUP_set_seed
443returns the length of the seed that has been set.
444If the supplied seed is
445.Dv NULL
446or the supplied seed length is 0, the return value will be 1.
447On error 0 is returned.
448.Pp
449.Fn EC_GROUP_cmp
450returns 0 if the curves are equal, 1 if they are not equal,
451or -1 on error.
452.Pp
453.Fn EC_GROUP_get_basis_type
454always returns 0.
455.Sh SEE ALSO
456.Xr d2i_ECPKParameters 3 ,
457.Xr EC_GROUP_new 3 ,
458.Xr EC_KEY_new 3 ,
459.Xr EC_POINT_add 3 ,
460.Xr EC_POINT_new 3
461.Sh HISTORY
462.Fn EC_GROUP_copy ,
463.Fn EC_GROUP_set_generator ,
464.Fn EC_GROUP_get0_generator ,
465.Fn EC_GROUP_get_order ,
466and
467.Fn EC_GROUP_get_cofactor
468first appeared in OpenSSL 0.9.7 and have been available since
469.Ox 3.2 .
470.Pp
471.Fn EC_GROUP_dup ,
472.Fn EC_GROUP_set_curve_name ,
473.Fn EC_GROUP_get_curve_name ,
474.Fn EC_GROUP_set_asn1_flag ,
475.Fn EC_GROUP_get_asn1_flag ,
476.Fn EC_GROUP_set_point_conversion_form ,
477.Fn EC_GROUP_get_point_conversion_form ,
478.Fn EC_GROUP_get0_seed ,
479.Fn EC_GROUP_get_seed_len ,
480.Fn EC_GROUP_set_seed ,
481.Fn EC_GROUP_get_degree ,
482.Fn EC_GROUP_check ,
483.Fn EC_GROUP_check_discriminant ,
484.Fn EC_GROUP_cmp ,
485and
486.Fn EC_GROUP_get_basis_type
487first appeared in OpenSSL 0.9.8 and have been available since
488.Ox 4.5 .
489.Pp
490.Fn EC_GROUP_order_bits
491first appeared in OpenSSL 1.1.0 and has been available since
492.Ox 7.0 .
diff --git a/src/lib/libcrypto/man/EC_GROUP_get_curve_name.3 b/src/lib/libcrypto/man/EC_GROUP_get_curve_name.3
new file mode 100644
index 0000000000..9a131fddfe
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_get_curve_name.3
@@ -0,0 +1,264 @@
1.\" $OpenBSD: EC_GROUP_get_curve_name.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_GROUP_GET_CURVE_NAME 3
19.Os
20.Sh NAME
21.Nm EC_GROUP_get_curve_name ,
22.Nm EC_GROUP_set_curve_name ,
23.Nm EC_GROUP_get_asn1_flag ,
24.Nm EC_GROUP_set_asn1_flag ,
25.Nm EC_GROUP_get0_seed ,
26.Nm EC_GROUP_get_seed_len ,
27.Nm EC_GROUP_set_seed ,
28.Nm EC_GROUP_get_point_conversion_form ,
29.Nm EC_GROUP_set_point_conversion_form ,
30.Nm EC_GROUP_get_basis_type
31.Nd configure and inspect details of the ASN.1 encoding of
32.Vt EC_GROUP
33and related objects
34.Sh SYNOPSIS
35.In openssl/ec.h
36.Ft int
37.Fo EC_GROUP_get_curve_name
38.Fa "const EC_GROUP *group"
39.Fc
40.Ft void
41.Fo EC_GROUP_set_curve_name
42.Fa "EC_GROUP *group"
43.Fa "int nid"
44.Fc
45.Ft int
46.Fo EC_GROUP_get_asn1_flag
47.Fa "const EC_GROUP *group"
48.Fc
49.Ft void
50.Fo EC_GROUP_set_asn1_flag
51.Fa "EC_GROUP *group"
52.Fa "int flag"
53.Fc
54.Ft "unsigned char *"
55.Fo EC_GROUP_get0_seed
56.Fa "const EC_GROUP *group"
57.Fc
58.Ft size_t
59.Fo EC_GROUP_get_seed_len
60.Fa "const EC_GROUP *group"
61.Fc
62.Ft size_t
63.Fo EC_GROUP_set_seed
64.Fa "EC_GROUP *group"
65.Fa "const unsigned char *seed"
66.Fa "size_t len"
67.Fc
68.Bd -literal
69typedef enum {
70 POINT_CONVERSION_COMPRESSED = 2,
71 POINT_CONVERSION_UNCOMPRESSED = 4,
72 POINT_CONVERSION_HYBRID = 6
73} point_conversion_form_t;
74
75.Ed
76.Ft point_conversion_form_t
77.Fo EC_GROUP_get_point_conversion_form
78.Fa "const EC_GROUP *group"
79.Fc
80.Fo void
81.Ft EC_GROUP_set_point_conversion_form
82.Fa "EC_GROUP *group"
83.Fa "point_conversion_form_t form"
84.Fc
85.Pp
86Deprecated:
87.Ft int
88.Fo EC_GROUP_get_basis_type
89.Fa "const EC_GROUP *group"
90.Fc
91.Sh DESCRIPTION
92The functions in this manual affect or allow the inspection of
93the details of the ASN.1 encoding produced by the
94.Xr i2d_ECPKParameters 3
95family of functions.
96Modern applications use named curves and uncompressed point encoding,
97which are the default for
98.Xr EC_GROUP_new_by_curve_name 3 .
99.Pp
100In this library, Elliptic curve parameters are either encoded as a
101.Em named curve ,
102using an ASN.1 Object Identifier (OID) to refer to
103standardized parameters that need to be built into the library,
104or using
105.Em explicit curve parameters
106where the field, the curve equation, the base point's coordinates
107and other data are encoded explicitly.
108The
109.Em implicitly CA
110variant is not supported.
111.Pp
112.Fn EC_GROUP_get_curve_name
113gets the Numerical Identifier (NID) representation of the
114ASN.1 Object Identifier used for the named curve encoding of
115.Fa group .
116.Fn EC_GROUP_set_curve_name
117sets it to
118.Fa nid .
119.Pp
120.Fn EC_GROUP_get_asn1_flag
121retrieves the value of the
122.Fa asn1_flag
123member of
124.Fa group .
125If the bit corresponding to
126.Dv OPENSSL_EC_NAMED_CURVE
127is set, named curve encoding is used for
128.Fa group ,
129otherwise explicit encoding is used.
130.Fn EC_GROUP_set_asn1_flag
131sets the
132.Fa asn1_flag
133member of group to
134.Fa flag ,
135which should be either
136.Dv OPENSSL_EC_NAMED_CURVE
137to use named curve encoding or
138.Dv OPENSSL_EC_EXPLICIT_CURVE
139to use explicit encoding.
140.Pp
141The ASN.1 encoding of explicit curve parameters includes
142an optional seed value for parameters generated verifiably at random.
143If a seed value is set on
144.Fa group ,
145.Fn EC_GROUP_get0_seed
146returns a pointer to the internal byte string whose length is returned by
147.Fn EC_GROUP_get_seed_len .
148.Pp
149.Fn EC_GROUP_set_seed
150first clears any seed and length already stored in
151.Fa group .
152If
153.Fa seed
154is not
155.Dv NULL
156and
157.Fa len
158is not zero, it stores a copy of them in
159.Fa group .
160The
161.Fa seed
162should be a random byte string of
163.Fa len
164at least 20 bytes.
165The seed can be unset by passing
166.Dv NULL
167as a
168.Fa seed
169and a
170.Fa len
171of zero.
172The library does not perform any computation or validation with this seed,
173it only includes it in its ASN.1 encoded parameters,
174whether it contains a sensible value or not.
175.Pp
176Points on an elliptic curve, such as the generator or a public key,
177can be encoded in compressed form, uncompressed form,
178or in a hybrid form encompassing both, see
179.Xr EC_POINT_point2oct 3 .
180.Fn EC_GROUP_get_point_conversion_form
181retrieves the encoding used for points on
182.Fa group
183and
184.Fn EC_GROUP_set_point_conversion_form
185sets it to
186.Fa form .
187.Pp
188The deprecated
189.Fn EC_GROUP_get_basis_type
190only makes sense for curves over binary fields.
191It is provided for compatibility only.
192.Sh RETURN VALUES
193.Fn EC_GROUP_get_curve_name
194returns the NID to be used for named curve encoding of
195.Fa group
196or
197.Dv NID_undef
198if no NID is set.
199.Pp
200.Fn EC_GROUP_get_asn1_flag
201returns the value most recently set by
202.Fn EC_GROUP_set_asn1_flag
203on
204.Fa group .
205.Pp
206.Fn EC_GROUP_get0_seed
207returns an internal pointer to the
208.Fa seed
209on
210.Fa group
211or
212.Dv NULL
213if none is set.
214.Pp
215.Fn EC_GROUP_get_seed_len
216returns the byte length of the seed set on
217.Fa group
218or zero if none is set.
219.Pp
220.Fn EC_GROUP_set_seed
221returns 0 on memory allocation failure.
222It returns
223.Fa len
224on success unless
225.Fa seed
226is
227.Dv NULL
228or
229.Fa len
230is zero, in which case it returns 1.
231.Pp
232.Fn EC_GROUP_get_point_conversion_form
233returns the point conversion form last set by
234.Fn EC_GROUP_set_point_conversion_form
235on
236.Fa group .
237.Pp
238.Fn EC_GROUP_get_basis_type
239always returns
240.Dv NID_undef .
241.Sh SEE ALSO
242.Xr crypto 3 ,
243.Xr d2i_ECPKParameters 3 ,
244.Xr EC_GROUP_check 3 ,
245.Xr EC_GROUP_new_by_curve_name 3 ,
246.Xr EC_GROUP_new_curve_GFp 3 ,
247.Xr EC_KEY_METHOD_new 3 ,
248.Xr EC_KEY_new 3 ,
249.Xr EC_POINT_add 3 ,
250.Xr EC_POINT_get_affine_coordinates 3 ,
251.Xr EC_POINT_new 3 ,
252.Xr EC_POINT_point2oct 3 ,
253.Xr ECDH_compute_key 3 ,
254.Xr ECDSA_SIG_new 3 ,
255.Xr OBJ_obj2nid 3
256.Sh HISTORY
257These functions first appeared in OpenSSL 0.9.8 and have been available since
258.Ox 4.5 .
259.Sh BUGS
260Most of the setters cannot report errors and none of them perform proper
261input validation and accept most of the values passed in.
262This can result in invalid or nonsensical ASN.1 encoding produced by
263.Xr i2d_ECPKParameters 3
264and related functions.
diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3
deleted file mode 100644
index 83e3e4c870..0000000000
--- a/src/lib/libcrypto/man/EC_GROUP_new.3
+++ /dev/null
@@ -1,353 +0,0 @@
1.\" $OpenBSD: EC_GROUP_new.3,v 1.18 2025/03/08 16:38:13 tb Exp $
2.\" OpenSSL 6328d367 Sat Jul 4 21:58:30 2020 +0200
3.\"
4.\" This file was written by Matt Caswell <matt@openssl.org>.
5.\" Copyright (c) 2013 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: March 8 2025 $
52.Dt EC_GROUP_NEW 3
53.Os
54.Sh NAME
55.Nm EC_GROUP_new ,
56.Nm EC_GROUP_free ,
57.Nm EC_GROUP_clear_free ,
58.Nm EC_GROUP_new_curve_GFp ,
59.Nm EC_GROUP_new_by_curve_name ,
60.Nm EC_GROUP_set_curve ,
61.Nm EC_GROUP_get_curve ,
62.Nm EC_GROUP_set_curve_GFp ,
63.Nm EC_GROUP_get_curve_GFp ,
64.Nm EC_get_builtin_curves ,
65.Nm EC_curve_nid2nist ,
66.Nm EC_curve_nist2nid
67.Nd create and destroy EC_GROUP objects
68.Sh SYNOPSIS
69.In openssl/ec.h
70.In openssl/bn.h
71.Ft EC_GROUP *
72.Fo EC_GROUP_new
73.Fa "const EC_METHOD *meth"
74.Fc
75.Ft void
76.Fo EC_GROUP_free
77.Fa "EC_GROUP *group"
78.Fc
79.Ft void
80.Fo EC_GROUP_clear_free
81.Fa "EC_GROUP *group"
82.Fc
83.Ft EC_GROUP *
84.Fo EC_GROUP_new_curve_GFp
85.Fa "const BIGNUM *p"
86.Fa "const BIGNUM *a"
87.Fa "const BIGNUM *b"
88.Fa "BN_CTX *ctx"
89.Fc
90.Ft EC_GROUP *
91.Fo EC_GROUP_new_by_curve_name
92.Fa "int nid"
93.Fc
94.Ft int
95.Fo EC_GROUP_set_curve
96.Fa "EC_GROUP *group"
97.Fa "const BIGNUM *p"
98.Fa "const BIGNUM *a"
99.Fa "const BIGNUM *b"
100.Fa "BN_CTX *ctx"
101.Fc
102.Ft int
103.Fo EC_GROUP_get_curve
104.Fa "const EC_GROUP *group"
105.Fa "BIGNUM *p"
106.Fa "BIGNUM *a"
107.Fa "BIGNUM *b"
108.Fa "BN_CTX *ctx"
109.Fc
110.Ft int
111.Fo EC_GROUP_set_curve_GFp
112.Fa "EC_GROUP *group"
113.Fa "const BIGNUM *p"
114.Fa "const BIGNUM *a"
115.Fa "const BIGNUM *b"
116.Fa "BN_CTX *ctx"
117.Fc
118.Ft int
119.Fo EC_GROUP_get_curve_GFp
120.Fa "const EC_GROUP *group"
121.Fa "BIGNUM *p"
122.Fa "BIGNUM *a"
123.Fa "BIGNUM *b"
124.Fa "BN_CTX *ctx"
125.Fc
126.Ft size_t
127.Fo EC_get_builtin_curves
128.Fa "EC_builtin_curve *r"
129.Fa "size_t nitems"
130.Fc
131.Ft "const char *"
132.Fo EC_curve_nid2nist
133.Fa "int nid"
134.Fc
135.Ft int
136.Fo EC_curve_nist2nid
137.Fa "const char *name"
138.Fc
139.Sh DESCRIPTION
140The EC library provides functions for performing operations on
141elliptic curves in Weierstrass form.
142Such curves are defined over the prime field of order
143.Fa p
144and satisfy the Weierstrass equation with coefficients
145.Fa a
146and
147.Fa b
148.Pp
149.Dl y^2 = x^3 + ax + b
150.Pp
151An
152.Vt EC_GROUP
153structure is used to represent the definition of an elliptic curve.
154A new curve can be constructed by calling
155.Fn EC_GROUP_new ,
156using the implementation provided by
157.Fa meth .
158It is then necessary to call
159.Fn EC_GROUP_set_curve
160to set the curve parameters.
161.Pp
162.Fn EC_GROUP_set_curve
163sets the curve parameters
164.Fa p ,
165.Fa a ,
166and
167.Fa b ,
168where
169.Fa a
170and
171.Fa b
172represent the coefficients of the curve equation.
173.Pp
174.Fn EC_GROUP_set_curve_GFp
175is a deprecated synonym for
176.Fn EC_GROUP_set_curve .
177.Pp
178.Fn EC_GROUP_get_curve
179obtains the previously set curve parameters.
180.Pp
181.Fn EC_GROUP_get_curve_GFp
182is a deprecated synonym for
183.Fn EC_GROUP_get_curve .
184.Pp
185The function
186.Fn EC_GROUP_new_curve_GFp
187is a shortcut for calling
188.Fn EC_GROUP_new
189and
190.Fn EC_GROUP_set_curve .
191An appropriate default implementation method will be used.
192.Pp
193Whilst the library can be used to create any curve using the functions
194described above, there are also a number of predefined curves that are
195available.
196In order to obtain a list of all of the predefined curves, call the
197function
198.Fn EC_get_builtin_curves .
199The parameter
200.Fa r
201should be an array of
202.Vt EC_builtin_cure
203structures of size
204.Fa nitems .
205The function will populate the
206.Fa r
207array with information about the builtin curves.
208If
209.Fa nitems
210is less than the total number of curves available, then the first
211.Fa nitems
212curves will be returned.
213Otherwise the total number of curves will be provided.
214The return value is the total number of curves available (whether that
215number has been populated in
216.Fa r
217or not).
218Passing a
219.Dv NULL
220.Fa r ,
221or setting
222.Fa nitems
223to 0, will do nothing other than return the total number of curves
224available.
225The
226.Vt EC_builtin_curve
227structure is defined as follows:
228.Bd -literal
229typedef struct {
230 int nid;
231 const char *comment;
232} EC_builtin_curve;
233.Ed
234.Pp
235Each
236.Vt EC_builtin_curve
237item has a unique integer ID
238.Pq Fa nid
239and a human readable comment string describing the curve.
240.Pp
241In order to construct a builtin curve, use the function
242.Fn EC_GROUP_new_by_curve_name
243and provide the
244.Fa nid
245of the curve to be constructed.
246.Pp
247.Fn EC_GROUP_free
248frees the memory associated with the
249.Vt EC_GROUP .
250If
251.Fa group
252is a
253.Dv NULL
254pointer, no action occurs.
255.Pp
256.Fn EC_GROUP_clear_free
257destroys any sensitive data held within the
258.Vt EC_GROUP
259and then frees its memory.
260If
261.Fa group
262is a
263.Dv NULL
264pointer, no action occurs.
265.Pp
266Some builtin curves can be identified by their NIST name
267in addition to a numerical identifier (NID).
268.Fn EC_curve_nid2nist
269and
270.Fn EC_curve_nist2nid
271translate between the two.
272The five built-in prime curves are:
273.Pp
274.Bl -column "NIST name" NID_X9_62_prime256v1 "deprecated in SP800-186" -compact
275.It No NIST Fa name Ta Em ASN.1 NID Ta Em notes
276.It Qq P-192 Ta Dv NID_X9_62_prime192v1 Ta No deprecated in SP800-186
277.It Qq P-224 Ta Dv NID_secp224r1 Ta
278.It Qq P-256 Ta Dv NID_X9_62_prime256v1 Ta
279.It Qq P-384 Ta Dv NID_secp384r1 Ta
280.It Qq P-521 Ta Dv NID_secp521r1 Ta
281.El
282.Pp
283.Fn EC_curve_nid2nist
284and
285.Fn EC_curve_nist2nid
286also accept the ten binary curves defined in FIPS\& 186-4
287and deprecated in SP800-186,
288although they no longer correspond to builtin curves in LibreSSL.
289.Sh RETURN VALUES
290All
291.Fn EC_GROUP_new*
292functions return a pointer to the newly constructed group or
293.Dv NULL
294on error.
295.Pp
296.Fn EC_get_builtin_curves
297returns the number of builtin curves that are available.
298.Pp
299.Fn EC_curve_nid2nist
300returns a string constant containing the NIST name if
301.Fa nid
302identifies a NIST curve or
303.Dv NULL
304otherwise.
305.Pp
306.Fn EC_curve_nist2nid
307returns the NID corresponding to the NIST curve
308.Fa name ,
309or
310.Dv NID_undef .
311.Pp
312.Fn EC_GROUP_set_curve ,
313.Fn EC_GROUP_get_curve ,
314.Fn EC_GROUP_set_curve_GFp ,
315and
316.Fn EC_GROUP_get_curve_GFp
317return 1 on success or 0 on error.
318.Sh SEE ALSO
319.Xr crypto 3 ,
320.Xr d2i_ECPKParameters 3 ,
321.Xr EC_GROUP_copy 3 ,
322.Xr EC_KEY_new 3 ,
323.Xr EC_POINT_add 3 ,
324.Xr EC_POINT_new 3 ,
325.Xr ECDH_compute_key 3 ,
326.Xr ECDSA_SIG_new 3
327.Sh HISTORY
328.Fn EC_GROUP_new ,
329.Fn EC_GROUP_free ,
330.Fn EC_GROUP_clear_free ,
331.Fn EC_GROUP_new_curve_GFp ,
332.Fn EC_GROUP_set_curve_GFp ,
333and
334.Fn EC_GROUP_get_curve_GFp
335first appeared in OpenSSL 0.9.7 and have been available since
336.Ox 3.2 .
337.Pp
338.Fn EC_GROUP_new_by_curve_name
339and
340.Fn EC_get_builtin_curves
341first appeared in OpenSSL 0.9.8 and have been available since
342.Ox 4.5 .
343.Fn EC_curve_nid2nist ,
344and
345.Fn EC_curve_nist2nid
346first appeared in OpenSSL 1.1.0 and have been available since
347.Ox 5.8 .
348.Pp
349.Fn EC_GROUP_set_curve
350and
351.Fn EC_GROUP_get_curve
352first appeared in OpenSSL 1.1.1 and have been available since
353.Ox 7.0 .
diff --git a/src/lib/libcrypto/man/EC_GROUP_new_by_curve_name.3 b/src/lib/libcrypto/man/EC_GROUP_new_by_curve_name.3
new file mode 100644
index 0000000000..128b30eda5
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_new_by_curve_name.3
@@ -0,0 +1,310 @@
1.\" $OpenBSD: EC_GROUP_new_by_curve_name.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2024, 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_GROUP_NEW_BY_CURVE_NAME 3
19.Os
20.Sh NAME
21.Nm EC_GROUP_new_by_curve_name ,
22.Nm EC_GROUP_free ,
23.Nm EC_GROUP_dup ,
24.Nm EC_GROUP_cmp ,
25.Nm EC_get_builtin_curves ,
26.Nm EC_curve_nid2nist ,
27.Nm EC_curve_nist2nid
28.Nd instantiate named curves built into libcrypto
29.Sh SYNOPSIS
30.In openssl/bn.h
31.In openssl/ec.h
32.In openssl/objects.h
33.Ft "EC_GROUP *"
34.Fo EC_GROUP_new_by_curve_name
35.Fa "int nid"
36.Fc
37.Ft void
38.Fo EC_GROUP_free
39.Fa "EC_GROUP *group"
40.Fc
41.Ft EC_GROUP *
42.Fo EC_GROUP_dup
43.Fa "const EC_GROUP *group"
44.Fc
45.Ft int
46.Fo EC_GROUP_cmp
47.Fa "const EC_GROUP *group1"
48.Fa "const EC_GROUP *group2"
49.Fa "BN_CTX *ctx"
50.Fc
51.Bd -literal
52typedef struct {
53 int nid;
54 const char *comment;
55} EC_builtin_curve;
56
57.Ed
58.Ft size_t
59.Fo EC_get_builtin_curves
60.Fa "EC_builtin_curve *curves"
61.Fa "size_t ncurves"
62.Fc
63.Ft int
64.Fo EC_curve_nist2nid
65.Fa "const char *name"
66.Fc
67.Ft "const char *"
68.Fo EC_curve_nid2nist
69.Fa "int nid"
70.Fc
71.Sh DESCRIPTION
72Most elliptic curves used in cryptographic protocols have a
73standardized representation as a
74.Em named curve ,
75where an ASN.1 Object Identifier (OID) is used instead of
76detailed domain parameters.
77This OID is represented internally by a Numerical Identifier (NID),
78and the parameters themselves must be built into the library.
79In the EC library the
80.Em curve name
81refers to this NID.
82.Pp
83.Fn EC_GROUP_new_by_curve_name
84returns a new
85.Vt EC_GROUP
86object representing the named curve corresponding to
87.Fa nid ,
88using the parameters built into the library.
89It is equivalent to passing the appropriate parameters to
90.Xr EC_GROUP_new_curve_GFp 3 ,
91.Xr EC_GROUP_set_curve_name 3 ,
92.Xr EC_GROUP_set_generator 3
93and
94.Xr EC_GROUP_set_seed 3 .
95.Pp
96.Fn EC_GROUP_free
97frees
98.Fa group
99and all the memory associated with it.
100If
101.Fa group
102is
103.Dv NULL ,
104no action occurs.
105.Pp
106.Fn EC_GROUP_dup
107creates a deep copy of
108.Fa group .
109.Pp
110.Fn EC_GROUP_cmp
111is intended to determine whether
112.Fa group1
113and
114.Fa group2
115represent the same elliptic curve,
116making use of the optional
117.Fa ctx .
118If the curve name is set on both curves, they are compared as integers,
119then the prime field,
120the coefficients of the Weierstrass equation,
121the generators, their order and their cofactors are compared
122using
123.Xr BN_cmp 3
124or
125.Xr EC_POINT_cmp 3 ,
126respectively.
127.Pp
128.Fn EC_get_builtin_curves
129returns the number of builtin curves.
130If
131.Fa curves
132is
133.Dv NULL
134or
135.Fa ncurves
136is zero, it performs no other action.
137Otherwise, after reducing
138.Fa ncurves
139to the number of builtin curves if necessary,
140it copies the
141.Fa nid
142and a pointer to the
143.Fa comment
144of the first
145.Fa ncurves
146built-in curves to the array of
147.Vt EC_builtin_curve
148objects pointed to by
149.Fa curves
150and leaves the remainder of the array uninitialized.
151.Pp
152Some curves can be identified by their NIST name
153in addition to the numerical identifier (NID).
154.Fn EC_curve_nist2nid
155and
156.Fn EC_curve_nid2nist
157translate between the two.
158The builtin NIST curves over a prime field are:
159.Pp
160.Bl -column "NIST name" NID_X9_62_prime256v1 "deprecated in SP800-186" -compact
161.It No NIST Fa name Ta Em ASN.1 NID Ta Em notes
162.It Qq P-224 Ta Dv NID_secp224r1 Ta
163.It Qq P-256 Ta Dv NID_X9_62_prime256v1 Ta also known as secp256r1
164.It Qq P-384 Ta Dv NID_secp384r1 Ta
165.It Qq P-521 Ta Dv NID_secp521r1 Ta
166.El
167.Pp
168.Fn EC_curve_nist2nid
169and
170.Fn EC_curve_nid2nist
171also accept the binary curves defined in FIPS\& 186-4
172and deprecated in SP800-186,
173as well as
174.Qq P-192
175and
176.Dv NID_X9_62_prime192v1 ,
177although all these no longer correspond to builtin curves in LibreSSL.
178.Sh RETURN VALUES
179.Fn EC_GROUP_new_by_curve_name
180returns a newly allocated group or
181.Dv NULL
182if there is no built-in group with NID
183.Fa nid ,
184or if memory allocation fails.
185.Pp
186.Fn EC_GROUP_dup
187returns a newly allocated group or
188.Dv NULL
189if memory allocation fails.
190.Pp
191.Fn EC_GROUP_cmp
192returns 1 if the groups are distinct, 0 if the groups are
193considered identical and \-1 on memory allocation error.
194.Pp
195.Fn EC_get_builtin_curves
196returns the number of builtin curves.
197.Pp
198.Fn EC_curve_nid2nist
199returns a string constant containing the NIST name if
200.Fa nid
201identifies a NIST curve or
202.Dv NULL
203otherwise.
204.Pp
205.Fn EC_curve_nist2nid
206returns the NID corresponding to the NIST curve
207.Fa name ,
208or
209.Dv NID_undef .
210.Sh EXAMPLES
211Print the list of builtin curves, their NIDs, their NIST name and
212a comment describing each curve:
213.Bd -literal
214#include <err.h>
215#include <stdio.h>
216#include <stdlib.h>
217#include <unistd.h>
218
219#include <openssl/ec.h>
220
221int
222main(void)
223{
224 EC_builtin_curve *curves;
225 size_t ncurves, i;
226
227 if (pledge("stdio", NULL) == -1)
228 err(1, "pledge");
229
230 ncurves = EC_get_builtin_curves(NULL, 0);
231 if ((curves = calloc(ncurves, sizeof(*curves))) == NULL)
232 err(1, NULL);
233 (void)EC_get_builtin_curves(curves, ncurves);
234
235 printf("curve\etnid\etNIST\etcomment\en");
236 for (i = 0; i < ncurves; i++) {
237 const char *nist_name = EC_curve_nid2nist(curves[i].nid);
238
239 printf("%2zu\et%d\et%s\et%s\en", i, curves[i].nid,
240 nist_name != NULL ? nist_name : "", curves[i].comment);
241 }
242
243 free(curves);
244
245 return 0;
246}
247.Ed
248.Sh SEE ALSO
249.Xr crypto 3 ,
250.Xr d2i_ECPKParameters 3 ,
251.Xr EC_GROUP_check 3 ,
252.Xr EC_GROUP_get_curve_name 3 ,
253.Xr EC_GROUP_new_curve_GFp 3 ,
254.Xr EC_KEY_METHOD_new 3 ,
255.Xr EC_KEY_new 3 ,
256.Xr EC_POINT_add 3 ,
257.Xr EC_POINT_get_affine_coordinates 3 ,
258.Xr EC_POINT_new 3 ,
259.Xr EC_POINT_point2oct 3 ,
260.Xr ECDH_compute_key 3 ,
261.Xr ECDSA_SIG_new 3 ,
262.Xr OBJ_nid2obj 3
263.Sh STANDARDS
264.Rs
265.%T SEC 1: Elliptic Curve Cryptography, Version 2.0
266.%U https://www.secg.org/sec1-v2.pdf
267.%D May 21, 2009
268.Re
269.Pp
270.Rs
271.%T SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0
272.%U https://www.secg.org/sec2-v2.pdf
273.%D Jan 27, 2010
274.Re
275.Sh HISTORY
276.Fn EC_GROUP_free
277first appeared in OpenSSL 0.9.7 and has been available since
278.Ox 3.2 .
279.Pp
280.Fn EC_GROUP_new_by_curve_name ,
281.Fn EC_GROUP_cmp ,
282.Fn EC_GROUP_dup ,
283and
284.Fn EC_get_builtin_curves
285first appeared in OpenSSL 0.9.8 and have been available since
286.Ox 4.5 .
287.Pp
288.Fn EC_curve_nid2nist
289and
290.Fn EC_curve_nist2nid
291first appeared in OpenSSL 1.1.0 and have been available since
292.Ox 5.8 .
293.Sh BUGS
294.Fn EC_GROUP_cmp
295compares the coefficients of the Weierstrass equation as
296integers, not as elements of the prime field.
297It also treats the generator as mandatory while it is generally
298optional in the EC library.
299Aspects of the ASN.1 encoding controlled by the functions in
300.Xr EC_GROUP_get_asn1_flag 3 ,
301in particular seed, ASN.1 flag, and point conversion form,
302are ignored in the comparison.
303Group objects may therefore compare as equal and produce
304completely different ASN.1 encodings via
305.Xr i2d_ECPKParameters 3
306and related functions.
307In fact, either of these encodings might be valid or not,
308accepted or rejected by
309.Xr d2i_ECPKParameters 3 ,
310or the encoding might fail on one or both of the group objects.
diff --git a/src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3 b/src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3
new file mode 100644
index 0000000000..f13c969c28
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3
@@ -0,0 +1,450 @@
1.\" $OpenBSD: EC_GROUP_new_curve_GFp.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_GROUP_NEW_CURVE_GFP 3
19.Os
20.Sh NAME
21.Nm EC_GROUP_new_curve_GFp ,
22.Nm EC_GROUP_set_curve ,
23.Nm EC_GROUP_get_curve ,
24.Nm EC_GROUP_set_generator ,
25.Nm EC_GROUP_get0_generator ,
26.Nm EC_GROUP_get_degree ,
27.Nm EC_GROUP_get_order ,
28.Nm EC_GROUP_order_bits ,
29.Nm EC_GROUP_get_cofactor ,
30.Nm EC_GROUP_clear_free ,
31.Nm EC_GROUP_set_curve_GFp ,
32.Nm EC_GROUP_get_curve_GFp
33.Nd define elliptic curves and retrieve information from them
34.Sh SYNOPSIS
35.In openssl/bn.h
36.In openssl/ec.h
37.Ft "EC_GROUP *"
38.Fo EC_GROUP_new_curve_GFp
39.Fa "const BIGNUM *p"
40.Fa "const BIGNUM *a"
41.Fa "const BIGNUM *b"
42.Fa "BN_CTX *ctx"
43.Fc
44.Ft int
45.Fo EC_GROUP_set_curve
46.Fa "EC_GROUP *group"
47.Fa "const BIGNUM *p"
48.Fa "const BIGNUM *a"
49.Fa "const BIGNUM *b"
50.Fa "BN_CTX *ctx"
51.Fc
52.Ft int
53.Fo EC_GROUP_get_curve
54.Fa "const EC_GROUP *group"
55.Fa "BIGNUM *p"
56.Fa "BIGNUM *a"
57.Fa "BIGNUM *b"
58.Fa "BN_CTX *ctx"
59.Fc
60.Ft int
61.Fo EC_GROUP_set_generator
62.Fa "EC_GROUP *group"
63.Fa "const EC_POINT *generator"
64.Fa "const BIGNUM *order"
65.Fa "const BIGNUM *cofactor"
66.Fc
67.Ft "const EC_POINT *"
68.Fo EC_GROUP_get0_generator
69.Fa "const EC_GROUP *group"
70.Fc
71.Ft int
72.Fo EC_GROUP_get_degree
73.Fa "const EC_GROUP *"
74.Fc
75.Ft int
76.Fo EC_GROUP_get_order
77.Fa "const EC_GROUP *group"
78.Fa "BIGNUM *order"
79.Fa "BN_CTX *ctx"
80.Fc
81.Ft int
82.Fo EC_GROUP_order_bits
83.Fa "const EC_GROUP *group"
84.Fc
85.Ft int
86.Fo EC_GROUP_get_cofactor
87.Fa "const EC_GROUP *group"
88.Fa "BIGNUM *cofactor"
89.Fa "BN_CTX *ctx"
90.Fc
91.Pp
92Deprecated:
93.Pp
94.Ft void
95.Fo EC_GROUP_clear_free
96.Fa "EC_GROUP *group"
97.Fc
98.Ft int
99.Fo EC_GROUP_set_curve_GFp
100.Fa "EC_GROUP *group"
101.Fa "const BIGNUM *p"
102.Fa "const BIGNUM *a"
103.Fa "const BIGNUM *b"
104.Fa "BN_CTX *ctx"
105.Fc
106.Ft int
107.Fo EC_GROUP_get_curve_GFp
108.Fa "const EC_GROUP *group"
109.Fa "BIGNUM *p"
110.Fa "BIGNUM *a"
111.Fa "BIGNUM *b"
112.Fa "BN_CTX *ctx"
113.Fc
114.Sh DESCRIPTION
115With the exception of the getters
116the functions in this manual should not be used.
117Use
118.Xr EC_GROUP_new_by_curve_name 3
119instead.
120.Pp
121The EC library uses
122.Vt EC_GROUP
123objects to represent
124elliptic curves in Weierstrass form.
125These curves are defined over the prime field of order
126.Fa p
127via the Weierstrass equation
128.Dl y^2 = x^3 + ax + b
129where
130.Fa a
131and
132.Fa b
133are such that the discriminant 4a^3 - 27b^2 is non-zero.
134.Pp
135The points on an elliptic curve form a group.
136Cryptographic applications usually depend on the choice of a
137.Fa generator
138whose multiples form a cyclic subgroup of a certain
139.Fa order .
140By Lagrange's theorem, the number of points on the elliptic curve is
141the product of
142.Fa order
143and another integer called the
144.Fa cofactor .
145Hasse's theorem is the inequality
146.Dl | Ns Fa order No * Fa cofactor No - (p + 1)| <= 2 sqrt(p)
147which implies an upper bound on
148.Fa order
149in terms of
150.Fa p
151and allows the computation of
152.Fa cofactor
153provided that
154.Fa order
155is large enough.
156.Pp
157.Fn EC_GROUP_new_curve_GFp
158instantiates a new
159.Vt EC_GROUP
160object over the prime field of size
161.Fa p
162with Weierstrass equation given by the coefficients
163.Fa a
164and
165.Fa b .
166The optional
167.Fa ctx
168is used to transform the other arguments into internal representation.
169It is the caller's responsibility to ensure that
170.Fa p
171is a prime number greater than three and that
172the discriminant is non-zero.
173This can be done with
174.Xr EC_GROUP_check_discriminant 3
175or as part of
176.Xr EC_GROUP_check 3
177after
178.Fn EC_GROUP_set_generator .
179.Pp
180.Fn EC_GROUP_set_curve
181sets the curve parameters of
182.Fa group
183to
184.Fa p ,
185.Fa a ,
186.Fa b
187using the optional
188.Fa ctx
189and the comments in
190.Fn EC_GROUP_new_curve_GFp
191apply.
192Existing
193.Fa generator ,
194.Fa order ,
195or
196.Fa cofactor
197on
198.Fa group
199are left unmodified and become most likely invalid.
200They must therefore be set to legitimate values using
201.Fn EC_GROUP_set_generator .
202.Pp
203.Fn EC_GROUP_get_curve
204copies the curve parameters of
205.Fa group
206into the caller-owned
207.Fa p ,
208.Fa a ,
209and
210.Fa b ,
211possibly making use of the
212.Fa ctx
213for conversion from internal representations.
214Except for
215.Fa group ,
216all arguments are optional.
217.Pp
218.Fn EC_GROUP_set_generator
219performs sanity checks based on Hasse's theorem
220and copies
221.Fa generator ,
222.Fa order
223and the optional
224.Fa cofactor
225into
226.Fa group ,
227replacing all existing entries.
228It is the caller's responsibility to ensure that
229.Fa generator
230is a point on the curve and that
231.Fa order
232is its order,
233which can partially be accomplished with a subsequent call to
234.Xr EC_GROUP_check 3 .
235If
236.Fa cofactor
237is
238.Dv NULL ,
239it can be computed on curves of cryptographic interest,
240in which case
241.Fa cofactor
242is set to the computed value, otherwise it is set to zero.
243.Pp
244.Fn EC_GROUP_get0_generator
245returns an internal pointer to the
246.Fa group Ns 's
247.Fa generator ,
248which may be
249.Dv NULL
250if no generator was set.
251.Pp
252.Fn EC_GROUP_get_degree
253returns the bit length of the prime
254.Fa p
255set on
256.Fa group .
257.Pp
258.Fn EC_GROUP_get_order
259copies the value of the
260.Fa group Ns 's
261.Fa order
262into the caller-owned
263.Fa order ,
264returning failure if the
265.Fa group Ns 's
266.Fa order
267is zero.
268The
269.Fa ctx
270argument is ignored.
271.Pp
272.Fn EC_GROUP_order_bits
273returns the number of bits in the
274.Fa group Ns 's
275.Fa order ,
276which is the result of calling
277.Xr BN_num_bits 3
278on
279.Fa order .
280Unlike
281.Fn EC_GROUP_get_order ,
282it does not fail if
283.Fa order
284is zero.
285.Pp
286.Fn EC_GROUP_get_cofactor
287copies the value of the
288.Fa group Ns 's
289.Fa cofactor
290into the caller-owned
291.Fa cofactor ,
292returning failure if the
293.Fa group Ns 's
294.Fa cofactor
295is zero.
296The
297.Fa ctx
298argument is ignored.
299.Pp
300The deprecated
301.Fn EC_GROUP_clear_free
302uses
303.Xr explicit_bzero 3
304and
305.Xr freezero 3
306to clear and free all data associated with
307.Fa group .
308If
309.Fa group
310is
311.Dv NULL ,
312no action occurs.
313Since there is no secret data in
314.Fa group ,
315this API is useless.
316In LibreSSL,
317.Xr EC_GROUP_free 3
318and
319.Fn EC_GROUP_clear_free
320behave identically.
321.Pp
322.Fn EC_GROUP_set_curve_GFp
323and
324.Fn EC_GROUP_get_curve_GFp
325are deprecated aliases for
326.Fn EC_GROUP_set_curve
327and
328.Fn EC_GROUP_get_curve ,
329respectively.
330.Sh RETURN VALUES
331.Fn EC_GROUP_new_curve_GFp
332returns a newly allocated group or
333.Dv NULL
334if memory allocation fails,
335or if some minimal sanity checks on
336.Fa p ,
337.Fa a ,
338and
339.Fa b
340fail.
341.Pp
342.Fn EC_GROUP_set_curve
343and
344.Fn EC_GROUP_set_curve_GFp
345return 1 on success and 0 on failure.
346Failure conditions include that
347.Fa p
348is smaller than or equal to three, or even, or
349memory allocation failure.
350.Pp
351.Fn EC_GROUP_get_curve
352and
353.Fn EC_GROUP_get_curve_GFp
354return 1 on success and 0 on memory allocation failure.
355.Pp
356.Fn EC_GROUP_set_generator
357returns 1 on success and 0 on memory allocation failure, or if
358.Fa order
359or
360.Fa cofactor
361are larger than Hasse's theorem allows.
362.Fn EC_GROUP_get0_generator
363returns an internal pointer to the
364.Fa generator
365or
366.Dv NULL
367if none was set on
368.Fa group .
369.Pp
370.Fn EC_GROUP_get_order
371returns 1 on success or 0 on memory allocation failure or if the
372.Fa group Ns 's
373order is set to
374.Fa zero .
375.Pp
376.Fn EC_GROUP_get_degree ,
377.Fn EC_GROUP_order_bits ,
378and
379.Fn EC_GROUP_get_cofactor
380return the number of bits in the
381.Fa group Ns 's
382.Fa p ,
383.Fa order ,
384and
385.Fa cofactor ,
386respectively.
387.Sh SEE ALSO
388.Xr BN_new 3 ,
389.Xr BN_num_bits 3 ,
390.Xr crypto 3 ,
391.Xr d2i_ECPKParameters 3 ,
392.Xr EC_GROUP_check 3 ,
393.Xr EC_GROUP_get_curve_name 3 ,
394.Xr EC_GROUP_new_by_curve_name 3 ,
395.Xr EC_KEY_METHOD_new 3 ,
396.Xr EC_KEY_new 3 ,
397.Xr EC_POINT_add 3 ,
398.Xr EC_POINT_get_affine_coordinates 3 ,
399.Xr EC_POINT_new 3 ,
400.Xr EC_POINT_point2oct 3 ,
401.Xr ECDH_compute_key 3 ,
402.Xr ECDSA_SIG_new 3
403.Sh STANDARDS
404.Rs
405.%T SEC 1: Elliptic Curve Cryptography, Version 2.0
406.%U https://www.secg.org/sec1-v2.pdf
407.%D May 21, 2009
408.Re
409.Pp
410.Rs
411.%T SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0
412.%U https://www.secg.org/sec2-v2.pdf
413.%D Jan 27, 2010
414.Re
415.Sh HISTORY
416.Fn EC_GROUP_new_curve_GFp ,
417.Fn EC_GROUP_clear_free ,
418.Fn EC_GROUP_set_curve_GFp ,
419.Fn EC_GROUP_get_curve_GFp ,
420.Fn EC_GROUP_set_generator ,
421.Fn EC_GROUP_get0_generator ,
422.Fn EC_GROUP_get_order ,
423and
424.Fn EC_GROUP_get_cofactor
425first appeared in OpenSSL 0.9.7 and
426have been available since
427.Ox 3.2 .
428.Pp
429.Fn EC_GROUP_get_degree
430first appeared in OpenSSL 0.9.8 and
431has been available since
432.Ox 4.5 .
433.Pp
434.Fn EC_GROUP_set_curve ,
435.Fn EC_GROUP_get_curve ,
436and
437.Fn EC_GROUP_order_bits
438first appeared in OpenSSL 1.1.1 and
439have been available since
440.Ox 7.0
441.Sh BUGS
442Too many.
443The API is unergonomic and the design is very poor even by
444OpenSSL's standards.
445Naming is inconsistent, especially in regards to the _GFp suffix
446and the _get_ infix.
447Function signatures are inconsistent.
448In particular, functions that should have a
449.Vt BN_CTX
450argument don't have one and functions that don't need it have one.
diff --git a/src/lib/libcrypto/man/EC_KEY_METHOD_new.3 b/src/lib/libcrypto/man/EC_KEY_METHOD_new.3
index 79c16ef014..5f5795d5cc 100644
--- a/src/lib/libcrypto/man/EC_KEY_METHOD_new.3
+++ b/src/lib/libcrypto/man/EC_KEY_METHOD_new.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.4 2024/07/21 08:36:43 tb Exp $ 1.\" $OpenBSD: EC_KEY_METHOD_new.3,v 1.5 2025/04/25 19:57:12 tb Exp $
2.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 2.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
3.\" 3.\"
4.\" Permission to use, copy, modify, and distribute this software for any 4.\" Permission to use, copy, modify, and distribute this software for any
@@ -13,7 +13,7 @@
13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15.\" 15.\"
16.Dd $Mdocdate: July 21 2024 $ 16.Dd $Mdocdate: April 25 2025 $
17.Dt EC_KEY_METHOD_NEW 3 17.Dt EC_KEY_METHOD_NEW 3
18.Os 18.Os
19.Sh NAME 19.Sh NAME
@@ -312,7 +312,16 @@ returns 1 for success or 0 for failure.
312returns the EC_KEY implementation used by the given 312returns the EC_KEY implementation used by the given
313.Fa key . 313.Fa key .
314.Sh SEE ALSO 314.Sh SEE ALSO
315.Xr crypto 3 ,
316.Xr EC_GROUP_check 3 ,
317.Xr EC_GROUP_get_curve_name 3 ,
318.Xr EC_GROUP_new_by_curve_name 3 ,
319.Xr EC_GROUP_new_curve_GFp 3 ,
315.Xr EC_KEY_new 3 , 320.Xr EC_KEY_new 3 ,
321.Xr EC_POINT_add 3 ,
322.Xr EC_POINT_get_affine_coordinates 3 ,
323.Xr EC_POINT_new 3 ,
324.Xr EC_POINT_point2oct 3 ,
316.Xr ECDSA_sign 3 325.Xr ECDSA_sign 3
317.Sh HISTORY 326.Sh HISTORY
318These functions first appeared in OpenSSL 1.1.0 327These functions first appeared in OpenSSL 1.1.0
diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3
index c24cb080ef..a2592a20ae 100644
--- a/src/lib/libcrypto/man/EC_KEY_new.3
+++ b/src/lib/libcrypto/man/EC_KEY_new.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: EC_KEY_new.3,v 1.21 2025/03/08 16:38:13 tb Exp $ 1.\" $OpenBSD: EC_KEY_new.3,v 1.22 2025/04/25 19:57:12 tb Exp $
2.\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500 2.\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500
3.\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 3.\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
4.\" 4.\"
@@ -49,7 +49,7 @@
49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" OF THE POSSIBILITY OF SUCH DAMAGE.
51.\" 51.\"
52.Dd $Mdocdate: March 8 2025 $ 52.Dd $Mdocdate: April 25 2025 $
53.Dt EC_KEY_NEW 3 53.Dt EC_KEY_NEW 3
54.Os 54.Os
55.Sh NAME 55.Sh NAME
@@ -234,7 +234,7 @@ and supplying the
234.Fa nid 234.Fa nid
235of the associated curve. 235of the associated curve.
236Refer to 236Refer to
237.Xr EC_GROUP_new 3 237.Xr EC_GROUP_new_by_curve_name 3
238for a description of curve names. 238for a description of curve names.
239This function simply wraps calls to 239This function simply wraps calls to
240.Fn EC_KEY_new 240.Fn EC_KEY_new
@@ -357,7 +357,7 @@ The format of the external representation of the public key written by
357such as whether it is stored in a compressed form or not, 357such as whether it is stored in a compressed form or not,
358is described by the point_conversion_form. 358is described by the point_conversion_form.
359See 359See
360.Xr EC_GROUP_copy 3 360.Xr EC_POINT_point2oct 3
361for a description of point_conversion_form. 361for a description of point_conversion_form.
362.Pp 362.Pp
363When reading a private key encoded without an associated public key, 363When reading a private key encoded without an associated public key,
@@ -378,7 +378,7 @@ and
378get and set the point_conversion_form for the 378get and set the point_conversion_form for the
379.Fa key . 379.Fa key .
380For a description of point_conversion_form refer to 380For a description of point_conversion_form refer to
381.Xr EC_GROUP_copy 3 . 381.Xr EC_POINT_point2oct 3 .
382.Pp 382.Pp
383.Fn EC_KEY_set_flags 383.Fn EC_KEY_set_flags
384sets the flags in the 384sets the flags in the
@@ -407,7 +407,7 @@ sets the asn1_flag on the underlying
407.Vt EC_GROUP 407.Vt EC_GROUP
408object (if set). 408object (if set).
409Refer to 409Refer to
410.Xr EC_GROUP_copy 3 410.Xr EC_GROUP_get_curve_name 3
411for further information on the asn1_flag. 411for further information on the asn1_flag.
412.Pp 412.Pp
413.Fn EC_KEY_precompute_mult 413.Fn EC_KEY_precompute_mult
@@ -488,11 +488,14 @@ returns the point_conversion_form for the
488.Vt EC_KEY . 488.Vt EC_KEY .
489.Sh SEE ALSO 489.Sh SEE ALSO
490.Xr d2i_ECPKParameters 3 , 490.Xr d2i_ECPKParameters 3 ,
491.Xr EC_GROUP_copy 3 , 491.Xr EC_GROUP_check 3 ,
492.Xr EC_GROUP_new 3 , 492.Xr EC_GROUP_get_curve_name 3 ,
493.Xr EC_GROUP_new_by_curve_name 3 ,
494.Xr EC_GROUP_new_curve_GFp 3 ,
493.Xr EC_KEY_METHOD_new 3 , 495.Xr EC_KEY_METHOD_new 3 ,
494.Xr EC_POINT_add 3 , 496.Xr EC_POINT_add 3 ,
495.Xr EC_POINT_new 3 , 497.Xr EC_POINT_get_affine_coordinates 3 ,
498.Xr EC_POINT_point2oct 3 ,
496.Xr ECDH_compute_key 3 , 499.Xr ECDH_compute_key 3 ,
497.Xr ECDSA_SIG_new 3 , 500.Xr ECDSA_SIG_new 3 ,
498.Xr EVP_PKEY_set1_EC_KEY 3 501.Xr EVP_PKEY_set1_EC_KEY 3
diff --git a/src/lib/libcrypto/man/EC_POINT_add.3 b/src/lib/libcrypto/man/EC_POINT_add.3
index cc35499c0e..9c75f0dcd3 100644
--- a/src/lib/libcrypto/man/EC_POINT_add.3
+++ b/src/lib/libcrypto/man/EC_POINT_add.3
@@ -1,4 +1,4 @@
1.\" $OpenBSD: EC_POINT_add.3,v 1.15 2025/03/08 16:48:22 tb Exp $ 1.\" $OpenBSD: EC_POINT_add.3,v 1.16 2025/04/25 19:57:12 tb Exp $
2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\" 3.\"
4.\" This file was written by Matt Caswell <matt@openssl.org>. 4.\" This file was written by Matt Caswell <matt@openssl.org>.
@@ -48,7 +48,7 @@
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\" 50.\"
51.Dd $Mdocdate: March 8 2025 $ 51.Dd $Mdocdate: April 25 2025 $
52.Dt EC_POINT_ADD 3 52.Dt EC_POINT_ADD 3
53.Os 53.Os
54.Sh NAME 54.Sh NAME
@@ -177,7 +177,7 @@ in which case the result is just
177.Dl q * m. 177.Dl q * m.
178.Pp 178.Pp
179See 179See
180.Xr EC_GROUP_copy 3 180.Xr EC_GROUP_new_curve_GFp 3
181for information about the generator. 181for information about the generator.
182.Sh RETURN VALUES 182.Sh RETURN VALUES
183The following functions return 1 on success or 0 on error: 183The following functions return 1 on success or 0 on error:
@@ -197,11 +197,17 @@ returns 1 if the point is on the curve, 0 if not, or -1 on error.
197.Fn EC_POINT_cmp 197.Fn EC_POINT_cmp
198returns 1 if the points are not equal, 0 if they are, or -1 on error. 198returns 1 if the points are not equal, 0 if they are, or -1 on error.
199.Sh SEE ALSO 199.Sh SEE ALSO
200.Xr crypto 3 ,
200.Xr d2i_ECPKParameters 3 , 201.Xr d2i_ECPKParameters 3 ,
201.Xr EC_GROUP_copy 3 , 202.Xr EC_GROUP_check 3 ,
202.Xr EC_GROUP_new 3 , 203.Xr EC_GROUP_get_curve_name 3 ,
204.Xr EC_GROUP_new_by_curve_name 3 ,
205.Xr EC_GROUP_new_curve_GFp 3 ,
206.Xr EC_KEY_METHOD_new 3 ,
203.Xr EC_KEY_new 3 , 207.Xr EC_KEY_new 3 ,
204.Xr EC_POINT_new 3 208.Xr EC_POINT_get_affine_coordinates 3 ,
209.Xr EC_POINT_new 3 ,
210.Xr EC_POINT_point2oct 3
205.Sh HISTORY 211.Sh HISTORY
206.Fn EC_POINT_add , 212.Fn EC_POINT_add ,
207.Fn EC_POINT_dbl , 213.Fn EC_POINT_dbl ,
diff --git a/src/lib/libcrypto/man/EC_POINT_get_affine_coordinates.3 b/src/lib/libcrypto/man/EC_POINT_get_affine_coordinates.3
new file mode 100644
index 0000000000..b36d480530
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_POINT_get_affine_coordinates.3
@@ -0,0 +1,215 @@
1.\" $OpenBSD: EC_POINT_get_affine_coordinates.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_POINT_GET_AFFINE_COORDINATES 3
19.Os
20.Sh NAME
21.Nm EC_POINT_get_affine_coordinates ,
22.Nm EC_POINT_set_affine_coordinates ,
23.Nm EC_POINT_set_compressed_coordinates ,
24.Nm EC_POINT_set_to_infinity ,
25.Nm EC_POINT_get_affine_coordinates_GFp ,
26.Nm EC_POINT_set_affine_coordinates_GFp ,
27.Nm EC_POINT_set_compressed_coordinates_GFp
28.Nd get and set coordinates of elliptic curve points
29.Sh SYNOPSIS
30.In openssl/bn.h
31.In openssl/ec.h
32.Pp
33.Ft int
34.Fo EC_POINT_get_affine_coordinates
35.Fa "const EC_GROUP *group"
36.Fa "const EC_POINT *point"
37.Fa "BIGNUM *x"
38.Fa "BIGNUM *y"
39.Fa "BN_CTX *ctx"
40.Fc
41.Ft int
42.Fo EC_POINT_set_affine_coordinates
43.Fa "const EC_GROUP *group"
44.Fa "EC_POINT *point"
45.Fa "const BIGNUM *x"
46.Fa "const BIGNUM *y"
47.Fa "BN_CTX *ctx"
48.Fc
49.Ft int
50.Fo EC_POINT_set_compressed_coordinates
51.Fa "const EC_GROUP *group"
52.Fa "EC_POINT *point"
53.Fa "const BIGNUM *x"
54.Fa "int y_bit"
55.Fa "BN_CTX *ctx"
56.Fc
57.Ft int
58.Fo EC_POINT_set_to_infinity
59.Fa "const EC_GROUP *group"
60.Fa "EC_POINT *point"
61.Fc
62.Pp
63Deprecated:
64.Pp
65.Ft int
66.Fo EC_POINT_get_affine_coordinates_GFp
67.Fa "const EC_GROUP *group"
68.Fa "const EC_POINT *point"
69.Fa "BIGNUM *x"
70.Fa "BIGNUM *y"
71.Fa "BN_CTX *ctx"
72.Fc
73.Ft int
74.Fo EC_POINT_set_affine_coordinates_GFp
75.Fa "const EC_GROUP *group"
76.Fa "EC_POINT *point"
77.Fa "const BIGNUM *x"
78.Fa "const BIGNUM *y"
79.Fa "BN_CTX *ctx"
80.Fc
81.Ft int
82.Fo EC_POINT_set_compressed_coordinates_GFp
83.Fa "const EC_GROUP *group"
84.Fa "EC_POINT *point"
85.Fa "const BIGNUM *x"
86.Fa "int y_bit"
87.Fa "BN_CTX *ctx"
88.Fc
89.Sh DESCRIPTION
90.Fn EC_POINT_get_affine_coordinates
91assumes that
92.Fa point
93is a point on
94.Fa group ,
95calculates its affine coordinates from its internal representation
96using the optional
97.Fa ctx ,
98and copies them into the optional user-provided
99.Fa x
100and
101.Fa y .
102.Pp
103.Fn EC_POINT_set_affine_coordinates
104assumes that
105.Fa x
106and
107.Fa y
108are the affine coordinates of a point on
109.Fa group ,
110converts them into internal representation and sets them on
111.Fa point
112using the optional
113.Fa ctx .
114The user-provided
115.Fa point
116should be the result of
117.Fn EC_POINT_new 3
118with an argument of
119.Fa group .
120It then verifies using
121.Xr EC_POINT_is_on_curve 3
122that
123.Fa x
124and
125.Fa y
126are indeed the affine coordinates of a point on
127.Fa group .
128.Pp
129.Fn EC_POINT_set_compressed_coordinates
130assumes that
131.Fa x
132is the x-coordinate and
133.Fa y_bit
134is the parity bit of a point on
135.Fa group
136and sets
137.Fa point
138to the corresponding point on
139.Fa group .
140It does this by solving the quadratic equation y^2 = x^3 + ax + b using
141.Xr BN_mod_sqrt 3
142and the optional
143.Fa ctx ,
144chooses the solution
145.Fa y
146with parity matching
147.Fa y_bit ,
148and passes
149.Fa x
150and
151.Fa y
152to
153.Fn EC_POINT_set_affine_coordinates .
154The user-provided
155.Fa point
156should be the result of
157.Fn EC_POINT_new
158with argument
159.Fa group .
160.Pp
161.Fn EC_POINT_set_to_infinity
162sets
163.Fa point
164to the internal representation of the point at infinity on
165.Fa group .
166.Pp
167.Fn EC_POINT_get_affine_coordinates_GFp
168is a deprecated alias for
169.Fn EC_POINT_get_affine_coordinates .
170Similarly for
171.Fn EC_POINT_set_affine_coordinates_GFp
172and
173.Fn EC_POINT_set_compressed_coordinates_GFp .
174.Sh RETURN VALUES
175All these functions return 1 on success and 0 on error.
176Error conditions include memory allocation failure,
177that
178.Fa point
179is incompatible with
180.Fa group ,
181and, for the coordinate setters, that the provided coordinates
182do not represent a point on
183.Fa group .
184.Sh SEE ALSO
185.Xr BN_CTX_new 3 ,
186.Xr BN_is_zero 3 ,
187.Xr BN_mod_sqrt 3 ,
188.Xr crypto 3 ,
189.Xr d2i_ECPKParameters 3 ,
190.Xr EC_GROUP_check 3 ,
191.Xr EC_GROUP_get_curve_name 3 ,
192.Xr EC_GROUP_new_by_curve_name 3 ,
193.Xr EC_GROUP_new_curve_GFp 3 ,
194.Xr EC_KEY_METHOD_new 3 ,
195.Xr EC_KEY_new 3 ,
196.Xr EC_POINT_add 3 ,
197.Xr EC_POINT_new 3 ,
198.Xr EC_POINT_point2oct 3 ,
199.Xr ECDH_compute_key 3 ,
200.Xr ECDSA_SIG_new 3
201.Sh HISTORY
202.Fn EC_POINT_get_affine_coordinates_GFp ,
203.Fn EC_POINT_set_affine_coordinates_GFp ,
204.Fn EC_POINT_set_compressed_coordinates_GFp ,
205and
206.Fn EC_POINT_set_to_infinity
207first appeared in OpenSSL 0.9.7 and have been available since
208.Ox 3.2 .
209.Pp
210.Fn EC_POINT_get_affine_coordinates ,
211.Fn EC_POINT_set_affine_coordinates ,
212and
213.Fn EC_POINT_set_compressed_coordinates
214first appeared in OpenSSL 1.1.1 and have been available since
215.Ox 7.0 .
diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3
index db6280fce7..cfc988f294 100644
--- a/src/lib/libcrypto/man/EC_POINT_new.3
+++ b/src/lib/libcrypto/man/EC_POINT_new.3
@@ -1,54 +1,20 @@
1.\" $OpenBSD: EC_POINT_new.3,v 1.17 2025/03/08 17:04:07 tb Exp $ 1.\" $OpenBSD: EC_POINT_new.3,v 1.18 2025/04/25 19:57:12 tb Exp $
2.\" full merge up to: OpenSSL 50db8163 Jul 30 16:56:41 2018 +0100
3.\" 2.\"
4.\" This file was written by Matt Caswell <matt@openssl.org>. 3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
5.\" Copyright (c) 2013, 2016 The OpenSSL Project. All rights reserved.
6.\" 4.\"
7.\" Redistribution and use in source and binary forms, with or without 5.\" Permission to use, copy, modify, and distribute this software for any
8.\" modification, are permitted provided that the following conditions 6.\" purpose with or without fee is hereby granted, provided that the above
9.\" are met: 7.\" copyright notice and this permission notice appear in all copies.
10.\" 8.\"
11.\" 1. Redistributions of source code must retain the above copyright 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" notice, this list of conditions and the following disclaimer. 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13.\" 16.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright 17.Dd $Mdocdate: April 25 2025 $
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: March 8 2025 $
52.Dt EC_POINT_NEW 3 18.Dt EC_POINT_NEW 3
53.Os 19.Os
54.Sh NAME 20.Sh NAME
@@ -56,163 +22,56 @@
56.Nm EC_POINT_free , 22.Nm EC_POINT_free ,
57.Nm EC_POINT_clear_free , 23.Nm EC_POINT_clear_free ,
58.Nm EC_POINT_copy , 24.Nm EC_POINT_copy ,
59.Nm EC_POINT_dup , 25.Nm EC_POINT_dup
60.Nm EC_POINT_set_to_infinity , 26.Nd allocate, free and copy elliptic curve points
61.Nm EC_POINT_set_affine_coordinates ,
62.Nm EC_POINT_set_affine_coordinates_GFp ,
63.Nm EC_POINT_get_affine_coordinates ,
64.Nm EC_POINT_get_affine_coordinates_GFp ,
65.Nm EC_POINT_set_compressed_coordinates ,
66.Nm EC_POINT_set_compressed_coordinates_GFp ,
67.Nm EC_POINT_point2oct ,
68.Nm EC_POINT_oct2point ,
69.Nm EC_POINT_point2bn ,
70.Nm EC_POINT_bn2point ,
71.Nm EC_POINT_point2hex ,
72.Nm EC_POINT_hex2point
73.Nd create, destroy, and manipulate EC_POINT objects
74.Sh SYNOPSIS 27.Sh SYNOPSIS
75.In openssl/ec.h 28.In openssl/ec.h
76.In openssl/bn.h 29.Pp
77.Ft EC_POINT * 30.Ft "EC_POINT *"
78.Fo EC_POINT_new 31.Fo EC_POINT_new
79.Fa "const EC_GROUP *group" 32.Fa "const EC_GROUP *group"
80.Fc 33.Fc
81.Ft void 34.Ft "void"
82.Fo EC_POINT_free 35.Fo EC_POINT_free
83.Fa "EC_POINT *point" 36.Fa "EC_POINT *point"
84.Fc 37.Fc
85.Ft void 38.Ft "void"
86.Fo EC_POINT_clear_free 39.Fo EC_POINT_clear_free
87.Fa "EC_POINT *point" 40.Fa "EC_POINT *point"
88.Fc 41.Fc
89.Ft int 42.Ft "int"
90.Fo EC_POINT_copy 43.Fo EC_POINT_copy
91.Fa "EC_POINT *dst" 44.Fa "EC_POINT *dst"
92.Fa "const EC_POINT *src" 45.Fa "const EC_POINT *src"
93.Fc 46.Fc
94.Ft EC_POINT * 47.Ft "EC_POINT *"
95.Fo EC_POINT_dup 48.Fo EC_POINT_dup
96.Fa "const EC_POINT *src" 49.Fa "const EC_POINT *point"
97.Fa "const EC_GROUP *group"
98.Fc
99.Ft int
100.Fo EC_POINT_set_to_infinity
101.Fa "const EC_GROUP *group"
102.Fa "EC_POINT *point"
103.Fc
104.Ft int
105.Fo EC_POINT_set_affine_coordinates
106.Fa "const EC_GROUP *group"
107.Fa "EC_POINT *p"
108.Fa "const BIGNUM *x"
109.Fa "const BIGNUM *y"
110.Fa "BN_CTX *ctx"
111.Fc
112.Ft int
113.Fo EC_POINT_set_affine_coordinates_GFp
114.Fa "const EC_GROUP *group"
115.Fa "EC_POINT *p"
116.Fa "const BIGNUM *x"
117.Fa "const BIGNUM *y"
118.Fa "BN_CTX *ctx"
119.Fc
120.Ft int
121.Fo EC_POINT_get_affine_coordinates
122.Fa "const EC_GROUP *group"
123.Fa "const EC_POINT *p"
124.Fa "BIGNUM *x"
125.Fa "BIGNUM *y"
126.Fa "BN_CTX *ctx"
127.Fc
128.Ft int
129.Fo EC_POINT_get_affine_coordinates_GFp
130.Fa "const EC_GROUP *group"
131.Fa "const EC_POINT *p"
132.Fa "BIGNUM *x"
133.Fa "BIGNUM *y"
134.Fa "BN_CTX *ctx"
135.Fc
136.Ft int
137.Fo EC_POINT_set_compressed_coordinates
138.Fa "const EC_GROUP *group"
139.Fa "EC_POINT *p"
140.Fa "const BIGNUM *x"
141.Fa "int y_bit"
142.Fa "BN_CTX *ctx"
143.Fc
144.Ft int
145.Fo EC_POINT_set_compressed_coordinates_GFp
146.Fa "const EC_GROUP *group"
147.Fa "EC_POINT *p"
148.Fa "const BIGNUM *x"
149.Fa "int y_bit"
150.Fa "BN_CTX *ctx"
151.Fc
152.Ft size_t
153.Fo EC_POINT_point2oct
154.Fa "const EC_GROUP *group" 50.Fa "const EC_GROUP *group"
155.Fa "const EC_POINT *p"
156.Fa "point_conversion_form_t form"
157.Fa "unsigned char *buf"
158.Fa "size_t len"
159.Fa "BN_CTX *ctx"
160.Fc
161.Ft int
162.Fo EC_POINT_oct2point
163.Fa "const EC_GROUP *group"
164.Fa "EC_POINT *p"
165.Fa "const unsigned char *buf"
166.Fa "size_t len"
167.Fa "BN_CTX *ctx"
168.Fc
169.Ft BIGNUM *
170.Fo EC_POINT_point2bn
171.Fa "const EC_GROUP *"
172.Fa "const EC_POINT *"
173.Fa "point_conversion_form_t form"
174.Fa "BIGNUM *"
175.Fa "BN_CTX *"
176.Fc
177.Ft EC_POINT *
178.Fo EC_POINT_bn2point
179.Fa "const EC_GROUP *"
180.Fa "const BIGNUM *"
181.Fa "EC_POINT *"
182.Fa "BN_CTX *"
183.Fc
184.Ft char *
185.Fo EC_POINT_point2hex
186.Fa "const EC_GROUP *"
187.Fa "const EC_POINT *"
188.Fa "point_conversion_form_t form"
189.Fa "BN_CTX *"
190.Fc
191.Ft EC_POINT *
192.Fo EC_POINT_hex2point
193.Fa "const EC_GROUP *"
194.Fa "const char *"
195.Fa "EC_POINT *"
196.Fa "BN_CTX *"
197.Fc 51.Fc
198.Sh DESCRIPTION 52.Sh DESCRIPTION
199An 53An
200.Vt EC_POINT 54.Vt EC_POINT
201represents a point on a curve. 55object holds a point on the elliptic curve represented by an
202A curve is represented by an 56.Vt EC_GROUP .
203.Vt EC_GROUP 57The details of the internal representation depend on the group
204object created by the functions described in 58and should never be an application's concern since the EC library
205.Xr EC_GROUP_new 3 . 59has API to set a point's coordinates,
60.Xr EC_POINT_set_affine_coordinates 3 .
206.Pp 61.Pp
207A new point is constructed by calling the function
208.Fn EC_POINT_new 62.Fn EC_POINT_new
209and providing the 63allocates and initializes an
210.Fa group 64.Vt EC_POINT
211object that the point relates to. 65object to be used with the
66.Fa group .
67Before explicitly setting its coordinates, the returned
68.Vt EC_POINT
69is invalid.
212.Pp 70.Pp
213.Fn EC_POINT_free 71.Fn EC_POINT_free
214frees the memory associated with the 72frees
215.Vt EC_POINT . 73.Fa point
74and all memory associated with it.
216If 75If
217.Fa point 76.Fa point
218is a 77is a
@@ -220,236 +79,129 @@ is a
220pointer, no action occurs. 79pointer, no action occurs.
221.Pp 80.Pp
222.Fn EC_POINT_clear_free 81.Fn EC_POINT_clear_free
223destroys any sensitive data held within the 82is intended to destroy sensitive data held in
224.Vt EC_POINT
225and then frees its memory.
226If
227.Fa point 83.Fa point
228is a 84in addition to freeing all memory associated with it.
229.Dv NULL 85Since elliptic curve points usually hold public data, this
230pointer, no action occurs. 86is rarely needed.
87In LibreSSL,
88.Fn EC_POINT_free
89and
90.Fn EC_POINT_clear_free
91behave identically.
231.Pp 92.Pp
232.Fn EC_POINT_copy 93.Fn EC_POINT_copy
233copies the point 94copies the internal representation of
234.Fa src 95.Fa src
235into 96into
236.Fa dst . 97.Fa dst .
237Both 98If
238.Fa src 99.Fa src
239and 100and
240.Fa dst 101.Fa dst
241must use the same 102are identical, no action occurs.
242.Vt EC_METHOD . 103Both
243.Pp
244.Fn EC_POINT_dup
245creates a new
246.Vt EC_POINT
247object and copies the content from
248.Fa src 104.Fa src
249to the newly created
250.Vt EC_POINT
251object.
252.Pp
253A valid point on a curve is the special point at infinity.
254A point is set to be at infinity by calling
255.Fn EC_POINT_set_to_infinity .
256.Pp
257The affine coordinates for a point describe a point in terms of its
258.Fa x
259and
260.Fa y
261position.
262The function
263.Fn EC_POINT_set_affine_coordinates
264sets the
265.Fa x
266and
267.Fa y
268coordinates for the point
269.Fa p
270defined over the curve given in
271.Fa group .
272The function
273.Fn EC_POINT_get_affine_coordinates
274sets
275.Fa x
276and
277.Fa y ,
278either of which may be
279.Dv NULL ,
280to the corresponding coordinates of
281.Fa p .
282.Pp
283The functions
284.Fn EC_POINT_set_affine_coordinates_GFp
285is a deprecated synonym for
286.Fn EC_POINT_set_affine_coordinates
287and the function
288.Fn EC_POINT_get_affine_coordinates_GFp
289is a deprecated synonym for
290.Fn EC_POINT_get_affine_coordinates .
291.Pp
292Points can also be described in terms of their compressed coordinates.
293For a point
294.Pq Fa x , y ,
295for any given value for
296.Fa x
297such that the point is on the curve, there will only ever be two
298possible values for
299.Fa y .
300Therefore, a point can be set using the
301.Fn EC_POINT_set_compressed_coordinates
302function where
303.Fa x
304is the x coordinate and
305.Fa y_bit
306is a value 0 or 1 to identify which of the two possible values for y
307should be used.
308.Pp
309The functions
310.Fn EC_POINT_set_compressed_coordinates_GFp
311is a deprecated synonym for
312.Fn EC_POINT_set_compressed_coordinates .
313.Pp
314In addition
315.Vt EC_POINT Ns s
316can be converted to and from various external representations.
317Supported representations are octet strings,
318.Vt BIGNUM Ns s ,
319and hexadecimal.
320The format of the external representation is described by the
321point_conversion_form.
322See
323.Xr EC_GROUP_copy 3
324for a description of point_conversion_form.
325Octet strings are stored in a buffer along with an associated buffer
326length.
327A point held in a
328.Vt BIGNUM
329is calculated by converting the point to an octet string and then
330converting that octet string into a
331.Vt BIGNUM
332integer.
333Points in hexadecimal format are stored in a NUL terminated character
334string where each character is one of the printable values 0-9 or A-F
335(or a-f).
336.Pp
337The functions
338.Fn EC_POINT_point2oct ,
339.Fn EC_POINT_oct2point ,
340.Fn EC_POINT_point2bn ,
341.Fn EC_POINT_bn2point ,
342.Fn EC_POINT_point2hex ,
343and 105and
344.Fn EC_POINT_hex2point 106.Fa dst
345convert from and to 107should be the result of
346.Vt EC_POINT Ns s 108.Fn EC_POINT_new
347for the formats octet string, 109with the same
348.Vt BIGNUM , 110.Fa group
349and hexadecimal, respectively. 111argument, although
350.Pp 112.Fn EC_POINT_copy
351The function 113cannot check that.
352.Fn EC_POINT_point2oct
353must be supplied with a
354.Fa buf
355long enough to store the octet string.
356The return value provides the number of octets stored.
357Calling the function with a
358.Dv NULL
359.Fa buf
360will not perform the conversion but will still return the required
361buffer length.
362.Pp 114.Pp
363The function 115.Fn EC_POINT_dup
364.Fn EC_POINT_point2hex 116creates a deep copy of
365will allocate sufficient memory to store the hexadecimal string. 117.Fa point
366It is the caller's responsibility to free this memory with a subsequent 118by combining
367call to 119.Fn EC_POINT_new
368.Xr free 3 . 120with
121.Fn EC_GROUP_copy .
369.Sh RETURN VALUES 122.Sh RETURN VALUES
370.Fn EC_POINT_new 123.Fn EC_POINT_new
371and 124returns a newly allocated
372.Fn EC_POINT_dup
373return the newly allocated
374.Vt EC_POINT 125.Vt EC_POINT
375or 126or
376.Dv NULL 127.Dv NULL
377on error. 128on memory allocation failure.
378.Pp 129.Pp
379The following functions return 1 on success or 0 on error: 130.Fn EC_POINT_copy
380.Fn EC_POINT_copy , 131returns 1 on success or 0 on error.
381.Fn EC_POINT_set_to_infinity , 132Error conditions include memory allocation failure and that
382.Fn EC_POINT_set_affine_coordinates , 133.Fa dst
383.Fn EC_POINT_set_affine_coordinates_GFp , 134is incompatible with the group on which
384.Fn EC_POINT_get_affine_coordinates , 135.Fa src
385.Fn EC_POINT_get_affine_coordinates_GFp , 136is defined.
386.Fn EC_POINT_set_compressed_coordinates ,
387.Fn EC_POINT_set_compressed_coordinates_GFp ,
388and
389.Fn EC_POINT_oct2point .
390.Pp
391.Fn EC_POINT_point2oct
392returns the length of the required buffer, or 0 on error.
393.Pp
394.Fn EC_POINT_point2bn
395returns the pointer to the
396.Vt BIGNUM
397supplied or
398.Dv NULL
399on error.
400.Pp
401.Fn EC_POINT_bn2point
402returns the pointer to the
403.Vt EC_POINT
404supplied or
405.Dv NULL
406on error.
407.Pp
408.Fn EC_POINT_point2hex
409returns a pointer to the hex string or
410.Dv NULL
411on error.
412.Pp 137.Pp
413.Fn EC_POINT_hex2point 138.Fn EC_POINT_dup
414returns the pointer to the 139returns a newly allocated
415.Vt EC_POINT 140.Vt EC_POINT
416supplied or 141or
417.Dv NULL 142.Dv NULL
418on error. 143on failure.
144Error conditions include memory allocation failure or that
145.Fa group
146is incompatible with
147.Fa src .
419.Sh SEE ALSO 148.Sh SEE ALSO
149.Xr BN_CTX_new 3 ,
150.Xr BN_is_zero 3 ,
151.Xr crypto 3 ,
420.Xr d2i_ECPKParameters 3 , 152.Xr d2i_ECPKParameters 3 ,
421.Xr EC_GROUP_copy 3 , 153.Xr EC_GROUP_check 3 ,
422.Xr EC_GROUP_new 3 , 154.Xr EC_GROUP_get_curve_name 3 ,
155.Xr EC_GROUP_new_by_curve_name 3 ,
156.Xr EC_GROUP_new_curve_GFp 3 ,
157.Xr EC_KEY_METHOD_new 3 ,
423.Xr EC_KEY_new 3 , 158.Xr EC_KEY_new 3 ,
424.Xr EC_POINT_add 3 , 159.Xr EC_POINT_add 3 ,
425.Xr ECDH_compute_key 3 160.Xr EC_POINT_get_affine_coordinates 3 ,
161.Xr EC_POINT_point2oct 3 ,
162.Xr ECDH_compute_key 3 ,
163.Xr ECDSA_SIG_new 3
426.Sh HISTORY 164.Sh HISTORY
427.Fn EC_POINT_new , 165.Fn EC_POINT_new ,
428.Fn EC_POINT_free , 166.Fn EC_POINT_free ,
429.Fn EC_POINT_clear_free , 167.Fn EC_POINT_clear_free ,
430.Fn EC_POINT_copy ,
431.Fn EC_POINT_set_to_infinity ,
432.Fn EC_POINT_set_affine_coordinates_GFp ,
433.Fn EC_POINT_get_affine_coordinates_GFp ,
434.Fn EC_POINT_set_compressed_coordinates_GFp ,
435.Fn EC_POINT_point2oct ,
436and 168and
437.Fn EC_POINT_oct2point 169.Fn EC_POINT_copy
438first appeared in OpenSSL 0.9.7 and have been available since 170first appeared in OpenSSL 0.9.7 and have been available since
439.Ox 3.2 . 171.Ox 3.2 .
440.Pp 172.Pp
441.Fn EC_POINT_dup , 173.Fn EC_POINT_dup
442.Fn EC_POINT_point2bn , 174first appeared in OpenSSL 0.9.8 and has been available since
443.Fn EC_POINT_bn2point ,
444.Fn EC_POINT_point2hex ,
445and
446.Fn EC_POINT_hex2point
447first appeared in OpenSSL 0.9.8 and have been available since
448.Ox 4.5 . 175.Ox 4.5 .
449.Pp 176.Sh BUGS
450.Fn EC_POINT_set_affine_coordinates , 177A fundamental flaw in the OpenSSL API toolkit is that
451.Fn EC_POINT_get_affine_coordinates , 178.Fn *_new
179functions usually create invalid objects that are tricky to
180turn into valid objects.
181A fundamental flaw in the EC library is that
182.Vt EC_POINT
183objects do not hold a reference to the group they live on
184despite the fact that
185.Fn EC_POINT_new
186has a
187.Fa group
188argument.
189This is difficult to fix because
190.Vt EC_GROUP
191objects are not reference counted and
192because of const qualifiers in the API.
193This is the root cause for various contortions in the EC library
194and API.
195This has security implications because not
196only does the library not know whether an
197.Fa EC_POINT
198object represents a valid point,
199even if it did know that it would not know on what curve.
200.Pp
201The signature of
202.Fn EC_GROUP_dup
203is bizarre and the order of
204.Fa point
452and 205and
453.Fn EC_POINT_set_compressed_coordinates 206.Fa group
454first appeared in OpenSSL 1.1.1 and have been available since 207is inconsistent with the rest of the EC API.
455.Ox 7.0 .
diff --git a/src/lib/libcrypto/man/EC_POINT_point2oct.3 b/src/lib/libcrypto/man/EC_POINT_point2oct.3
new file mode 100644
index 0000000000..d0663670ee
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_POINT_point2oct.3
@@ -0,0 +1,431 @@
1.\" $OpenBSD: EC_POINT_point2oct.3,v 1.1 2025/04/25 19:57:12 tb Exp $
2.\"
3.\" Copyright (c) 2025 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: April 25 2025 $
18.Dt EC_POINT_POINT2OCT 3
19.Os
20.Sh NAME
21.Nm EC_POINT_point2oct ,
22.Nm EC_POINT_oct2point ,
23.Nm EC_POINT_point2bn ,
24.Nm EC_POINT_bn2point ,
25.Nm EC_POINT_point2hex ,
26.Nm EC_POINT_hex2point
27.Nd encode and decode elliptic curve points
28.Sh SYNOPSIS
29.In openssl/bn.h
30.In openssl/ec.h
31.Bd -literal
32typedef enum {
33 POINT_CONVERSION_COMPRESSED = 2,
34 POINT_CONVERSION_UNCOMPRESSED = 4,
35 POINT_CONVERSION_HYBRID = 6
36} point_conversion_form_t;
37
38.Ed
39.Ft size_t
40.Fo EC_POINT_point2oct
41.Fa "const EC_GROUP *group"
42.Fa "const EC_POINT *point"
43.Fa "point_conversion_form_t form"
44.Fa "unsigned char *buf"
45.Fa "size_t len"
46.Fa "BN_CTX *ctx"
47.Fc
48.Ft int
49.Fo EC_POINT_oct2point
50.Fa "const EC_GROUP *group"
51.Fa "EC_POINT *point"
52.Fa "const unsigned char *buf"
53.Fa "size_t len"
54.Fa "BN_CTX *ctx"
55.Fc
56.Ft "BIGNUM *"
57.Fo EC_POINT_point2bn
58.Fa "const EC_GROUP *group"
59.Fa "const EC_POINT *point"
60.Fa "point_conversion_form_t form"
61.Fa "BIGNUM *bn"
62.Fa "BN_CTX *ctx"
63.Fc
64.Ft "EC_POINT *"
65.Fo EC_POINT_bn2point
66.Fa "const EC_GROUP *group"
67.Fa "const BIGNUM *bn"
68.Fa "EC_POINT *point"
69.Fa "BN_CTX *ctx"
70.Fc
71.Ft "char *"
72.Fo EC_POINT_point2hex
73.Fa "const EC_GROUP *group"
74.Fa "const EC_POINT *point"
75.Fa "point_conversion_form_t form"
76.Fa "BN_CTX *ctx"
77.Fc
78.Ft "EC_POINT *"
79.Fo EC_POINT_hex2point
80.Fa "const EC_GROUP *group"
81.Fa "const char *hex"
82.Fa "EC_POINT *point"
83.Fa "BN_CTX *ctx"
84.Fc
85.Sh DESCRIPTION
86The
87.Fa ctx
88argument of all functions in this manual is optional.
89.Pp
90An
91.Vt EC_POINT
92object represents a point on the elliptic curve given by an
93.Vt EC_GROUP
94object.
95It is either the point at infinity or it has a representation
96(x, y) in standard affine coordinates,
97in which case it satisfies the curve's Weierstrass equation
98.Dl y^2 = x^3 + ax + b
99in the prime field of size p.
100Thus, y is a square root of x^3 + ax + b.
101Since p > 3 is odd, p - y is another square root
102with different parity, unless y is zero.
103Point compression uses that x and the parity of y are enough
104to compute y using
105.Xr BN_mod_sqrt 3 .
106.Pp
107Field elements are represented as non-negative integers < p
108in big-endian 2-complement form, zero-padded on the left to the byte
109length l of p.
110If X and Y are the representations of x and y, respectively, and P is
111the parity bit of y, the three encodings of the point (x, y) are
112the byte strings:
113.Bl -column "EncodingX" "CompressedX" "UncompressedX" "Hybrid" -offset indent -compact
114.It Ta Em Compressed Ta Em Uncompressed Ta Em Hybrid
115.It Encoding Ta 2+P || X Ta 4 || X || Y Ta 6+P || X || Y
116.It Length Ta 1 + l Ta 1 + 2l Ta 1 + 2l
117.El
118where the first octet is the point conversion form
119combined with the parity bit in the compressed and hybrid encodings.
120The point at infinity is encoded as a single zero byte.
121.Pp
122.Fn EC_POINT_point2oct
123converts
124.Fa point
125into the octet string encoding of type
126.Fa form .
127It assumes without checking that
128.Fa point
129is a point on the elliptic curve represented by
130.Fa group
131and operates in two modes depending on the
132.Fa buf
133argument.
134If
135.Fa buf
136is
137.Dv NULL ,
138.Fn EC_POINT_point2oct
139returns the length of
140.Fa point Ns 's
141encoding of type
142.Fa form
143and ignores the
144.Fa len
145and
146.Fa ctx
147arguments.
148If
149.Fa buf
150is not
151.Dv NULL
152and its length
153.Fa len
154is sufficiently big,
155.Fn EC_POINT_point2oct 3
156writes the
157.Fa point Ns 's
158encoding of type
159.Fa form
160to
161.Fa buf
162and returns the number of bytes written.
163Unless
164.Fa point
165is the point at infinity, the coordinates to be encoded are calculated using
166.Xr EC_POINT_get_affine_coordinates 3 .
167.Pp
168.Fn EC_POINT_oct2point
169decodes the octet string representation of a point on
170.Fa group
171in
172.Fa buf
173of size
174.Fa len
175and, if it represents a point on
176.Fa group ,
177sets it on the caller-provided
178.Fa point
179using
180.Xr EC_POINT_set_to_infinity 3
181.Xr EC_POINT_set_compressed_coordinates 3 ,
182or
183.Xr EC_POINT_set_affine_coordinates 3 .
184For hybrid encoding the consistency of
185the parity bit in the leading octet is verified.
186.Pp
187.Fn EC_POINT_point2bn
188returns a
189.Vt BIGNUM
190containing the encoding of type
191.Fa form
192of the
193.Fa point
194on
195.Fa group .
196If
197.Fa bn
198is
199.Dv NULL ,
200this
201.Vt BIGNUM
202is newly allocated, otherwise the result is copied into
203.Fa bn
204and returned.
205.Fn EC_POINT_point2bn
206is equivalent to
207.Fn EC_POINT_point2oct
208followed by
209.Xr BN_bin2bn 3 .
210.Pp
211.Fn EC_POINT_bn2point
212assumes that
213.Fa bn
214contains the encoding of a point on
215.Fa group .
216If
217.Fa point
218is
219.Dv NULL ,
220the result is placed in a newly allocated
221.Vt EC_POINT ,
222otherwise the result is placed in
223.Fa point
224which is then returned.
225.Fn EC_POINT_bn2point
226is equivalent to
227.Xr BN_bn2bin 3
228followed by
229.Fn EC_POINT_oct2point .
230.Pp
231.Fn EC_POINT_point2hex
232returns a printable string containing the hexadecimal encoding of
233the point encoding of type
234.Fa form
235of the
236.Fa point
237on
238.Fa group .
239The string must be freed by the caller using
240.Xr free 3 .
241.Fn EC_POINT_point2hex
242is equivalent to
243.Fn EC_POINT_point2bn
244followed by
245.Fn BN_bn2hex 3 .
246.Pp
247.Fn EC_POINT_hex2point
248interprets
249.Fa hex
250as a hexadecimal encoding of the point encoding of a point on
251.Fa group .
252If
253.Fa point
254is
255.Dv NULL ,
256the result is returned in a newly allocated
257.Vt EC_POINT ,
258otherwise the result is copied into
259.Fa point ,
260which is then returned.
261.Fn EC_POINT_hex2point
262is equivalent to
263.Xr BN_hex2bn 3
264followed by
265.Fn EC_POINT_bn2point .
266.Sh RETURN VALUES
267If
268.Fa buf
269is
270.Dv NULL ,
271.Fn EC_POINT_point2oct
272returns the length needed to encode the
273.Fa point
274on
275.Fa group ,
276or 0 on error.
277If
278.Fa buf
279is not
280.Dv NULL ,
281.Fn EC_POINT_point2oct
282returns the number of bytes written to
283.Fa buf
284or 0 on error.
285Error conditions include that
286.Fa form
287is invalid,
288.Fa len
289is too small, and memory allocation failure.
290.Pp
291.Fn EC_POINT_oct2point
292returns 1 on success and 0 on error.
293Error conditions include invalid encoding,
294.Fa buf
295does not represent a point on
296.Fa group ,
297or memory allocation failure.
298.Pp
299.Fn EC_POINT_point2bn
300returns a
301.Vt BIGNUM
302containing the encoding of
303.Fa point
304or
305.Dv NULL
306on error.
307The returned
308.Vt BIGNUM
309is either
310.Fa in_bn
311or a newly allocated one which must be freed by the caller.
312Error conditions include those of
313.Fn EC_POINT_point2oct ,
314.Xr BN_bn2bin 3 ,
315or memory allocation failure.
316.Pp
317.Fn EC_POINT_bn2point
318returns an
319.Vt EC_POINT
320corresponding to the encoding in
321.Fa bn
322or
323.Dv NULL
324on error.
325The returned
326.Vt EC_POINT
327is either
328.Fa in_point
329or a newly allocated one which must be freed by the caller.
330Error conditions include those of
331.Xr BN_bn2bin 3 ,
332.Fn EC_POINT_oct2point ,
333or memory allocation failure.
334.Pp
335.Fn EC_POINT_point2hex
336returns a newly allocated string or
337.Dv NULL
338on error.
339Error conditions include those of
340.Fn EC_POINT_point2bn
341or
342.Xr BN_bn2hex 3 .
343.Pp
344.Fn EC_POINT_hex2point
345returns an
346.Vt EC_POINT
347containing the decoded point on
348.Fa group
349or
350.Dv NULL
351on error.
352The returned
353.Vt EC_POINT
354is either
355.Fa in_point
356or a newly allocated one which must be freed by the caller.
357Error conditions are those of
358.Xr BN_hex2bn 3 ,
359or
360.Fn EC_POINT_bn2point .
361.Sh SEE ALSO
362.Xr BN_mod_sqrt 3 ,
363.Xr BN_new 3 ,
364.Xr BN_num_bits 3 ,
365.Xr crypto 3 ,
366.Xr d2i_ECPKParameters 3 ,
367.Xr EC_GROUP_check 3 ,
368.Xr EC_GROUP_get_curve_name 3 ,
369.Xr EC_GROUP_new_by_curve_name 3 ,
370.Xr EC_GROUP_new_curve_GFp 3 ,
371.Xr EC_KEY_METHOD_new 3 ,
372.Xr EC_KEY_new 3 ,
373.Xr EC_POINT_add 3 ,
374.Xr EC_POINT_get_affine_coordinates 3 ,
375.Xr EC_POINT_new 3 ,
376.Xr ECDH_compute_key 3 ,
377.Xr ECDSA_SIG_new 3
378.Sh STANDARDS
379.Rs
380.%T SEC 1: Elliptic Curve Cryptography, Version 2.0
381.%U https://www.secg.org/sec1-v2.pdf
382.%D May 21, 2009
383.Re
384.Sh HISTORY
385.Fn EC_POINT_point2oct
386and
387.Fn EC_POINT_oct2point
388first appeared in OpenSSL 0.9.7 and have been available since
389.Ox 3.2 .
390.Pp
391.Fn EC_POINT_point2bn ,
392.Fn EC_POINT_bn2point ,
393.Fn EC_POINT_point2hex ,
394and
395.Fn EC_POINT_hex2point
396first appeared in OpenSSL 0.9.8 and have been available since
397.Ox 4.5 .
398.Sh BUGS
399The
400.Vt point_conversion_form_t
401is not properly exposed in the API.
402There is no representation for the point at infinity nor is there
403an API interface for the parity bit,
404forcing applications to invent their own and do bit twiddling in buffers.
405.Pp
406The poorly chosen signatures of the functions in this manual result
407in an unergonomic API, particularly so for
408.Fn EC_POINT_point2oct
409and
410.Fn EC_POINT_oct2point .
411Due to fundamental misdesign in the EC library,
412points are not directly linked to the curve they live on.
413Adding checks that
414.Fa point
415lives on
416.Fa group
417is too expensive and intrusive, so it is and will continue to be easy
418to make the EC_POINT_point2* API output nonsense.
419.Pp
420.Fn EC_POINT_point2bn
421and
422.Fn EC_POINT_bn2point
423make no sense.
424They abuse
425.Vt BIGNUM
426as a vector type, which is in poor taste.
427.Pp
428.Fn EC_POINT_point2hex
429and
430.Fn EC_POINT_hex2point
431use a non-standard encoding format.
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 9f3d448432..b8dfe86d49 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.307 2025/03/08 17:12:55 tb Exp $ 1# $OpenBSD: Makefile,v 1.308 2025/04/25 19:57:12 tb Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -133,12 +133,16 @@ MAN= \
133 DSA_size.3 \ 133 DSA_size.3 \
134 ECDH_compute_key.3 \ 134 ECDH_compute_key.3 \
135 ECDSA_SIG_new.3 \ 135 ECDSA_SIG_new.3 \
136 EC_GROUP_copy.3 \ 136 EC_GROUP_check.3 \
137 EC_GROUP_new.3 \ 137 EC_GROUP_get_curve_name.3 \
138 EC_GROUP_new_by_curve_name.3 \
139 EC_GROUP_new_curve_GFp.3 \
138 EC_KEY_METHOD_new.3 \ 140 EC_KEY_METHOD_new.3 \
139 EC_KEY_new.3 \ 141 EC_KEY_new.3 \
140 EC_POINT_add.3 \ 142 EC_POINT_add.3 \
143 EC_POINT_get_affine_coordinates.3 \
141 EC_POINT_new.3 \ 144 EC_POINT_new.3 \
145 EC_POINT_point2oct.3 \
142 ENGINE_new.3 \ 146 ENGINE_new.3 \
143 ERR.3 \ 147 ERR.3 \
144 ERR_GET_LIB.3 \ 148 ERR_GET_LIB.3 \
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-30 10:50:48 +0000