Debian Codegraph @

upstream/debian-unstable/man3/EC_GROUP_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EC_GROUP_NEW 3SSL"
58 .TH EC_GROUP_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EC_GROUP_get_ecparameters,
65 EC_GROUP_get_ecpkparameters,
66 EC_GROUP_new_from_params,
67 EC_GROUP_to_params,
68 EC_GROUP_new_from_ecparameters,
69 EC_GROUP_new_from_ecpkparameters,
70 EC_GROUP_new,
71 EC_GROUP_free,
72 EC_GROUP_clear_free,
73 EC_GROUP_new_curve_GFp,
74 EC_GROUP_new_curve_GF2m,
75 EC_GROUP_new_by_curve_name_ex,
76 EC_GROUP_new_by_curve_name,
77 EC_GROUP_set_curve,
78 EC_GROUP_get_curve,
79 EC_GROUP_set_curve_GFp,
80 EC_GROUP_get_curve_GFp,
81 EC_GROUP_set_curve_GF2m,
82 EC_GROUP_get_curve_GF2m,
83 EC_get_builtin_curves,
84 OSSL_EC_curve_nid2name \-
85 Functions for creating and destroying EC_GROUP objects
86 .SH SYNOPSIS
87 .IX Header "SYNOPSIS"
88 .Vb 1
89 \& #include <openssl/ec.h>
90 \&
91 \& EC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[],
92 \& OSSL_LIB_CTX *libctx, const char *propq);
93 \& OSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx,
94 \& const char *propq, BN_CTX *bnctx);
95 \& EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params);
96 \& EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params);
97 \& void EC_GROUP_free(EC_GROUP *group);
98 \&
99 \& EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
100 \& const BIGNUM *b, BN_CTX *ctx);
101 \& EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
102 \& const BIGNUM *b, BN_CTX *ctx);
103 \& EC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq,
104 \& int nid);
105 \& EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
106 \&
107 \& int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
108 \& const BIGNUM *b, BN_CTX *ctx);
109 \& int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,
110 \& BN_CTX *ctx);
111 \&
112 \& ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group,
113 \& ECPARAMETERS *params);
114 \& ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group,
115 \& ECPKPARAMETERS *params);
116 \&
117 \& size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
118 \& const char *OSSL_EC_curve_nid2name(int nid);
119 .Ve
120 .PP
121 The following functions have been deprecated since OpenSSL 3.0, and can be
122 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
123 see \fBopenssl_user_macros\fR\|(7):
124 .PP
125 .Vb 2
126 \& EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
127 \& void EC_GROUP_clear_free(EC_GROUP *group);
128 \&
129 \& int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,
130 \& const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
131 \& int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,
132 \& BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
133 \& int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,
134 \& const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
135 \& int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,
136 \& BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
137 .Ve
138 .SH DESCRIPTION
139 .IX Header "DESCRIPTION"
140 Within the library there are two forms of elliptic curve that are of interest.
141 The first form is those defined over the prime field Fp. The elements of Fp are
142 the integers 0 to p\-1, where p is a prime number. This gives us a revised
143 elliptic curve equation as follows:
144 .PP
145 y^2 mod p = x^3 +ax + b mod p
146 .PP
147 The second form is those defined over a binary field F2^m where the elements of
148 the field are integers of length at most m bits. For this form the elliptic
149 curve equation is modified to:
150 .PP
151 y^2 + xy = x^3 + ax^2 + b (where b != 0)
152 .PP
153 Operations in a binary field are performed relative to an
154 \&\fBirreducible polynomial\fR. All such curves with OpenSSL use a trinomial or a
155 pentanomial for this parameter.
156 .PP
157 Although deprecated since OpenSSL 3.0 and should no longer be used,
158 a new curve can be constructed by calling \fBEC_GROUP_new()\fR, using the
159 implementation provided by \fImeth\fR (see \fBEC_GFp_simple_method\fR\|(3)) and
160 associated with the library context \fIctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)).
161 The \fIctx\fR parameter may be NULL in which case the default library context is
162 used.
163 It is then necessary to call \fBEC_GROUP_set_curve()\fR to set the curve parameters.
164 Applications should instead use one of the other EC_GROUP_new_* constructors.
165 .PP
166 \&\fBEC_GROUP_new_from_params()\fR creates a group with parameters specified by \fIparams\fR.
167 The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and property query string
168 \&\fIpropq\fR are used to fetch algorithms from providers.
169 \&\fIparams\fR may be either a list of explicit params or a named group,
170 The values for \fIctx\fR and \fIpropq\fR may be NULL.
171 The \fIparams\fR that can be used are described in
172 \&\fBEVP_PKEY\-EC\fR(7).
173 .PP
174 EC_GROUP_to_params creates an OSSL_PARAM array with the corresponding parameters
175 describing the given EC_GROUP. The resulting parameters may contain parameters
176 describing a named or explicit curve depending on the EC_GROUP.
177 The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and property query string
178 \&\fIpropq\fR are used to fetch algorithms from providers.
179 \&\fIbnctx\fR is an optional preallocated BN_CTX (to save the overhead of allocating
180 and freeing the structure in a loop).
181 The values for \fIlibctx\fR, \fIpropq\fR and \fIbnctx\fR may be NULL.
182 The caller is responsible for freeing the OSSL_PARAM pointer returned.
183 .PP
184 \&\fBEC_GROUP_new_from_ecparameters()\fR will create a group from the
185 specified \fIparams\fR and
186 \&\fBEC_GROUP_new_from_ecpkparameters()\fR will create a group from the specific PK
187 \&\fIparams\fR.
188 .PP
189 \&\fBEC_GROUP_set_curve()\fR sets the curve parameters \fIp\fR, \fIa\fR and \fIb\fR. For a curve
190 over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR represents
191 the irreducible polynomial \- each bit represents a term in the polynomial.
192 Therefore, there will either be three or five bits set dependent on whether the
193 polynomial is a trinomial or a pentanomial.
194 In either case, \fIa\fR and \fIb\fR represents the coefficients a and b from the
195 relevant equation introduced above.
196 .PP
197 \&\fBEC_group_get_curve()\fR obtains the previously set curve parameters.
198 .PP
199 \&\fBEC_GROUP_set_curve_GFp()\fR and \fBEC_GROUP_set_curve_GF2m()\fR are synonyms for
200 \&\fBEC_GROUP_set_curve()\fR. They are defined for backwards compatibility only and
201 should not be used.
202 .PP
203 \&\fBEC_GROUP_get_curve_GFp()\fR and \fBEC_GROUP_get_curve_GF2m()\fR are synonyms for
204 \&\fBEC_GROUP_get_curve()\fR. They are defined for backwards compatibility only and
205 should not be used.
206 .PP
207 The functions \fBEC_GROUP_new_curve_GFp()\fR and \fBEC_GROUP_new_curve_GF2m()\fR are
208 shortcuts for calling \fBEC_GROUP_new()\fR and then the \fBEC_GROUP_set_curve()\fR function.
209 An appropriate default implementation method will be used.
210 .PP
211 Whilst the library can be used to create any curve using the functions described
212 above, there are also a number of predefined curves that are available. In order
213 to obtain a list of all of the predefined curves, call the function
214 \&\fBEC_get_builtin_curves()\fR. The parameter \fIr\fR should be an array of
215 EC_builtin_curve structures of size \fInitems\fR. The function will populate the
216 \&\fIr\fR array with information about the built-in curves. If \fInitems\fR is less than
217 the total number of curves available, then the first \fInitems\fR curves will be
218 returned. Otherwise the total number of curves will be provided. The return
219 value is the total number of curves available (whether that number has been
220 populated in \fIr\fR or not). Passing a NULL \fIr\fR, or setting \fInitems\fR to 0 will
221 do nothing other than return the total number of curves available.
222 The EC_builtin_curve structure is defined as follows:
223 .PP
224 .Vb 4
225 \& typedef struct {
226 \& int nid;
227 \& const char *comment;
228 \& } EC_builtin_curve;
229 .Ve
230 .PP
231 Each EC_builtin_curve item has a unique integer id (\fInid\fR), and a human
232 readable comment string describing the curve.
233 .PP
234 In order to construct a built-in curve use the function
235 \&\fBEC_GROUP_new_by_curve_name_ex()\fR and provide the \fInid\fR of the curve to
236 be constructed, the associated library context to be used in \fIctx\fR (see
237 \&\fBOSSL_LIB_CTX\fR\|(3)) and any property query string in \fIpropq\fR. The \fIctx\fR value
238 may be NULL in which case the default library context is used. The \fIpropq\fR
239 value may also be NULL.
240 .PP
241 \&\fBEC_GROUP_new_by_curve_name()\fR is the same as
242 \&\fBEC_GROUP_new_by_curve_name_ex()\fR except that the default library context
243 is always used along with a NULL property query string.
244 .PP
245 \&\fBEC_GROUP_free()\fR frees the memory associated with the EC_GROUP.
246 If \fIgroup\fR is NULL nothing is done.
247 .PP
248 \&\fBEC_GROUP_clear_free()\fR is deprecated: it was meant to destroy any sensitive data
249 held within the EC_GROUP and then free its memory, but since all the data stored
250 in the EC_GROUP is public anyway, this function is unnecessary.
251 Its use can be safely replaced with \fBEC_GROUP_free()\fR.
252 If \fIgroup\fR is NULL nothing is done.
253 .PP
254 \&\fBOSSL_EC_curve_nid2name()\fR converts a curve \fInid\fR into the corresponding name.
255 .SH "RETURN VALUES"
256 .IX Header "RETURN VALUES"
257 All EC_GROUP_new* functions return a pointer to the newly constructed group, or
258 NULL on error.
259 .PP
260 \&\fBEC_get_builtin_curves()\fR returns the number of built-in curves that are
261 available.
262 .PP
263 \&\fBEC_GROUP_set_curve_GFp()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR,
264 \&\fBEC_GROUP_get_curve_GF2m()\fR return 1 on success or 0 on error.
265 .PP
266 \&\fBOSSL_EC_curve_nid2name()\fR returns a character string constant, or NULL on error.
267 .SH "SEE ALSO"
268 .IX Header "SEE ALSO"
269 \&\fBcrypto\fR\|(7), \fBEC_GROUP_copy\fR\|(3),
270 \&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3),
271 \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3),
272 \&\fBOSSL_LIB_CTX\fR\|(3), \fBEVP_PKEY\-EC\fR\|(7)
273 .SH HISTORY
274 .IX Header "HISTORY"
275 \&\fBEC_GROUP_to_params()\fR was added in OpenSSL 3.2.
276 .IP \(bu 2
277 \&\fBEC_GROUP_new()\fR was deprecated in OpenSSL 3.0.
278 .Sp
279 \&\fBEC_GROUP_new_by_curve_name_ex()\fR and \fBEC_GROUP_new_from_params()\fR were
280 added in OpenSSL 3.0.
281 .IP \(bu 2
282 \&\fBEC_GROUP_clear_free()\fR was deprecated in OpenSSL 3.0; use \fBEC_GROUP_free()\fR
283 instead.
284 .IP \(bu 2
285
286 .Sp
287 .Vb 3
288 \& EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(),
289 \& EC_GROUP_set_curve_GF2m() and EC_GROUP_get_curve_GF2m() were deprecated in
290 \& OpenSSL 3.0; use EC_GROUP_set_curve() and EC_GROUP_get_curve() instead.
291 .Ve
292 .SH COPYRIGHT
293 .IX Header "COPYRIGHT"
294 Copyright 2013\-2024 The OpenSSL Project Authors. All Rights Reserved.
295 .PP
296 Licensed under the Apache License 2.0 (the "License"). You may not use
297 this file except in compliance with the License. You can obtain a copy
298 in the file LICENSE in the source distribution or at
299 <https://www.openssl.org/source/license.html>.