xref: /openbsd-src/lib/libcrypto/man/EC_GROUP_new.3 (revision 4e1ee0786f11cc571bd0be17d38e46f635c719fc)
1.\"	$OpenBSD: EC_GROUP_new.3,v 1.13 2021/05/11 04:22:32 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: May 11 2021 $
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_curve_GF2m ,
60.Nm EC_GROUP_new_by_curve_name ,
61.Nm EC_GROUP_set_curve ,
62.Nm EC_GROUP_get_curve ,
63.Nm EC_GROUP_set_curve_GFp ,
64.Nm EC_GROUP_get_curve_GFp ,
65.Nm EC_GROUP_set_curve_GF2m ,
66.Nm EC_GROUP_get_curve_GF2m ,
67.Nm EC_get_builtin_curves
68.Nd create and destroy EC_GROUP objects
69.Sh SYNOPSIS
70.In openssl/ec.h
71.In openssl/bn.h
72.Ft EC_GROUP *
73.Fo EC_GROUP_new
74.Fa "const EC_METHOD *meth"
75.Fc
76.Ft void
77.Fo EC_GROUP_free
78.Fa "EC_GROUP *group"
79.Fc
80.Ft void
81.Fo EC_GROUP_clear_free
82.Fa "EC_GROUP *group"
83.Fc
84.Ft EC_GROUP *
85.Fo EC_GROUP_new_curve_GFp
86.Fa "const BIGNUM *p"
87.Fa "const BIGNUM *a"
88.Fa "const BIGNUM *b"
89.Fa "BN_CTX *ctx"
90.Fc
91.Ft EC_GROUP *
92.Fo EC_GROUP_new_curve_GF2m
93.Fa "const BIGNUM *p"
94.Fa "const BIGNUM *a"
95.Fa "const BIGNUM *b"
96.Fa "BN_CTX *ctx"
97.Fc
98.Ft EC_GROUP *
99.Fo EC_GROUP_new_by_curve_name
100.Fa "int nid"
101.Fc
102.Ft int
103.Fo EC_GROUP_set_curve
104.Fa "EC_GROUP *group"
105.Fa "const BIGNUM *p"
106.Fa "const BIGNUM *a"
107.Fa "const BIGNUM *b"
108.Fa "BN_CTX *ctx"
109.Fc
110.Ft int
111.Fo EC_GROUP_get_curve
112.Fa "const EC_GROUP *group"
113.Fa "BIGNUM *p"
114.Fa "BIGNUM *a"
115.Fa "BIGNUM *b"
116.Fa "BN_CTX *ctx"
117.Fc
118.Ft int
119.Fo EC_GROUP_set_curve_GFp
120.Fa "EC_GROUP *group"
121.Fa "const BIGNUM *p"
122.Fa "const BIGNUM *a"
123.Fa "const BIGNUM *b"
124.Fa "BN_CTX *ctx"
125.Fc
126.Ft int
127.Fo EC_GROUP_get_curve_GFp
128.Fa "const EC_GROUP *group"
129.Fa "BIGNUM *p"
130.Fa "BIGNUM *a"
131.Fa "BIGNUM *b"
132.Fa "BN_CTX *ctx"
133.Fc
134.Ft int
135.Fo EC_GROUP_set_curve_GF2m
136.Fa "EC_GROUP *group"
137.Fa "const BIGNUM *p"
138.Fa "const BIGNUM *a"
139.Fa "const BIGNUM *b"
140.Fa "BN_CTX *ctx"
141.Fc
142.Ft int
143.Fo EC_GROUP_get_curve_GF2m
144.Fa "const EC_GROUP *group"
145.Fa "BIGNUM *p"
146.Fa "BIGNUM *a"
147.Fa "BIGNUM *b"
148.Fa "BN_CTX *ctx"
149.Fc
150.Ft size_t
151.Fo EC_get_builtin_curves
152.Fa "EC_builtin_curve *r"
153.Fa "size_t nitems"
154.Fc
155.Sh DESCRIPTION
156The EC library provides functions for performing operations on
157elliptic curves over finite fields.
158In general, an elliptic curve satisfies an equation of the form:
159.Pp
160.Dl y^2 = x^3 + ax + b
161.Pp
162Within the library there are two forms of elliptic curves that are of
163interest.
164The first form is those defined over the prime field Fp.
165The elements of Fp are the integers 0 to p-1, where
166.Fa p
167is a prime number.
168This gives us a revised elliptic curve equation as follows:
169.Pp
170.Dl y^2 mod p = x^3 + ax + b mod p
171.Pp
172The second form is those defined over a binary field F2^m where the
173elements of the field are integers of length at most m bits.
174For this form the elliptic curve equation is modified to:
175.Pp
176.Dl y^2 + xy = x^3 + ax^2 + b (where b != 0)
177.Pp
178Operations in a binary field are performed relative to an irreducible
179polynomial.
180All such curves with OpenSSL use a trinomial or a pentanomial for this
181parameter.
182.Pp
183An
184.Vt EC_GROUP
185structure is used to represent the definition of an elliptic curve.
186A new curve can be constructed by calling
187.Fn EC_GROUP_new ,
188using the implementation provided by
189.Fa meth
190(see
191.Xr EC_GFp_simple_method 3 ) .
192It is then necessary to call
193.Fn EC_GROUP_set_curve
194to set the curve parameters.
195.Pp
196.Fn EC_GROUP_set_curve
197sets the curve parameters
198.Fa p ,
199.Fa a ,
200and
201.Fa b .
202For a curve over Fp,
203.Fa p
204is the prime for the field.
205For a curve over F2^m
206.Fa p
207represents the irreducible polynomial - each bit represents a term in
208the polynomial.
209Therefore, there will either be three or five bits set dependent on
210whether the polynomial is a trinomial or a pentanomial.
211In either case,
212.Fa a
213and
214.Fa b
215represent the coefficients of the curve equation.
216.Pp
217.Fn EC_GROUP_set_curve_GFp
218and
219.Fn EC_GROUP_set_curve_GF2m
220are deprecated synonyms for
221.Fn EC_GROUP_set_curve .
222.Pp
223.Fn EC_GROUP_get_curve
224obtains the previously set curve parameters.
225.Pp
226.Fn EC_GROUP_get_curve_GFp
227and
228.Fn EC_GROUP_get_curve_GF2m
229are deprecated synonyms for
230.Fn EC_GROUP_get_curve .
231.Pp
232The functions
233.Fn EC_GROUP_new_curve_GFp
234and
235.Fn EC_GROUP_new_curve_GF2m
236are shortcuts for calling
237.Fn EC_GROUP_new
238and the appropriate
239.Fn EC_GROUP_set_curve_*
240function.
241An appropriate default implementation method will be used.
242.Pp
243Whilst the library can be used to create any curve using the functions
244described above, there are also a number of predefined curves that are
245available.
246In order to obtain a list of all of the predefined curves, call the
247function
248.Fn EC_get_builtin_curves .
249The parameter
250.Fa r
251should be an array of
252.Vt EC_builtin_cure
253structures of size
254.Fa nitems .
255The function will populate the
256.Fa r
257array with information about the builtin curves.
258If
259.Fa nitems
260is less than the total number of curves available, then the first
261.Fa nitems
262curves will be returned.
263Otherwise the total number of curves will be provided.
264The return value is the total number of curves available (whether that
265number has been populated in
266.Fa r
267or not).
268Passing a
269.Dv NULL
270.Fa r ,
271or setting
272.Fa nitems
273to 0, will do nothing other than return the total number of curves
274available.
275The
276.Vt EC_builtin_curve
277structure is defined as follows:
278.Bd -literal
279typedef struct {
280	int nid;
281	const char *comment;
282} EC_builtin_curve;
283.Ed
284.Pp
285Each
286.Vt EC_builtin_curve
287item has a unique integer ID
288.Pq Fa nid
289and a human readable comment string describing the curve.
290.Pp
291In order to construct a builtin curve use the function
292.Fn EC_GROUP_new_by_curve_name
293and provide the
294.Fa nid
295of the curve to be constructed.
296.Pp
297.Fn EC_GROUP_free
298frees the memory associated with the
299.Vt EC_GROUP .
300If
301.Fa group
302is a
303.Dv NULL
304pointer, no action occurs.
305.Pp
306.Fn EC_GROUP_clear_free
307destroys any sensitive data held within the
308.Vt EC_GROUP
309and then frees its memory.
310If
311.Fa group
312is a
313.Dv NULL
314pointer, no action occurs.
315.Sh RETURN VALUES
316All
317.Fn EC_GROUP_new*
318functions return a pointer to the newly constructed group or
319.Dv NULL
320on error.
321.Pp
322.Fn EC_get_builtin_curves
323returns the number of builtin curves that are available.
324.Pp
325.Fn EC_GROUP_set_curve ,
326.Fn EC_GROUP_get_curve ,
327.Fn EC_GROUP_set_curve_GFp ,
328.Fn EC_GROUP_get_curve_GFp ,
329.Fn EC_GROUP_set_curve_GF2m ,
330and
331.Fn EC_GROUP_get_curve_GF2m
332return 1 on success or 0 on error.
333.Sh SEE ALSO
334.Xr crypto 3 ,
335.Xr d2i_ECPKParameters 3 ,
336.Xr EC_GFp_simple_method 3 ,
337.Xr EC_GROUP_copy 3 ,
338.Xr EC_KEY_new 3 ,
339.Xr EC_POINT_add 3 ,
340.Xr EC_POINT_new 3 ,
341.Xr ECDH_compute_key 3 ,
342.Xr ECDSA_SIG_new 3
343.Sh HISTORY
344.Fn EC_GROUP_new ,
345.Fn EC_GROUP_free ,
346.Fn EC_GROUP_clear_free ,
347.Fn EC_GROUP_new_curve_GFp ,
348.Fn EC_GROUP_set_curve_GFp ,
349and
350.Fn EC_GROUP_get_curve_GFp
351first appeared in OpenSSL 0.9.7 and have been available since
352.Ox 3.2 .
353.Pp
354.Fn EC_GROUP_new_curve_GF2m ,
355.Fn EC_GROUP_new_by_curve_name ,
356.Fn EC_GROUP_set_curve_GF2m ,
357.Fn EC_GROUP_get_curve_GF2m ,
358and
359.Fn EC_get_builtin_curves
360first appeared in OpenSSL 0.9.8 and have been available since
361.Ox 4.5 .
362.Fn EC_GROUP_set_curve
363and
364.Fn EC_GROUP_get_curve
365first appeared in OpenSSL 1.1.1 and have been available since
366.Ox 7.0 .
367