summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EC_KEY_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EC_KEY_new.3')
-rw-r--r--src/lib/libcrypto/man/EC_KEY_new.3532
1 files changed, 0 insertions, 532 deletions
diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3
deleted file mode 100644
index c24cb080ef..0000000000
--- a/src/lib/libcrypto/man/EC_KEY_new.3
+++ /dev/null
@@ -1,532 +0,0 @@
1.\" $OpenBSD: EC_KEY_new.3,v 1.21 2025/03/08 16:38:13 tb Exp $
2.\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500
3.\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
4.\"
5.\" This file was written by Matt Caswell <matt@openssl.org>.
6.\" Copyright (c) 2013, 2014 The OpenSSL Project. All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\"
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\"
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in
17.\" the documentation and/or other materials provided with the
18.\" distribution.
19.\"
20.\" 3. All advertising materials mentioning features or use of this
21.\" software must display the following acknowledgment:
22.\" "This product includes software developed by the OpenSSL Project
23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24.\"
25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26.\" endorse or promote products derived from this software without
27.\" prior written permission. For written permission, please contact
28.\" openssl-core@openssl.org.
29.\"
30.\" 5. Products derived from this software may not be called "OpenSSL"
31.\" nor may "OpenSSL" appear in their names without prior written
32.\" permission of the OpenSSL Project.
33.\"
34.\" 6. Redistributions of any form whatsoever must retain the following
35.\" acknowledgment:
36.\" "This product includes software developed by the OpenSSL Project
37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38.\"
39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50.\" OF THE POSSIBILITY OF SUCH DAMAGE.
51.\"
52.Dd $Mdocdate: March 8 2025 $
53.Dt EC_KEY_NEW 3
54.Os
55.Sh NAME
56.Nm EC_KEY_new ,
57.Nm EC_KEY_get_flags ,
58.Nm EC_KEY_set_flags ,
59.Nm EC_KEY_clear_flags ,
60.Nm EC_KEY_new_by_curve_name ,
61.Nm EC_KEY_free ,
62.Nm EC_KEY_copy ,
63.Nm EC_KEY_dup ,
64.Nm EC_KEY_up_ref ,
65.Nm EC_KEY_get0_group ,
66.Nm EC_KEY_set_group ,
67.Nm EC_KEY_get0_private_key ,
68.Nm EC_KEY_set_private_key ,
69.Nm EC_KEY_get0_public_key ,
70.Nm EC_KEY_set_public_key ,
71.Nm EC_KEY_get_enc_flags ,
72.Nm EC_KEY_set_enc_flags ,
73.Nm EC_KEY_get_conv_form ,
74.Nm EC_KEY_set_conv_form ,
75.Nm EC_KEY_set_asn1_flag ,
76.Nm EC_KEY_precompute_mult ,
77.Nm EC_KEY_generate_key ,
78.Nm EC_KEY_check_key ,
79.Nm EC_KEY_set_public_key_affine_coordinates ,
80.Nm EC_KEY_print ,
81.Nm EC_KEY_print_fp
82.Nd create, destroy and manipulate EC_KEY objects
83.Sh SYNOPSIS
84.In openssl/ec.h
85.In openssl/bn.h
86.Ft EC_KEY *
87.Fn EC_KEY_new void
88.Ft int
89.Fo EC_KEY_get_flags
90.Fa "const EC_KEY *key"
91.Fc
92.Ft void
93.Fo EC_KEY_set_flags
94.Fa "EC_KEY *key"
95.Fa "int flags"
96.Fc
97.Ft void
98.Fo EC_KEY_clear_flags
99.Fa "EC_KEY *key"
100.Fa "int flags"
101.Fc
102.Ft EC_KEY *
103.Fo EC_KEY_new_by_curve_name
104.Fa "int nid"
105.Fc
106.Ft void
107.Fo EC_KEY_free
108.Fa "EC_KEY *key"
109.Fc
110.Ft EC_KEY *
111.Fo EC_KEY_copy
112.Fa "EC_KEY *dst"
113.Fa "const EC_KEY *src"
114.Fc
115.Ft EC_KEY *
116.Fo EC_KEY_dup
117.Fa "const EC_KEY *src"
118.Fc
119.Ft int
120.Fo EC_KEY_up_ref
121.Fa "EC_KEY *key"
122.Fc
123.Ft const EC_GROUP *
124.Fo EC_KEY_get0_group
125.Fa "const EC_KEY *key"
126.Fc
127.Ft int
128.Fo EC_KEY_set_group
129.Fa "EC_KEY *key"
130.Fa "const EC_GROUP *group"
131.Fc
132.Ft const BIGNUM *
133.Fo EC_KEY_get0_private_key
134.Fa "const EC_KEY *key"
135.Fc
136.Ft int
137.Fo EC_KEY_set_private_key
138.Fa "EC_KEY *key"
139.Fa "const BIGNUM *prv"
140.Fc
141.Ft const EC_POINT *
142.Fo EC_KEY_get0_public_key
143.Fa "const EC_KEY *key"
144.Fc
145.Ft int
146.Fo EC_KEY_set_public_key
147.Fa "EC_KEY *key"
148.Fa "const EC_POINT *pub"
149.Fc
150.Ft unsigned int
151.Fo EC_KEY_get_enc_flags
152.Fa "const EC_KEY *key"
153.Fc
154.Ft void
155.Fo EC_KEY_set_enc_flags
156.Fa "EC_KEY *key"
157.Fa "unsigned int flags"
158.Fc
159.Ft point_conversion_form_t
160.Fo EC_KEY_get_conv_form
161.Fa "const EC_KEY *key"
162.Fc
163.Ft void
164.Fo EC_KEY_set_conv_form
165.Fa "EC_KEY *key"
166.Fa "point_conversion_form_t cform"
167.Fc
168.Ft void
169.Fo EC_KEY_set_asn1_flag
170.Fa "EC_KEY *key"
171.Fa "int asn1_flag"
172.Fc
173.Ft int
174.Fo EC_KEY_precompute_mult
175.Fa "EC_KEY *key"
176.Fa "BN_CTX *ctx"
177.Fc
178.Ft int
179.Fo EC_KEY_generate_key
180.Fa "EC_KEY *key"
181.Fc
182.Ft int
183.Fo EC_KEY_check_key
184.Fa "const EC_KEY *key"
185.Fc
186.Ft int
187.Fo EC_KEY_set_public_key_affine_coordinates
188.Fa "EC_KEY *key"
189.Fa "BIGNUM *x"
190.Fa "BIGNUM *y"
191.Fc
192.Ft int
193.Fo EC_KEY_print
194.Fa "BIO *bp"
195.Fa "const EC_KEY *key"
196.Fa "int off"
197.Fc
198.Ft int
199.Fo EC_KEY_print_fp
200.Fa "FILE *fp"
201.Fa "const EC_KEY *key"
202.Fa "int off"
203.Fc
204.Sh DESCRIPTION
205An
206.Vt EC_KEY
207represents a public key and (optionally) an associated private key.
208The public key is a point on a curve represented by an
209.Vt EC_POINT ,
210see
211.Xr EC_POINT_new 3 .
212The private key is simply a
213.Vt BIGNUM ,
214see
215.Xr BN_new 3 .
216.Pp
217A new
218.Vt EC_KEY
219(with no associated curve) can be constructed by calling
220.Fn EC_KEY_new .
221The reference count for the newly created
222.Vt EC_KEY
223is initially set to 1.
224A curve can be associated with the
225.Vt EC_KEY
226by calling
227.Fn EC_KEY_set_group .
228.Pp
229Alternatively a new
230.Vt EC_KEY
231can be constructed by calling
232.Fn EC_KEY_new_by_curve_name
233and supplying the
234.Fa nid
235of the associated curve.
236Refer to
237.Xr EC_GROUP_new 3
238for a description of curve names.
239This function simply wraps calls to
240.Fn EC_KEY_new
241and
242.Fn EC_GROUP_new_by_curve_name .
243.Pp
244Calling
245.Fn EC_KEY_free
246decrements the reference count for the
247.Vt EC_KEY
248object and, if it has dropped to zero, then frees the memory associated
249with it.
250If
251.Fa key
252is a
253.Dv NULL
254pointer, no action occurs.
255.Pp
256.Fn EC_KEY_copy
257copies the contents of the
258.Vt EC_KEY
259in
260.Fa src
261into
262.Fa dst .
263.Pp
264.Fn EC_KEY_dup
265creates a new
266.Vt EC_KEY
267object and copies
268.Fa src
269into it.
270.Pp
271.Fn EC_KEY_up_ref
272increments the reference count associated with the
273.Vt EC_KEY
274object.
275.Pp
276.Fn EC_KEY_generate_key
277generates a new public and private key for the supplied
278.Fa key
279object.
280.Fa key
281must have an
282.Vt EC_GROUP
283object associated with it before calling this function.
284The private key is a random integer (0 < priv_key < order, where order
285is the order of the
286.Vt EC_GROUP
287object).
288The public key is an
289.Vt EC_POINT
290on the curve calculated by multiplying the generator for the curve
291by the private key.
292.Pp
293.Fn EC_KEY_check_key
294performs various sanity checks on the
295.Vt EC_KEY
296object to confirm that it is valid.
297.Pp
298.Fn EC_KEY_set_public_key_affine_coordinates
299sets the public key for
300.Fa key
301based on its affine coordinates, i.e. it constructs an
302.Vt EC_POINT
303object based on the supplied
304.Fa x
305and
306.Fa y
307values and sets the public key to be this
308.Vt EC_POINT .
309It also performs certain sanity checks on the key to confirm that
310it is valid.
311.Pp
312The functions
313.Fn EC_KEY_get0_group ,
314.Fn EC_KEY_set_group ,
315.Fn EC_KEY_get0_private_key ,
316.Fn EC_KEY_set_private_key ,
317.Fn EC_KEY_get0_public_key ,
318and
319.Fn EC_KEY_set_public_key
320get and set the
321.Vt EC_GROUP
322object, the private key and the
323.Vt EC_POINT
324public key for the
325.Fa key ,
326respectively.
327The setters copy the group and key objects without sanity checks
328and it is the caller's responsibility to ensure that
329the resulting key is valid, for example using
330.Fn EC_KEY_check_key .
331.Pp
332The functions
333.Fn EC_KEY_get_enc_flags
334and
335.Fn EC_KEY_set_enc_flags
336get and set the value of the encoding flags for the
337.Fa key .
338There are two encoding flags currently defined:
339.Dv EC_PKEY_NO_PARAMETERS
340and
341.Dv EC_PKEY_NO_PUBKEY .
342These flags define the behaviour of how the
343.Fa key
344is converted into ASN.1 in a call to
345.Fn i2d_ECPrivateKey .
346If
347.Dv EC_PKEY_NO_PARAMETERS
348is set then the public parameters for the curve
349are not encoded along with the private key.
350If
351.Dv EC_PKEY_NO_PUBKEY
352is set then the public key is not encoded along with the private
353key.
354.Pp
355The format of the external representation of the public key written by
356.Xr i2d_ECPrivateKey 3 ,
357such as whether it is stored in a compressed form or not,
358is described by the point_conversion_form.
359See
360.Xr EC_GROUP_copy 3
361for a description of point_conversion_form.
362.Pp
363When reading a private key encoded without an associated public key,
364for example if
365.Dv EC_PKEY_NO_PUBKEY
366was used,
367.Xr d2i_ECPrivateKey 3
368generates the missing public key automatically.
369Private keys encoded without parameters, for example if
370.Dv EC_PKEY_NO_PARAMETERS
371was used, cannot be loaded using
372.Xr d2i_ECPrivateKey 3 .
373.Pp
374The functions
375.Fn EC_KEY_get_conv_form
376and
377.Fn EC_KEY_set_conv_form
378get and set the point_conversion_form for the
379.Fa key .
380For a description of point_conversion_form refer to
381.Xr EC_GROUP_copy 3 .
382.Pp
383.Fn EC_KEY_set_flags
384sets the flags in the
385.Fa flags
386parameter on the
387.Vt EC_KEY
388object.
389Any flags that are already set are left set.
390The currently defined standard flags are
391.Dv EC_FLAG_NON_FIPS_ALLOW
392and
393.Dv EC_FLAG_FIPS_CHECKED .
394In addition there is the ECDH-specific flag
395.Dv EC_FLAG_COFACTOR_ECDH .
396.Fn EC_KEY_get_flags
397returns the current flags that are set for this
398.Vt EC_KEY .
399.Fn EC_KEY_clear_flags
400clears the flags indicated by the
401.Fa flags
402parameter.
403All other flags are left in their existing state.
404.Pp
405.Fn EC_KEY_set_asn1_flag
406sets the asn1_flag on the underlying
407.Vt EC_GROUP
408object (if set).
409Refer to
410.Xr EC_GROUP_copy 3
411for further information on the asn1_flag.
412.Pp
413.Fn EC_KEY_precompute_mult
414stores multiples of the underlying
415.Vt EC_GROUP
416generator for faster point multiplication.
417See also
418.Xr EC_POINT_add 3 .
419.Pp
420.Fn EC_KEY_print
421and
422.Fn EC_KEY_print_fp
423print out the content of
424.Fa key
425to the
426.Vt BIO
427.Fa bp
428or to the
429.Vt FILE
430pointer
431.Fa fp ,
432respectively.
433Each line is indented by
434.Fa indent
435spaces.
436.Sh RETURN VALUES
437.Fn EC_KEY_new ,
438.Fn EC_KEY_new_by_curve_name ,
439and
440.Fn EC_KEY_dup
441return a pointer to the newly created
442.Vt EC_KEY object
443or
444.Dv NULL
445on error.
446.Pp
447.Fn EC_KEY_get_flags
448returns the flags associated with the
449.Vt EC_KEY object .
450.Pp
451.Fn EC_KEY_copy
452returns a pointer to the destination key or
453.Dv NULL
454on error.
455In the latter case, part of the content may already have been copied.
456.Pp
457.Fn EC_KEY_up_ref ,
458.Fn EC_KEY_set_group ,
459.Fn EC_KEY_set_private_key ,
460.Fn EC_KEY_set_public_key ,
461.Fn EC_KEY_precompute_mult ,
462.Fn EC_KEY_generate_key ,
463.Fn EC_KEY_check_key ,
464.Fn EC_KEY_set_public_key_affine_coordinates ,
465.Fn EC_KEY_print ,
466and
467.Fn EC_KEY_print_fp
468return 1 on success or 0 on error.
469.Pp
470.Fn EC_KEY_get0_group
471returns the
472.Vt EC_GROUP
473associated with the
474.Vt EC_KEY .
475.Pp
476.Fn EC_KEY_get0_private_key
477and
478.Fn EC_KEY_get0_public_key
479return the private or public keys, respectively, associated with the
480.Vt EC_KEY .
481.Pp
482.Fn EC_KEY_get_enc_flags
483returns the value of the current encoding flags for the
484.Vt EC_KEY .
485.Pp
486.Fn EC_KEY_get_conv_form
487returns the point_conversion_form for the
488.Vt EC_KEY .
489.Sh SEE ALSO
490.Xr d2i_ECPKParameters 3 ,
491.Xr EC_GROUP_copy 3 ,
492.Xr EC_GROUP_new 3 ,
493.Xr EC_KEY_METHOD_new 3 ,
494.Xr EC_POINT_add 3 ,
495.Xr EC_POINT_new 3 ,
496.Xr ECDH_compute_key 3 ,
497.Xr ECDSA_SIG_new 3 ,
498.Xr EVP_PKEY_set1_EC_KEY 3
499.Sh HISTORY
500.Fn EC_KEY_new ,
501.Fn EC_KEY_new_by_curve_name ,
502.Fn EC_KEY_free ,
503.Fn EC_KEY_copy ,
504.Fn EC_KEY_dup ,
505.Fn EC_KEY_up_ref ,
506.Fn EC_KEY_get0_group ,
507.Fn EC_KEY_set_group ,
508.Fn EC_KEY_get0_private_key ,
509.Fn EC_KEY_set_private_key ,
510.Fn EC_KEY_get0_public_key ,
511.Fn EC_KEY_set_public_key ,
512.Fn EC_KEY_get_enc_flags ,
513.Fn EC_KEY_set_enc_flags ,
514.Fn EC_KEY_get_conv_form ,
515.Fn EC_KEY_set_conv_form ,
516.Fn EC_KEY_set_asn1_flag ,
517.Fn EC_KEY_precompute_mult ,
518.Fn EC_KEY_generate_key ,
519.Fn EC_KEY_check_key ,
520.Fn EC_KEY_print ,
521and
522.Fn EC_KEY_print_fp
523first appeared in OpenSSL 0.9.8 and have been available since
524.Ox 4.5 .
525.Pp
526.Fn EC_KEY_get_flags ,
527.Fn EC_KEY_set_flags ,
528.Fn EC_KEY_clear_flags ,
529and
530.Fn EC_KEY_set_public_key_affine_coordinates
531first appeared in OpenSSL 1.0.1 and have been available since
532.Ox 5.3 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 16:23:12 +0000