summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EC_GROUP_new.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/EC_GROUP_new.3353
1 files changed, 0 insertions, 353 deletions
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 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 22:58:33 +0000