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