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.3570
1 files changed, 0 insertions, 570 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 ef3028c4b7..0000000000
--- a/src/lib/libcrypto/man/EC_KEY_new.3
+++ /dev/null
@@ -1,570 +0,0 @@
1.\" $OpenBSD: EC_KEY_new.3,v 1.16 2020/09/08 03:25:15 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: September 8 2020 $
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_get_key_method_data ,
76.Nm EC_KEY_insert_key_method_data ,
77.Nm EC_KEY_set_asn1_flag ,
78.Nm EC_KEY_precompute_mult ,
79.Nm EC_KEY_generate_key ,
80.Nm EC_KEY_check_key ,
81.Nm EC_KEY_set_public_key_affine_coordinates ,
82.Nm EC_KEY_print ,
83.Nm EC_KEY_print_fp
84.Nd create, destroy and manipulate EC_KEY objects
85.Sh SYNOPSIS
86.In openssl/ec.h
87.In openssl/bn.h
88.Ft EC_KEY *
89.Fn EC_KEY_new void
90.Ft int
91.Fo EC_KEY_get_flags
92.Fa "const EC_KEY *key"
93.Fc
94.Ft void
95.Fo EC_KEY_set_flags
96.Fa "EC_KEY *key"
97.Fa "int flags"
98.Fc
99.Ft void
100.Fo EC_KEY_clear_flags
101.Fa "EC_KEY *key"
102.Fa "int flags"
103.Fc
104.Ft EC_KEY *
105.Fo EC_KEY_new_by_curve_name
106.Fa "int nid"
107.Fc
108.Ft void
109.Fo EC_KEY_free
110.Fa "EC_KEY *key"
111.Fc
112.Ft EC_KEY *
113.Fo EC_KEY_copy
114.Fa "EC_KEY *dst"
115.Fa "const EC_KEY *src"
116.Fc
117.Ft EC_KEY *
118.Fo EC_KEY_dup
119.Fa "const EC_KEY *src"
120.Fc
121.Ft int
122.Fo EC_KEY_up_ref
123.Fa "EC_KEY *key"
124.Fc
125.Ft const EC_GROUP *
126.Fo EC_KEY_get0_group
127.Fa "const EC_KEY *key"
128.Fc
129.Ft int
130.Fo EC_KEY_set_group
131.Fa "EC_KEY *key"
132.Fa "const EC_GROUP *group"
133.Fc
134.Ft const BIGNUM *
135.Fo EC_KEY_get0_private_key
136.Fa "const EC_KEY *key"
137.Fc
138.Ft int
139.Fo EC_KEY_set_private_key
140.Fa "EC_KEY *key"
141.Fa "const BIGNUM *prv"
142.Fc
143.Ft const EC_POINT *
144.Fo EC_KEY_get0_public_key
145.Fa "const EC_KEY *key"
146.Fc
147.Ft int
148.Fo EC_KEY_set_public_key
149.Fa "EC_KEY *key"
150.Fa "const EC_POINT *pub"
151.Fc
152.Ft unsigned int
153.Fo EC_KEY_get_enc_flags
154.Fa "const EC_KEY *key"
155.Fc
156.Ft void
157.Fo EC_KEY_set_enc_flags
158.Fa "EC_KEY *key"
159.Fa "unsigned int flags"
160.Fc
161.Ft point_conversion_form_t
162.Fo EC_KEY_get_conv_form
163.Fa "const EC_KEY *key"
164.Fc
165.Ft void
166.Fo EC_KEY_set_conv_form
167.Fa "EC_KEY *key"
168.Fa "point_conversion_form_t cform"
169.Fc
170.Ft void *
171.Fo EC_KEY_get_key_method_data
172.Fa "EC_KEY *key"
173.Fa "void *(*dup_func)(void *)"
174.Fa "void (*free_func)(void *)"
175.Fa "void (*clear_free_func)(void *)"
176.Fc
177.Ft void
178.Fo EC_KEY_insert_key_method_data
179.Fa "EC_KEY *key"
180.Fa "void *data"
181.Fa "void *(*dup_func)(void *)"
182.Fa "void (*free_func)(void *)"
183.Fa "void (*clear_free_func)(void *)"
184.Fc
185.Ft void
186.Fo EC_KEY_set_asn1_flag
187.Fa "EC_KEY *key"
188.Fa "int asn1_flag"
189.Fc
190.Ft int
191.Fo EC_KEY_precompute_mult
192.Fa "EC_KEY *key"
193.Fa "BN_CTX *ctx"
194.Fc
195.Ft int
196.Fo EC_KEY_generate_key
197.Fa "EC_KEY *key"
198.Fc
199.Ft int
200.Fo EC_KEY_check_key
201.Fa "const EC_KEY *key"
202.Fc
203.Ft int
204.Fo EC_KEY_set_public_key_affine_coordinates
205.Fa "EC_KEY *key"
206.Fa "BIGNUM *x"
207.Fa "BIGNUM *y"
208.Fc
209.Ft int
210.Fo EC_KEY_print
211.Fa "BIO *bp"
212.Fa "const EC_KEY *key"
213.Fa "int off"
214.Fc
215.Ft int
216.Fo EC_KEY_print_fp
217.Fa "FILE *fp"
218.Fa "const EC_KEY *key"
219.Fa "int off"
220.Fc
221.Sh DESCRIPTION
222An
223.Vt EC_KEY
224represents a public key and (optionally) an associated private key.
225The public key is a point on a curve represented by an
226.Vt EC_POINT ,
227see
228.Xr EC_POINT_new 3 .
229The private key is simply a
230.Vt BIGNUM ,
231see
232.Xr BN_new 3 .
233.Pp
234A new
235.Vt EC_KEY
236(with no associated curve) can be constructed by calling
237.Fn EC_KEY_new .
238The reference count for the newly created
239.Vt EC_KEY
240is initially set to 1.
241A curve can be associated with the
242.Vt EC_KEY
243by calling
244.Fn EC_KEY_set_group .
245.Pp
246Alternatively a new
247.Vt EC_KEY
248can be constructed by calling
249.Fn EC_KEY_new_by_curve_name
250and supplying the
251.Fa nid
252of the associated curve.
253Refer to
254.Xr EC_GROUP_new 3
255for a description of curve names.
256This function simply wraps calls to
257.Fn EC_KEY_new
258and
259.Fn EC_GROUP_new_by_curve_name .
260.Pp
261Calling
262.Fn EC_KEY_free
263decrements the reference count for the
264.Vt EC_KEY
265object and, if it has dropped to zero, then frees the memory associated
266with it.
267If
268.Fa key
269is a
270.Dv NULL
271pointer, no action occurs.
272.Pp
273.Fn EC_KEY_copy
274copies the contents of the
275.Vt EC_KEY
276in
277.Fa src
278into
279.Fa dst .
280.Pp
281.Fn EC_KEY_dup
282creates a new
283.Vt EC_KEY
284object and copies
285.Fa src
286into it.
287.Pp
288.Fn EC_KEY_up_ref
289increments the reference count associated with the
290.Vt EC_KEY
291object.
292.Pp
293.Fn EC_KEY_generate_key
294generates a new public and private key for the supplied
295.Fa key
296object.
297.Fa key
298must have an
299.Vt EC_GROUP
300object associated with it before calling this function.
301The private key is a random integer (0 < priv_key < order, where order
302is the order of the
303.Vt EC_GROUP
304object).
305The public key is an
306.Vt EC_POINT
307on the curve calculated by multiplying the generator for the curve
308by the private key.
309.Pp
310.Fn EC_KEY_check_key
311performs various sanity checks on the
312.Vt EC_KEY
313object to confirm that it is valid.
314.Pp
315.Fn EC_KEY_set_public_key_affine_coordinates
316sets the public key for
317.Fa key
318based on its affine coordinates, i.e. it constructs an
319.Vt EC_POINT
320object based on the supplied
321.Fa x
322and
323.Fa y
324values and sets the public key to be this
325.Vt EC_POINT .
326It also performs certain sanity checks on the key to confirm that
327it is valid.
328.Pp
329The functions
330.Fn EC_KEY_get0_group ,
331.Fn EC_KEY_set_group ,
332.Fn EC_KEY_get0_private_key ,
333.Fn EC_KEY_set_private_key ,
334.Fn EC_KEY_get0_public_key ,
335and
336.Fn EC_KEY_set_public_key
337get and set the
338.Vt EC_GROUP
339object, the private key and the
340.Vt EC_POINT
341public key for the
342.Fa key ,
343respectively.
344.Pp
345The functions
346.Fn EC_KEY_get_enc_flags
347and
348.Fn EC_KEY_set_enc_flags
349get and set the value of the encoding flags for the
350.Fa key .
351There are two encoding flags currently defined:
352.Dv EC_PKEY_NO_PARAMETERS
353and
354.Dv EC_PKEY_NO_PUBKEY .
355These flags define the behaviour of how the
356.Fa key
357is converted into ASN.1 in a call to
358.Fn i2d_ECPrivateKey .
359If
360.Dv EC_PKEY_NO_PARAMETERS
361is set then the public parameters for the curve
362are not encoded along with the private key.
363If
364.Dv EC_PKEY_NO_PUBKEY
365is set then the public key is not encoded along with the private
366key.
367.Pp
368The format of the external representation of the public key written by
369.Xr i2d_ECPrivateKey 3 ,
370such as whether it is stored in a compressed form or not,
371is described by the point_conversion_form.
372See
373.Xr EC_GROUP_copy 3
374for a description of point_conversion_form.
375.Pp
376When reading a private key encoded without an associated public key,
377for example if
378.Dv EC_PKEY_NO_PUBKEY
379was used,
380.Xr d2i_ECPrivateKey 3
381generates the missing public key automatically.
382Private keys encoded without parameters, for example if
383.Dv EC_PKEY_NO_PARAMETERS
384was used, cannot be loaded using
385.Xr d2i_ECPrivateKey 3 .
386.Pp
387The functions
388.Fn EC_KEY_get_conv_form
389and
390.Fn EC_KEY_set_conv_form
391get and set the point_conversion_form for the
392.Fa key .
393For a description of point_conversion_form please refer to
394.Xr EC_GROUP_copy 3 .
395.Pp
396.Fn EC_KEY_insert_key_method_data
397and
398.Fn EC_KEY_get_key_method_data
399enable the caller to associate arbitrary additional data specific
400to the elliptic curve scheme being used with the
401.Vt EC_KEY
402object.
403This data is treated as a "black box" by the EC library.
404The data to be stored by
405.Fn EC_KEY_insert_key_method_data
406is provided in the
407.Fa data
408parameter, which must have associated functions for duplicating, freeing
409and "clear_freeing" the data item.
410If a subsequent
411.Fn EC_KEY_get_key_method_data
412call is issued, the functions for duplicating, freeing and
413"clear_freeing" the data item must be provided again, and they must
414be the same as they were when the data item was inserted.
415.Pp
416.Fn EC_KEY_set_flags
417sets the flags in the
418.Fa flags
419parameter on the
420.Vt EC_KEY
421object.
422Any flags that are already set are left set.
423The currently defined standard flags are
424.Dv EC_FLAG_NON_FIPS_ALLOW
425and
426.Dv EC_FLAG_FIPS_CHECKED .
427In addition there is the flag
428.Dv EC_FLAG_COFACTOR_ECDH
429which is specific to ECDH and is defined in
430.In openssl/ecdh.h .
431.Fn EC_KEY_get_flags
432returns the current flags that are set for this
433.Vt EC_KEY .
434.Fn EC_KEY_clear_flags
435clears the flags indicated by the
436.Fa flags
437parameter.
438All other flags are left in their existing state.
439.Pp
440.Fn EC_KEY_set_asn1_flag
441sets the asn1_flag on the underlying
442.Vt EC_GROUP
443object (if set).
444Refer to
445.Xr EC_GROUP_copy 3
446for further information on the asn1_flag.
447.Pp
448.Fn EC_KEY_precompute_mult
449stores multiples of the underlying
450.Vt EC_GROUP
451generator for faster point multiplication.
452See also
453.Xr EC_POINT_add 3 .
454.Pp
455.Fn EC_KEY_print
456and
457.Fn EC_KEY_print_fp
458print out the content of
459.Fa key
460to the
461.Vt BIO
462.Fa bp
463or to the
464.Vt FILE
465pointer
466.Fa fp ,
467respectively.
468Each line is indented by
469.Fa indent
470spaces.
471.Sh RETURN VALUES
472.Fn EC_KEY_new ,
473.Fn EC_KEY_new_by_curve_name ,
474and
475.Fn EC_KEY_dup
476return a pointer to the newly created
477.Vt EC_KEY object
478or
479.Dv NULL
480on error.
481.Pp
482.Fn EC_KEY_get_flags
483returns the flags associated with the
484.Vt EC_KEY object .
485.Pp
486.Fn EC_KEY_copy
487returns a pointer to the destination key or
488.Dv NULL
489on error.
490In the latter case, part of the content may already have been copied.
491.Pp
492.Fn EC_KEY_up_ref ,
493.Fn EC_KEY_set_group ,
494.Fn EC_KEY_set_private_key ,
495.Fn EC_KEY_set_public_key ,
496.Fn EC_KEY_precompute_mult ,
497.Fn EC_KEY_generate_key ,
498.Fn EC_KEY_check_key ,
499.Fn EC_KEY_set_public_key_affine_coordinates ,
500.Fn EC_KEY_print ,
501and
502.Fn EC_KEY_print_fp
503return 1 on success or 0 on error.
504.Pp
505.Fn EC_KEY_get0_group
506returns the
507.Vt EC_GROUP
508associated with the
509.Vt EC_KEY .
510.Pp
511.Fn EC_KEY_get0_private_key
512and
513.Fn EC_KEY_get0_public_key
514return the private or public keys, respectively, associated with the
515.Vt EC_KEY .
516.Pp
517.Fn EC_KEY_get_enc_flags
518returns the value of the current encoding flags for the
519.Vt EC_KEY .
520.Pp
521.Fn EC_KEY_get_conv_form
522returns the point_conversion_form for the
523.Vt EC_KEY .
524.Sh SEE ALSO
525.Xr d2i_ECPKParameters 3 ,
526.Xr EC_GFp_simple_method 3 ,
527.Xr EC_GROUP_copy 3 ,
528.Xr EC_GROUP_new 3 ,
529.Xr EC_KEY_METHOD_new 3 ,
530.Xr EC_POINT_add 3 ,
531.Xr EC_POINT_new 3 ,
532.Xr ECDH_compute_key 3 ,
533.Xr ECDSA_SIG_new 3 ,
534.Xr EVP_PKEY_set1_EC_KEY 3
535.Sh HISTORY
536.Fn EC_KEY_new ,
537.Fn EC_KEY_new_by_curve_name ,
538.Fn EC_KEY_free ,
539.Fn EC_KEY_copy ,
540.Fn EC_KEY_dup ,
541.Fn EC_KEY_up_ref ,
542.Fn EC_KEY_get0_group ,
543.Fn EC_KEY_set_group ,
544.Fn EC_KEY_get0_private_key ,
545.Fn EC_KEY_set_private_key ,
546.Fn EC_KEY_get0_public_key ,
547.Fn EC_KEY_set_public_key ,
548.Fn EC_KEY_get_enc_flags ,
549.Fn EC_KEY_set_enc_flags ,
550.Fn EC_KEY_get_conv_form ,
551.Fn EC_KEY_set_conv_form ,
552.Fn EC_KEY_get_key_method_data ,
553.Fn EC_KEY_insert_key_method_data ,
554.Fn EC_KEY_set_asn1_flag ,
555.Fn EC_KEY_precompute_mult ,
556.Fn EC_KEY_generate_key ,
557.Fn EC_KEY_check_key ,
558.Fn EC_KEY_print ,
559and
560.Fn EC_KEY_print_fp
561first appeared in OpenSSL 0.9.8 and have been available since
562.Ox 4.5 .
563.Pp
564.Fn EC_KEY_get_flags ,
565.Fn EC_KEY_set_flags ,
566.Fn EC_KEY_clear_flags ,
567and
568.Fn EC_KEY_set_public_key_affine_coordinates
569first appeared in OpenSSL 1.0.1 and have been available since
570.Ox 5.3 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 22:42:20 +0000