summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3')
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3458
1 files changed, 458 insertions, 0 deletions
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..038deff434
--- /dev/null
+++ b/src/lib/libcrypto/man/EC_GROUP_new_curve_GFp.3
@@ -0,0 +1,458 @@
1.\" $OpenBSD: EC_GROUP_new_curve_GFp.3,v 1.5 2025/06/13 18:34:00 schwarze 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: June 13 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.Lb libcrypto
36.In openssl/bn.h
37.In openssl/ec.h
38.Ft EC_GROUP *
39.Fo EC_GROUP_new_curve_GFp
40.Fa "const BIGNUM *p"
41.Fa "const BIGNUM *a"
42.Fa "const BIGNUM *b"
43.Fa "BN_CTX *ctx"
44.Fc
45.Ft int
46.Fo EC_GROUP_set_curve
47.Fa "EC_GROUP *group"
48.Fa "const BIGNUM *p"
49.Fa "const BIGNUM *a"
50.Fa "const BIGNUM *b"
51.Fa "BN_CTX *ctx"
52.Fc
53.Ft int
54.Fo EC_GROUP_get_curve
55.Fa "const EC_GROUP *group"
56.Fa "BIGNUM *p"
57.Fa "BIGNUM *a"
58.Fa "BIGNUM *b"
59.Fa "BN_CTX *ctx"
60.Fc
61.Ft int
62.Fo EC_GROUP_set_generator
63.Fa "EC_GROUP *group"
64.Fa "const EC_POINT *generator"
65.Fa "const BIGNUM *order"
66.Fa "const BIGNUM *cofactor"
67.Fc
68.Ft const EC_POINT *
69.Fo EC_GROUP_get0_generator
70.Fa "const EC_GROUP *group"
71.Fc
72.Ft int
73.Fo EC_GROUP_get_degree
74.Fa "const EC_GROUP *"
75.Fc
76.Ft int
77.Fo EC_GROUP_get_order
78.Fa "const EC_GROUP *group"
79.Fa "BIGNUM *order"
80.Fa "BN_CTX *ctx"
81.Fc
82.Ft int
83.Fo EC_GROUP_order_bits
84.Fa "const EC_GROUP *group"
85.Fc
86.Ft int
87.Fo EC_GROUP_get_cofactor
88.Fa "const EC_GROUP *group"
89.Fa "BIGNUM *cofactor"
90.Fa "BN_CTX *ctx"
91.Fc
92.Pp
93Deprecated:
94.Pp
95.Ft void
96.Fo EC_GROUP_clear_free
97.Fa "EC_GROUP *group"
98.Fc
99.Ft int
100.Fo EC_GROUP_set_curve_GFp
101.Fa "EC_GROUP *group"
102.Fa "const BIGNUM *p"
103.Fa "const BIGNUM *a"
104.Fa "const BIGNUM *b"
105.Fa "BN_CTX *ctx"
106.Fc
107.Ft int
108.Fo EC_GROUP_get_curve_GFp
109.Fa "const EC_GROUP *group"
110.Fa "BIGNUM *p"
111.Fa "BIGNUM *a"
112.Fa "BIGNUM *b"
113.Fa "BN_CTX *ctx"
114.Fc
115.Sh DESCRIPTION
116With the exception of the getters
117the functions in this manual should not be used.
118Use
119.Xr EC_GROUP_new_by_curve_name 3
120instead.
121.Pp
122The EC library uses
123.Vt EC_GROUP
124objects to represent
125elliptic curves in Weierstrass form.
126These curves are defined over the prime field of order
127.Fa p
128via the Weierstrass equation
129.Pp
130.Dl y^2 = x^3 + ax + b
131.Pp
132where
133.Fa a
134and
135.Fa b
136are such that the discriminant 4a^3 - 27b^2 is non-zero.
137.Pp
138The points on an elliptic curve form a group.
139Cryptographic applications usually depend on the choice of a
140.Fa generator
141whose multiples form a cyclic subgroup of a certain
142.Fa order .
143By Lagrange's theorem, the number of points on the elliptic curve is
144the product of
145.Fa order
146and another integer called the
147.Fa cofactor .
148Hasse's theorem is the inequality
149.Pp
150.Dl | Ns Fa order No * Fa cofactor No - (p + 1)| <= 2 sqrt(p)
151.Pp
152which implies an upper bound on
153.Fa order
154in terms of
155.Fa p
156and allows the computation of
157.Fa cofactor
158provided that
159.Fa order
160is large enough.
161.Pp
162.Fn EC_GROUP_new_curve_GFp
163instantiates a new
164.Vt EC_GROUP
165object over the prime field of size
166.Fa p
167with Weierstrass equation given by the coefficients
168.Fa a
169and
170.Fa b .
171The optional
172.Fa ctx
173is used to transform the other arguments into internal representation.
174It is the caller's responsibility to ensure that
175.Fa p
176is a prime number greater than three and that
177the discriminant is non-zero.
178This can be done with
179.Xr EC_GROUP_check_discriminant 3
180or as part of
181.Xr EC_GROUP_check 3
182after
183.Fn EC_GROUP_set_generator .
184.Pp
185.Fn EC_GROUP_set_curve
186sets the curve parameters of
187.Fa group
188to
189.Fa p ,
190.Fa a ,
191.Fa b
192using the optional
193.Fa ctx
194and the comments in
195.Fn EC_GROUP_new_curve_GFp
196apply.
197Existing
198.Fa generator ,
199.Fa order ,
200or
201.Fa cofactor
202on
203.Fa group
204are left unmodified and become most likely invalid.
205They must therefore be set to legitimate values using
206.Fn EC_GROUP_set_generator .
207.Pp
208.Fn EC_GROUP_get_curve
209copies the curve parameters of
210.Fa group
211into the caller-owned
212.Fa p ,
213.Fa a ,
214and
215.Fa b ,
216possibly making use of the
217.Fa ctx
218for conversion from internal representations.
219Except for
220.Fa group ,
221all arguments are optional.
222.Pp
223.Fn EC_GROUP_set_generator
224performs sanity checks based on Hasse's theorem
225and copies
226.Fa generator ,
227.Fa order
228and the optional
229.Fa cofactor
230into
231.Fa group ,
232replacing all existing entries.
233It is the caller's responsibility to ensure that
234.Fa generator
235is a point on the curve and that
236.Fa order
237is its order,
238which can partially be accomplished with a subsequent call to
239.Xr EC_GROUP_check 3 .
240If
241.Fa cofactor
242is
243.Dv NULL ,
244it can be computed on curves of cryptographic interest,
245in which case
246.Fa cofactor
247is set to the computed value, otherwise it is set to zero.
248.Pp
249.Fn EC_GROUP_get0_generator
250returns an internal pointer to the
251.Fa group Ns 's
252.Fa generator ,
253which may be
254.Dv NULL
255if no generator was set.
256.Pp
257.Fn EC_GROUP_get_degree
258returns the bit length of the prime
259.Fa p
260set on
261.Fa group .
262.Pp
263.Fn EC_GROUP_get_order
264copies the value of the
265.Fa group Ns 's
266.Fa order
267into the caller-owned
268.Fa order ,
269returning failure if the
270.Fa group Ns 's
271.Fa order
272is zero.
273The
274.Fa ctx
275argument is ignored.
276.Pp
277.Fn EC_GROUP_order_bits
278returns the number of bits in the
279.Fa group Ns 's
280.Fa order ,
281which is the result of calling
282.Xr BN_num_bits 3
283on
284.Fa order .
285Unlike
286.Fn EC_GROUP_get_order ,
287it does not fail if
288.Fa order
289is zero.
290.Pp
291.Fn EC_GROUP_get_cofactor
292copies the value of the
293.Fa group Ns 's
294.Fa cofactor
295into the caller-owned
296.Fa cofactor ,
297returning failure if the
298.Fa group Ns 's
299.Fa cofactor
300is zero.
301The
302.Fa ctx
303argument is ignored.
304.Pp
305The deprecated
306.Fn EC_GROUP_clear_free
307uses
308.Xr explicit_bzero 3
309and
310.Xr freezero 3
311to clear and free all data associated with
312.Fa group .
313If
314.Fa group
315is
316.Dv NULL ,
317no action occurs.
318Since there is no secret data in
319.Fa group ,
320this API is useless.
321In LibreSSL,
322.Xr EC_GROUP_free 3
323and
324.Fn EC_GROUP_clear_free
325behave identically.
326.Pp
327.Fn EC_GROUP_set_curve_GFp
328and
329.Fn EC_GROUP_get_curve_GFp
330are deprecated aliases for
331.Fn EC_GROUP_set_curve
332and
333.Fn EC_GROUP_get_curve ,
334respectively.
335.Sh RETURN VALUES
336.Fn EC_GROUP_new_curve_GFp
337returns a newly allocated group or
338.Dv NULL
339if memory allocation fails,
340or if some minimal sanity checks on
341.Fa p ,
342.Fa a ,
343and
344.Fa b
345fail.
346.Pp
347.Fn EC_GROUP_set_curve
348and
349.Fn EC_GROUP_set_curve_GFp
350return 1 on success and 0 on failure.
351Failure conditions include that
352.Fa p
353is smaller than or equal to three, or even, or
354memory allocation failure.
355.Pp
356.Fn EC_GROUP_get_curve
357and
358.Fn EC_GROUP_get_curve_GFp
359return 1 on success and 0 on memory allocation failure.
360.Pp
361.Fn EC_GROUP_set_generator
362returns 1 on success and 0 on memory allocation failure, or if
363.Fa order
364or
365.Fa cofactor
366are larger than Hasse's theorem allows.
367.Pp
368.Fn EC_GROUP_get0_generator
369returns an internal pointer to the
370.Fa generator
371or
372.Dv NULL
373if none was set on
374.Fa group .
375.Pp
376.Fn EC_GROUP_get_order
377returns 1 on success or 0 on memory allocation failure or if the
378.Fa order
379is zero.
380.Pp
381.Fn EC_GROUP_get_cofactor
382returns 1 on success or 0 on memory allocation failure or if the
383.Fa cofactor
384is zero.
385.Pp
386.Fn EC_GROUP_get_degree ,
387and
388.Fn EC_GROUP_order_bits
389return the number of bits in the
390.Fa group Ns 's
391.Fa p ,
392and
393.Fa order ,
394respectively.
395.Sh SEE ALSO
396.Xr BN_new 3 ,
397.Xr BN_num_bits 3 ,
398.Xr crypto 3 ,
399.Xr d2i_ECPKParameters 3 ,
400.Xr EC_GROUP_check 3 ,
401.Xr EC_GROUP_get_curve_name 3 ,
402.Xr EC_GROUP_new_by_curve_name 3 ,
403.Xr EC_KEY_METHOD_new 3 ,
404.Xr EC_KEY_new 3 ,
405.Xr EC_POINT_add 3 ,
406.Xr EC_POINT_get_affine_coordinates 3 ,
407.Xr EC_POINT_new 3 ,
408.Xr EC_POINT_point2oct 3 ,
409.Xr ECDH_compute_key 3 ,
410.Xr ECDSA_SIG_new 3
411.Sh STANDARDS
412.Rs
413.%T SEC 1: Elliptic Curve Cryptography, Version 2.0
414.%U https://www.secg.org/sec1-v2.pdf
415.%D May 21, 2009
416.Re
417.Pp
418.Rs
419.%T SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0
420.%U https://www.secg.org/sec2-v2.pdf
421.%D Jan 27, 2010
422.Re
423.Sh HISTORY
424.Fn EC_GROUP_new_curve_GFp ,
425.Fn EC_GROUP_clear_free ,
426.Fn EC_GROUP_set_curve_GFp ,
427.Fn EC_GROUP_get_curve_GFp ,
428.Fn EC_GROUP_set_generator ,
429.Fn EC_GROUP_get0_generator ,
430.Fn EC_GROUP_get_order ,
431and
432.Fn EC_GROUP_get_cofactor
433first appeared in OpenSSL 0.9.7 and
434have been available since
435.Ox 3.2 .
436.Pp
437.Fn EC_GROUP_get_degree
438first appeared in OpenSSL 0.9.8 and
439has been available since
440.Ox 4.5 .
441.Pp
442.Fn EC_GROUP_set_curve ,
443.Fn EC_GROUP_get_curve ,
444and
445.Fn EC_GROUP_order_bits
446first appeared in OpenSSL 1.1.1 and
447have been available since
448.Ox 7.0
449.Sh BUGS
450Too many.
451The API is unergonomic and the design is very poor even by
452OpenSSL's standards.
453Naming is inconsistent, especially in regard to the _GFp suffix
454and the _get_ infix.
455Function signatures are inconsistent.
456In particular, functions that should have a
457.Vt BN_CTX
458argument don't have one and functions that don't need it have one.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-14 11:45:11 +0000