Debian Codegraph @

upstream/debian-unstable/man3/EC_KEY_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_KEY_NEW 3SSL"
58 .TH EC_KEY_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 EVP_EC_gen,
65 EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex,
66 EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
67 EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free,
68 EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine,
69 EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key,
70 EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key,
71 EC_KEY_get_conv_form,
72 EC_KEY_set_conv_form, EC_KEY_set_asn1_flag,
73 EC_KEY_decoded_from_explicit_params, EC_KEY_precompute_mult,
74 EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates,
75 EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct,
76 EC_KEY_priv2buf \- Functions for creating, destroying and manipulating
77 EC_KEY objects
78 .SH SYNOPSIS
79 .IX Header "SYNOPSIS"
80 .Vb 1
81 \& #include <openssl/ec.h>
82 \&
83 \& EVP_PKEY *EVP_EC_gen(const char *curve);
84 .Ve
85 .PP
86 The following functions have been deprecated since OpenSSL 3.0, and can be
87 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
88 see \fBopenssl_user_macros\fR\|(7):
89 .PP
90 .Vb 10
91 \& EC_KEY *EC_KEY_new_ex(OSSL_LIB_CTX *ctx, const char *propq);
92 \& EC_KEY *EC_KEY_new(void);
93 \& int EC_KEY_get_flags(const EC_KEY *key);
94 \& void EC_KEY_set_flags(EC_KEY *key, int flags);
95 \& void EC_KEY_clear_flags(EC_KEY *key, int flags);
96 \& EC_KEY *EC_KEY_new_by_curve_name_ex(OSSL_LIB_CTX *ctx, const char *propq,
97 \& int nid);
98 \& EC_KEY *EC_KEY_new_by_curve_name(int nid);
99 \& void EC_KEY_free(EC_KEY *key);
100 \& EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
101 \& EC_KEY *EC_KEY_dup(const EC_KEY *src);
102 \& int EC_KEY_up_ref(EC_KEY *key);
103 \& ENGINE *EC_KEY_get0_engine(const EC_KEY *eckey);
104 \& const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
105 \& int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
106 \& const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
107 \& int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv_key);
108 \& const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
109 \& int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
110 \& point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
111 \& void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
112 \& void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
113 \& int EC_KEY_decoded_from_explicit_params(const EC_KEY *key);
114 \& int EC_KEY_generate_key(EC_KEY *key);
115 \& int EC_KEY_check_key(const EC_KEY *key);
116 \& int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);
117 \& const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);
118 \& int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);
119 \&
120 \& int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, BN_CTX *ctx);
121 \& size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form,
122 \& unsigned char **pbuf, BN_CTX *ctx);
123 \&
124 \& int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len);
125 \& size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len);
126 \&
127 \& size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);
128 \& int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
129 .Ve
130 .SH DESCRIPTION
131 .IX Header "DESCRIPTION"
132 \&\fBEVP_EC_gen()\fR generates a new EC key pair on the given \fIcurve\fR.
133 .PP
134 All of the functions described below are deprecated.
135 Applications should instead use \fBEVP_EC_gen()\fR, \fBEVP_PKEY_Q_keygen\fR\|(3), or
136 \&\fBEVP_PKEY_keygen_init\fR\|(3) and \fBEVP_PKEY_keygen\fR\|(3).
137 .PP
138 An EC_KEY represents a public key and, optionally, the associated private
139 key.
140 A new EC_KEY with no associated curve can be constructed by calling
141 \&\fBEC_KEY_new_ex()\fR and specifying the associated library context in \fIctx\fR
142 (see \fBOSSL_LIB_CTX\fR\|(3)) and property query string \fIpropq\fR.
143 The \fIctx\fR parameter may be NULL in which case the default library context is
144 used.
145 The reference count for the newly created EC_KEY is initially
146 set to 1.
147 A curve can be associated with the EC_KEY by calling
148 \&\fBEC_KEY_set_group()\fR.
149 .PP
150 \&\fBEC_KEY_new()\fR is the same as \fBEC_KEY_new_ex()\fR except that the default library
151 context is always used.
152 .PP
153 Alternatively a new EC_KEY can be constructed by calling
154 \&\fBEC_KEY_new_by_curve_name_ex()\fR and supplying the nid of the associated
155 curve, the library context to be used \fIctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and any
156 property query string \fIpropq\fR.
157 The \fIctx\fR parameter may be NULL in which case the default library context is
158 used. The \fIpropq\fR value may also be NULL.
159 See \fBEC_GROUP_new\fR\|(3) for a description of curve names.
160 This function simply wraps calls to \fBEC_KEY_new_ex()\fR and
161 \&\fBEC_GROUP_new_by_curve_name_ex()\fR.
162 .PP
163 \&\fBEC_KEY_new_by_curve_name()\fR is the same as \fBEC_KEY_new_by_curve_name_ex()\fR
164 except that the default library context is always used and a NULL property query
165 string.
166 .PP
167 Calling \fBEC_KEY_free()\fR decrements the reference count for the EC_KEY object,
168 and if it has dropped to zero then frees the memory associated with it. If
169 \&\fIkey\fR is NULL nothing is done.
170 .PP
171 \&\fBEC_KEY_copy()\fR copies the contents of the EC_KEY in \fIsrc\fR into \fIdest\fR.
172 .PP
173 \&\fBEC_KEY_dup()\fR creates a new EC_KEY object and copies \fIec_key\fR into it.
174 .PP
175 \&\fBEC_KEY_up_ref()\fR increments the reference count associated with the EC_KEY
176 object.
177 .PP
178 \&\fBEC_KEY_get0_engine()\fR returns a handle to the ENGINE that has been set for
179 this EC_KEY object.
180 .PP
181 \&\fBEC_KEY_generate_key()\fR generates a new public and private key for the supplied
182 \&\fIeckey\fR object. \fIeckey\fR must have an EC_GROUP object associated with it
183 before calling this function. The private key is a random integer (0 < priv_key
184 < order, where \fIorder\fR is the order of the EC_GROUP object). The public key is
185 an EC_POINT on the curve calculated by multiplying the generator for the
186 curve by the private key.
187 .PP
188 \&\fBEC_KEY_check_key()\fR performs various sanity checks on the EC_KEY object to
189 confirm that it is valid.
190 .PP
191 \&\fBEC_KEY_set_public_key_affine_coordinates()\fR sets the public key for \fIkey\fR based
192 on its affine coordinates; i.e., it constructs an EC_POINT object based on
193 the supplied \fIx\fR and \fIy\fR values and sets the public key to be this
194 EC_POINT. It also performs certain sanity checks on the key to confirm
195 that it is valid.
196 .PP
197 The functions \fBEC_KEY_get0_group()\fR, \fBEC_KEY_set_group()\fR,
198 \&\fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_get0_public_key()\fR,
199 and \fBEC_KEY_set_public_key()\fR get and set the EC_GROUP object, the private key,
200 and the EC_POINT public key for the \fBkey\fR respectively. The function
201 \&\fBEC_KEY_set_private_key()\fR accepts NULL as the priv_key argument to securely clear
202 the private key component from the EC_KEY.
203 .PP
204 The functions \fBEC_KEY_get_conv_form()\fR and \fBEC_KEY_set_conv_form()\fR get and set the
205 point_conversion_form for the \fIkey\fR. For a description of
206 point_conversion_forms please see \fBEC_POINT_new\fR\|(3).
207 .PP
208 \&\fBEC_KEY_set_flags()\fR sets the flags in the \fIflags\fR parameter on the EC_KEY
209 object. Any flags that are already set are left set. The flags currently
210 defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In
211 addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH.
212 \&\fBEC_KEY_get_flags()\fR returns the current flags that are set for this EC_KEY.
213 \&\fBEC_KEY_clear_flags()\fR clears the flags indicated by the \fIflags\fR parameter; all
214 other flags are left in their existing state.
215 .PP
216 \&\fBEC_KEY_set_asn1_flag()\fR sets the asn1_flag on the underlying EC_GROUP object
217 (if set). Refer to \fBEC_GROUP_copy\fR\|(3) for further information on the
218 asn1_flag.
219 .PP
220 \&\fBEC_KEY_decoded_from_explicit_params()\fR returns 1 if the group of the \fIkey\fR was
221 decoded from data with explicitly encoded group parameters, \-1 if the \fIkey\fR
222 is NULL or the group parameters are missing, and 0 otherwise.
223 .PP
224 \&\fBEC_KEY_precompute_mult()\fR stores multiples of the underlying EC_GROUP generator
225 for faster point multiplication. See also \fBEC_POINT_add\fR\|(3).
226 Modern versions should instead switch to named curves which OpenSSL has
227 hardcoded lookup tables for.
228 .PP
229 \&\fBEC_KEY_oct2key()\fR and \fBEC_KEY_key2buf()\fR are identical to the functions
230 \&\fBEC_POINT_oct2point()\fR and \fBEC_POINT_point2buf()\fR except they use the public key
231 EC_POINT in \fIeckey\fR.
232 .PP
233 \&\fBEC_KEY_oct2priv()\fR and \fBEC_KEY_priv2oct()\fR convert between the private key
234 component of \fIeckey\fR and octet form. The octet form consists of the content
235 octets of the \fIprivateKey\fR OCTET STRING in an \fIECPrivateKey\fR ASN.1 structure.
236 .PP
237 The function \fBEC_KEY_priv2oct()\fR must be supplied with a buffer long enough to
238 store the octet form. The return value provides the number of octets stored.
239 Calling the function with a NULL buffer will not perform the conversion but
240 will just return the required buffer length.
241 .PP
242 The function \fBEC_KEY_priv2buf()\fR allocates a buffer of suitable length and writes
243 an EC_KEY to it in octet format. The allocated buffer is written to \fI*pbuf\fR
244 and its length is returned. The caller must free up the allocated buffer with a
245 call to \fBOPENSSL_free()\fR. Since the allocated buffer value is written to \fI*pbuf\fR
246 the \fIpbuf\fR parameter \fBMUST NOT\fR be \fBNULL\fR.
247 .PP
248 \&\fBEC_KEY_priv2buf()\fR converts an EC_KEY private key into an allocated buffer.
249 .SH "RETURN VALUES"
250 .IX Header "RETURN VALUES"
251 \&\fBEC_KEY_new_ex()\fR, \fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name_ex()\fR,
252 \&\fBEC_KEY_new_by_curve_name()\fR and \fBEC_KEY_dup()\fR return a pointer to the newly
253 created EC_KEY object, or NULL on error.
254 .PP
255 \&\fBEC_KEY_get_flags()\fR returns the flags associated with the EC_KEY object as an
256 integer.
257 .PP
258 \&\fBEC_KEY_copy()\fR returns a pointer to the destination key, or NULL on error.
259 .PP
260 \&\fBEC_KEY_get0_engine()\fR returns a pointer to an ENGINE, or NULL if it wasn't set.
261 .PP
262 \&\fBEC_KEY_up_ref()\fR, \fBEC_KEY_set_group()\fR, \fBEC_KEY_set_public_key()\fR,
263 \&\fBEC_KEY_precompute_mult()\fR, \fBEC_KEY_generate_key()\fR, \fBEC_KEY_check_key()\fR,
264 \&\fBEC_KEY_set_public_key_affine_coordinates()\fR, \fBEC_KEY_oct2key()\fR and
265 \&\fBEC_KEY_oct2priv()\fR return 1 on success or 0 on error.
266 .PP
267 \&\fBEC_KEY_set_private_key()\fR returns 1 on success or 0 on error except when the
268 priv_key argument is NULL, in that case it returns 0, for legacy compatibility,
269 and should not be treated as an error.
270 .PP
271 \&\fBEC_KEY_get0_group()\fR returns the EC_GROUP associated with the EC_KEY.
272 .PP
273 \&\fBEC_KEY_get0_private_key()\fR returns the private key associated with the EC_KEY.
274 .PP
275 \&\fBEC_KEY_get_conv_form()\fR return the point_conversion_form for the EC_KEY.
276 .PP
277 \&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_priv2oct()\fR and \fBEC_KEY_priv2buf()\fR return the length
278 of the buffer or 0 on error.
279 .SH "SEE ALSO"
280 .IX Header "SEE ALSO"
281 \&\fBEVP_PKEY_Q_keygen\fR\|(3)
282 \&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3),
283 \&\fBEC_GROUP_copy\fR\|(3), \fBEC_POINT_new\fR\|(3),
284 \&\fBEC_POINT_add\fR\|(3),
285 \&\fBEC_GFp_simple_method\fR\|(3),
286 \&\fBd2i_ECPKParameters\fR\|(3),
287 \&\fBOSSL_LIB_CTX\fR\|(3)
288 .SH HISTORY
289 .IX Header "HISTORY"
290 \&\fBEVP_EC_gen()\fR was added in OpenSSL 3.0.
291 All other functions described here were deprecated in OpenSSL 3.0.
292 For replacement see \fBEVP_PKEY\-EC\fR\|(7).
293 .SH COPYRIGHT
294 .IX Header "COPYRIGHT"
295 Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved.
296 .PP
297 Licensed under the Apache License 2.0 (the "License"). You may not use
298 this file except in compliance with the License. You can obtain a copy
299 in the file LICENSE in the source distribution or at
300 <https://www.openssl.org/source/license.html>.