Debian Codegraph @

upstream/debian-unstable/man7/EVP_PKEY-EC.7ssl

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 "EVP_PKEY-EC 7SSL"
58 .TH EVP_PKEY-EC 7SSL 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_PKEY\-EC,
65 EVP_KEYMGMT\-EC
66 \&\- EVP_PKEY EC keytype and algorithm support
67 .SH DESCRIPTION
68 .IX Header "DESCRIPTION"
69 The \fBEC\fR keytype is implemented in OpenSSL's default provider.
70 .SS "Common EC parameters"
71 .IX Subsection "Common EC parameters"
72 The normal way of specifying domain parameters for an EC curve is via the
73 curve name "group". For curves with no curve name, explicit parameters can be
74 used that specify "field-type", "p", "a", "b", "generator" and "order".
75 Explicit parameters are supported for backwards compatibility reasons, but they
76 are not compliant with multiple standards (including RFC5915) which only allow
77 named curves.
78 .PP
79 The following Key generation/Gettable/Import/Export types are available for the
80 built-in EC algorithm:
81 .IP """group"" (\fBOSSL_PKEY_PARAM_GROUP_NAME\fR) <UTF8 string>" 4
82 .IX Item """group"" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>"
83 The curve name.
84 .IP """field-type"" (\fBOSSL_PKEY_PARAM_EC_FIELD_TYPE\fR) <UTF8 string>" 4
85 .IX Item """field-type"" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>"
86 The value should be either "prime-field" or "characteristic-two-field",
87 which correspond to prime field Fp and binary field F2^m.
88 .IP """p"" (\fBOSSL_PKEY_PARAM_EC_P\fR) <unsigned integer>" 4
89 .IX Item """p"" (OSSL_PKEY_PARAM_EC_P) <unsigned integer>"
90 For a curve over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR
91 represents the irreducible polynomial \- each bit represents a term in the
92 polynomial. Therefore, there will either be three or five bits set dependent on
93 whether the polynomial is a trinomial or a pentanomial.
94 .IP """a"" (\fBOSSL_PKEY_PARAM_EC_A\fR) <unsigned integer>" 4
95 .IX Item """a"" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>"
96 .PD 0
97 .IP """b"" (\fBOSSL_PKEY_PARAM_EC_B\fR) <unsigned integer>" 4
98 .IX Item """b"" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>"
99 .IP """seed"" (\fBOSSL_PKEY_PARAM_EC_SEED\fR) <octet string>" 4
100 .IX Item """seed"" (OSSL_PKEY_PARAM_EC_SEED) <octet string>"
101 .PD
102 \&\fIa\fR and \fIb\fR represents the coefficients of the curve
103 For Fp: y^2 mod p = x^3 +ax + b mod p OR
104 For F2^m: y^2 + xy = x^3 + ax^2 + b
105 .Sp
106 \&\fIseed\fR is an optional value that is for information purposes only.
107 It represents the random number seed used to generate the coefficient \fIb\fR from a
108 random number.
109 .IP """generator"" (\fBOSSL_PKEY_PARAM_EC_GENERATOR\fR) <octet string>" 4
110 .IX Item """generator"" (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>"
111 .PD 0
112 .IP """order"" (\fBOSSL_PKEY_PARAM_EC_ORDER\fR) <unsigned integer>" 4
113 .IX Item """order"" (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>"
114 .IP """cofactor"" (\fBOSSL_PKEY_PARAM_EC_COFACTOR\fR) <unsigned integer>" 4
115 .IX Item """cofactor"" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>"
116 .PD
117 The \fIgenerator\fR is a well defined point on the curve chosen for cryptographic
118 operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
119 Cryptography") standard. See \fBEC_POINT_oct2point()\fR.
120 Integers used for point multiplications will be between 0 and
121 \&\fIorder\fR \- 1.
122 \&\fIcofactor\fR is an optional value.
123 \&\fIorder\fR multiplied by the \fIcofactor\fR gives the number of points on the curve.
124 .IP """decoded-from-explicit"" (\fBOSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS\fR) <integer>" 4
125 .IX Item """decoded-from-explicit"" (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer>"
126 Gets a flag indicating whether the key or parameters were decoded from explicit
127 curve parameters. Set to 1 if so or 0 if a named curve was used.
128 .IP """use-cofactor-flag"" (\fBOSSL_PKEY_PARAM_USE_COFACTOR_ECDH\fR) <integer>" 4
129 .IX Item """use-cofactor-flag"" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer>"
130 Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
131 if the value is zero. The cofactor variant multiplies the shared secret by the
132 EC curve's cofactor (note for some curves the cofactor is 1).
133 .Sp
134 See also \fBEVP_KEYEXCH\-ECDH\fR\|(7) for the related
135 \&\fBOSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE\fR parameter that can be set on a
136 per-operation basis.
137 .IP """encoding"" (\fBOSSL_PKEY_PARAM_EC_ENCODING\fR) <UTF8 string>" 4
138 .IX Item """encoding"" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>"
139 Set the format used for serializing the EC group parameters.
140 Valid values are "explicit" or "named_curve". The default value is "named_curve".
141 .IP """point-format"" (\fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR) <UTF8 string>" 4
142 .IX Item """point-format"" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string>"
143 Sets or gets the point_conversion_form for the \fIkey\fR. For a description of
144 point_conversion_forms please see \fBEC_POINT_new\fR\|(3). Valid values are
145 "uncompressed" or "compressed". The default value is "uncompressed".
146 .IP """group-check"" (\fBOSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE\fR) <UTF8 string>" 4
147 .IX Item """group-check"" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>"
148 Sets or Gets the type of group check done when \fBEVP_PKEY_param_check()\fR is called.
149 Valid values are "default", "named" and "named-nist".
150 The "named" type checks that the domain parameters match the inbuilt curve parameters,
151 "named-nist" is similar but also checks that the named curve is a nist curve.
152 The "default" type does domain parameter validation for the OpenSSL default provider,
153 but is equivalent to "named-nist" for the OpenSSL FIPS provider.
154 .IP """include-public"" (\fBOSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC\fR) <integer>" 4
155 .IX Item """include-public"" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>"
156 Setting this value to 0 indicates that the public key should not be included when
157 encoding the private key. The default value of 1 will include the public key.
158 .IP """pub"" (\fBOSSL_PKEY_PARAM_PUB_KEY\fR) <octet string>" 4
159 .IX Item """pub"" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>"
160 The public key value in encoded EC point format conforming to Sec. 2.3.3 and
161 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
162 This parameter is used when importing or exporting the public key value with the
163 \&\fBEVP_PKEY_fromdata()\fR and \fBEVP_PKEY_todata()\fR functions.
164 .Sp
165 Note, in particular, that the choice of point compression format used for
166 encoding the exported value via \fBEVP_PKEY_todata()\fR depends on the underlying
167 provider implementation.
168 Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always
169 opted for an encoding in compressed format, unconditionally.
170 Since OpenSSL 3.0.8, the implementation has been changed to honor the
171 \&\fBOSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT\fR parameter, if set, or to default
172 to uncompressed format.
173 .IP """priv"" (\fBOSSL_PKEY_PARAM_PRIV_KEY\fR) <unsigned integer>" 4
174 .IX Item """priv"" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>"
175 The private key value.
176 .IP """encoded-pub-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) <octet string>" 4
177 .IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>"
178 Used for getting and setting the encoding of an EC public key. The public key
179 is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
180 Curve Cryptography") standard.
181 .IP """qx"" (\fBOSSL_PKEY_PARAM_EC_PUB_X\fR) <unsigned integer>" 4
182 .IX Item """qx"" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>"
183 Used for getting the EC public key X component.
184 .IP """qy"" (\fBOSSL_PKEY_PARAM_EC_PUB_Y\fR) <unsigned integer>" 4
185 .IX Item """qy"" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>"
186 Used for getting the EC public key Y component.
187 .IP """default-digest"" (\fBOSSL_PKEY_PARAM_DEFAULT_DIGEST\fR) <UTF8 string>" 4
188 .IX Item """default-digest"" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>"
189 Getter that returns the default digest name.
190 (Currently returns "SHA256" as of OpenSSL 3.0).
191 .IP """dhkem-ikm"" (\fBOSSL_PKEY_PARAM_DHKEM_IKM\fR) <octet string>" 4
192 .IX Item """dhkem-ikm"" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>"
193 DHKEM requires the generation of a keypair using an input key material (seed).
194 Use this to specify the key material used for generation of the private key.
195 This value should not be reused for other purposes. It can only be used
196 for the curves "P\-256", "P\-384" and "P\-521" and should have a length of at least
197 the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves).
198 .PP
199 The following Gettable types are also available for the built-in EC algorithm:
200 .IP """basis-type"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_TYPE\fR) <UTF8 string>" 4
201 .IX Item """basis-type"" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>"
202 Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
203 This field is only used for a binary field F2^m.
204 .IP """m"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_M\fR) <integer>" 4
205 .IX Item """m"" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>"
206 .PD 0
207 .IP """tp"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS\fR) <integer>" 4
208 .IX Item """tp"" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>"
209 .IP """k1"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K1\fR) <integer>" 4
210 .IX Item """k1"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>"
211 .IP """k2"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K2\fR) <integer>" 4
212 .IX Item """k2"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>"
213 .IP """k3"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_PP_K3\fR) <integer>" 4
214 .IX Item """k3"" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>"
215 .PD
216 These fields are only used for a binary field F2^m.
217 \&\fIm\fR is the degree of the binary field.
218 .Sp
219 \&\fItp\fR is the middle bit of a trinomial so its value must be in the
220 range m > tp > 0.
221 .Sp
222 \&\fIk1\fR, \fIk2\fR and \fIk3\fR are used to get the middle bits of a pentanomial such
223 that m > k3 > k2 > k1 > 0
224 .PP
225 The following key generation settable parameter is also available for the
226 OpenSSL FIPS provider's EC algorithm:
227 .IP """key-check"" (\fBOSSL_PKEY_PARAM_FIPS_KEY_CHECK\fR) <integer>" 4
228 .IX Item """key-check"" (OSSL_PKEY_PARAM_FIPS_KEY_CHECK) <integer>"
229 See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for further information.
230 .PP
231 The following key generation Gettable parameter is available for the OpenSSL
232 FIPS provider's EC algorithm:
233 .IP """fips-indicator"" (\fBOSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
234 .IX Item """fips-indicator"" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
235 See "Common Information Parameters" in \fBprovider\-keymgmt\fR\|(7) for further information.
236 .SS "EC key validation"
237 .IX Subsection "EC key validation"
238 For EC keys, \fBEVP_PKEY_param_check\fR\|(3) behaves in the following way:
239 For the OpenSSL default provider it uses either
240 \&\fBEC_GROUP_check\fR\|(3) or \fBEC_GROUP_check_named_curve\fR\|(3) depending on the flag
241 EC_FLAG_CHECK_NAMED_GROUP.
242 The OpenSSL FIPS provider uses \fBEC_GROUP_check_named_curve\fR\|(3) in order to
243 conform to SP800\-56Ar3 \fIAssurances of Domain-Parameter Validity\fR.
244 .PP
245 For EC keys, \fBEVP_PKEY_param_check_quick\fR\|(3) is equivalent to
246 \&\fBEVP_PKEY_param_check\fR\|(3).
247 .PP
248 For EC keys, \fBEVP_PKEY_public_check\fR\|(3) and \fBEVP_PKEY_public_check_quick\fR\|(3)
249 conform to SP800\-56Ar3 \fIECC Full Public-Key Validation\fR and
250 \&\fIECC Partial Public-Key Validation\fR respectively.
251 .PP
252 For EC Keys, \fBEVP_PKEY_private_check\fR\|(3) and \fBEVP_PKEY_pairwise_check\fR\|(3)
253 conform to SP800\-56Ar3 \fIPrivate key validity\fR and
254 \&\fIOwner Assurance of Pair-wise Consistency\fR respectively.
255 .SH EXAMPLES
256 .IX Header "EXAMPLES"
257 An \fBEVP_PKEY\fR context can be obtained by calling:
258 .PP
259 .Vb 2
260 \& EVP_PKEY_CTX *pctx =
261 \& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
262 .Ve
263 .PP
264 An \fBEVP_PKEY\fR ECDSA or ECDH key can be generated with a "P\-256" named group by
265 calling:
266 .PP
267 .Vb 1
268 \& pkey = EVP_EC_gen("P\-256");
269 .Ve
270 .PP
271 or like this:
272 .PP
273 .Vb 4
274 \& EVP_PKEY *key = NULL;
275 \& OSSL_PARAM params[2];
276 \& EVP_PKEY_CTX *gctx =
277 \& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
278 \&
279 \& EVP_PKEY_keygen_init(gctx);
280 \&
281 \& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
282 \& "P\-256", 0);
283 \& params[1] = OSSL_PARAM_construct_end();
284 \& EVP_PKEY_CTX_set_params(gctx, params);
285 \&
286 \& EVP_PKEY_generate(gctx, &key);
287 \&
288 \& EVP_PKEY_print_private(bio_out, key, 0, NULL);
289 \& ...
290 \& EVP_PKEY_free(key);
291 \& EVP_PKEY_CTX_free(gctx);
292 .Ve
293 .PP
294 An \fBEVP_PKEY\fR EC CDH (Cofactor Diffie-Hellman) key can be generated with a
295 "K\-571" named group by calling:
296 .PP
297 .Vb 5
298 \& int use_cdh = 1;
299 \& EVP_PKEY *key = NULL;
300 \& OSSL_PARAM params[3];
301 \& EVP_PKEY_CTX *gctx =
302 \& EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
303 \&
304 \& EVP_PKEY_keygen_init(gctx);
305 \&
306 \& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
307 \& "K\-571", 0);
308 \& /*
309 \& * This curve has a cofactor that is not 1 \- so setting CDH mode changes
310 \& * the behaviour. For many curves the cofactor is 1 \- so setting this has
311 \& * no effect.
312 \& */
313 \& params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
314 \& &use_cdh);
315 \& params[2] = OSSL_PARAM_construct_end();
316 \& EVP_PKEY_CTX_set_params(gctx, params);
317 \&
318 \& EVP_PKEY_generate(gctx, &key);
319 \& EVP_PKEY_print_private(bio_out, key, 0, NULL);
320 \& ...
321 \& EVP_PKEY_free(key);
322 \& EVP_PKEY_CTX_free(gctx);
323 .Ve
324 .SH "SEE ALSO"
325 .IX Header "SEE ALSO"
326 \&\fBEVP_EC_gen\fR\|(3),
327 \&\fBEVP_KEYMGMT\fR\|(3),
328 \&\fBEVP_PKEY\fR\|(3),
329 \&\fBprovider\-keymgmt\fR\|(7),
330 \&\fBEVP_SIGNATURE\-ECDSA\fR\|(7),
331 \&\fBEVP_KEYEXCH\-ECDH\fR\|(7)
332 .SH COPYRIGHT
333 .IX Header "COPYRIGHT"
334 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
335 .PP
336 Licensed under the Apache License 2.0 (the "License"). You may not use
337 this file except in compliance with the License. You can obtain a copy
338 in the file LICENSE in the source distribution or at
339 <https://www.openssl.org/source/license.html>.