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