1=pod
2
3=head1 NAME
4
5EVP_PKEY-EC,
6EVP_KEYMGMT-EC
7- EVP_PKEY EC keytype and algorithm support
8
9=head1 DESCRIPTION
10
11The B<EC> keytype is implemented in OpenSSL's default provider.
12
13=head2 Common EC parameters
14
15The normal way of specifying domain parameters for an EC curve is via the
16curve name "group". For curves with no curve name, explicit parameters can be
17used that specify "field-type", "p", "a", "b", "generator" and "order".
18Explicit parameters are supported for backwards compatibility reasons, but they
19are not compliant with multiple standards (including RFC5915) which only allow
20named curves.
21
22The following KeyGen/Gettable/Import/Export types are available for the
23built-in EC algorithm:
24
25=over 4
26
27=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
28
29The curve name.
30
31=item "field-type" (B<OSSL_PKEY_PARAM_EC_FIELD_TYPE>) <UTF8 string>
32
33The value should be either "prime-field" or "characteristic-two-field",
34which correspond to prime field Fp and binary field F2^m.
35
36=item "p" (B<OSSL_PKEY_PARAM_EC_P>) <unsigned integer>
37
38For a curve over Fp I<p> is the prime for the field. For a curve over F2^m I<p>
39represents the irreducible polynomial - each bit represents a term in the
40polynomial. Therefore, there will either be three or five bits set dependent on
41whether the polynomial is a trinomial or a pentanomial.
42
43=item "a" (B<OSSL_PKEY_PARAM_EC_A>) <unsigned integer>
44
45=item "b" (B<OSSL_PKEY_PARAM_EC_B>) <unsigned integer>
46
47=item "seed" (B<OSSL_PKEY_PARAM_EC_SEED>) <octet string>
48
49I<a> and I<b> represents the coefficients of the curve
50For Fp:   y^2 mod p = x^3 +ax + b mod p OR
51For F2^m: y^2 + xy = x^3 + ax^2 + b
52
53I<seed> is an optional value that is for information purposes only.
54It represents the random number seed used to generate the coefficient I<b> from a
55random number.
56
57=item "generator" (B<OSSL_PKEY_PARAM_EC_GENERATOR>) <octet string>
58
59=item "order" (B<OSSL_PKEY_PARAM_EC_ORDER>) <unsigned integer>
60
61=item "cofactor" (B<OSSL_PKEY_PARAM_EC_COFACTOR>) <unsigned integer>
62
63The I<generator> is a well defined point on the curve chosen for cryptographic
64operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
65Cryptography") standard. See EC_POINT_oct2point().
66Integers used for point multiplications will be between 0 and
67I<order> - 1.
68I<cofactor> is an optional value.
69I<order> multiplied by the I<cofactor> gives the number of points on the curve.
70
71=item  "decoded-from-explicit" (B<OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS>) <integer>
72
73Gets a flag indicating whether the key or parameters were decoded from explicit
74curve parameters. Set to 1 if so or 0 if a named curve was used.
75
76=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
77
78Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
79if the value is zero. The cofactor variant multiplies the shared secret by the
80EC curve's cofactor (note for some curves the cofactor is 1).
81
82See also L<EVP_KEYEXCH-ECDH(7)> for the related
83B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
84per-operation basis.
85
86=item "encoding" (B<OSSL_PKEY_PARAM_EC_ENCODING>) <UTF8 string>
87
88Set the format used for serializing the EC group parameters.
89Valid values are "explicit" or "named_curve". The default value is "named_curve".
90
91=item "point-format" (B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>) <UTF8 string>
92
93Sets or gets the point_conversion_form for the I<key>. For a description of
94point_conversion_forms please see L<EC_POINT_new(3)>. Valid values are
95"uncompressed" or "compressed". The default value is "uncompressed".
96
97=item "group-check" (B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>) <UTF8 string>
98
99Sets or Gets the type of group check done when EVP_PKEY_param_check() is called.
100Valid values are "default", "named" and "named-nist".
101The "named" type checks that the domain parameters match the inbuilt curve parameters,
102"named-nist" is similar but also checks that the named curve is a nist curve.
103The "default" type does domain parameter validation for the OpenSSL default provider,
104but is equivalent to "named-nist" for the OpenSSL FIPS provider.
105
106=item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer>
107
108Setting this value to 0 indicates that the public key should not be included when
109encoding the private key. The default value of 1 will include the public key.
110
111=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
112
113The public key value in encoded EC point format conforming to Sec. 2.3.3 and
1142.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
115This parameter is used when importing or exporting the public key value with the
116EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
117
118Note, in particular, that the choice of point compression format used for
119encoding the exported value via EVP_PKEY_todata() depends on the underlying
120provider implementation.
121Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always
122opted for an encoding in compressed format, unconditionally.
123Since OpenSSL 3.0.8, the implementation has been changed to honor the
124B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT> parameter, if set, or to default
125to uncompressed format.
126
127=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
128
129The private key value.
130
131=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
132
133Used for getting and setting the encoding of an EC public key. The public key
134is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
135Curve Cryptography") standard.
136
137=item "qx" (B<OSSL_PKEY_PARAM_EC_PUB_X>) <unsigned integer>
138
139Used for getting the EC public key X component.
140
141=item "qy" (B<OSSL_PKEY_PARAM_EC_PUB_Y>) <unsigned integer>
142
143Used for getting the EC public key Y component.
144
145=item "default-digest" (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string>
146
147Getter that returns the default digest name.
148(Currently returns "SHA256" as of OpenSSL 3.0).
149
150=back
151
152The following Gettable types are also available for the built-in EC algorithm:
153
154=over 4
155
156=item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string>
157
158Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
159This field is only used for a binary field F2^m.
160
161=item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer>
162
163=item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer>
164
165=item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer>
166
167=item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer>
168
169=item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer>
170
171These fields are only used for a binary field F2^m.
172I<m> is the degree of the binary field.
173
174I<tp> is the middle bit of a trinomial so its value must be in the
175range m > tp > 0.
176
177I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such
178that m > k3 > k2 > k1 > 0
179
180=back
181
182=head2 EC key validation
183
184For EC keys, L<EVP_PKEY_param_check(3)> behaves in the following way:
185For the OpenSSL default provider it uses either
186L<EC_GROUP_check(3)> or L<EC_GROUP_check_named_curve(3)> depending on the flag
187EC_FLAG_CHECK_NAMED_GROUP.
188The OpenSSL FIPS provider uses L<EC_GROUP_check_named_curve(3)> in order to
189conform to SP800-56Ar3 I<Assurances of Domain-Parameter Validity>.
190
191For EC keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to
192L<EVP_PKEY_param_check(3)>.
193
194For EC keys, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_public_check_quick(3)>
195conform to SP800-56Ar3 I<ECC Full Public-Key Validation> and
196I<ECC Partial Public-Key Validation> respectively.
197
198For EC Keys, L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)>
199conform to SP800-56Ar3 I<Private key validity> and
200I<Owner Assurance of Pair-wise Consistency> respectively.
201
202=head1 EXAMPLES
203
204An B<EVP_PKEY> context can be obtained by calling:
205
206    EVP_PKEY_CTX *pctx =
207        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
208
209An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
210calling:
211
212    pkey = EVP_EC_gen("P-256");
213
214or like this:
215
216    EVP_PKEY *key = NULL;
217    OSSL_PARAM params[2];
218    EVP_PKEY_CTX *gctx =
219        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
220
221    EVP_PKEY_keygen_init(gctx);
222
223    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
224                                                 "P-256", 0);
225    params[1] = OSSL_PARAM_construct_end();
226    EVP_PKEY_CTX_set_params(gctx, params);
227
228    EVP_PKEY_generate(gctx, &key);
229
230    EVP_PKEY_print_private(bio_out, key, 0, NULL);
231    ...
232    EVP_PKEY_free(key);
233    EVP_PKEY_CTX_free(gctx);
234
235An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
236"K-571" named group by calling:
237
238    int use_cdh = 1;
239    EVP_PKEY *key = NULL;
240    OSSL_PARAM params[3];
241    EVP_PKEY_CTX *gctx =
242        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
243
244    EVP_PKEY_keygen_init(gctx);
245
246    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
247                                                 "K-571", 0);
248    /*
249     * This curve has a cofactor that is not 1 - so setting CDH mode changes
250     * the behaviour. For many curves the cofactor is 1 - so setting this has
251     * no effect.
252     */
253    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
254                                         &use_cdh);
255    params[2] = OSSL_PARAM_construct_end();
256    EVP_PKEY_CTX_set_params(gctx, params);
257
258    EVP_PKEY_generate(gctx, &key);
259    EVP_PKEY_print_private(bio_out, key, 0, NULL);
260    ...
261    EVP_PKEY_free(key);
262    EVP_PKEY_CTX_free(gctx);
263
264=head1 SEE ALSO
265
266L<EVP_EC_gen(3)>,
267L<EVP_KEYMGMT(3)>,
268L<EVP_PKEY(3)>,
269L<provider-keymgmt(7)>,
270L<EVP_SIGNATURE-ECDSA(7)>,
271L<EVP_KEYEXCH-ECDH(7)>
272
273=head1 COPYRIGHT
274
275Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
276
277Licensed under the Apache License 2.0 (the "License").  You may not use
278this file except in compliance with the License.  You can obtain a copy
279in the file LICENSE in the source distribution or at
280L<https://www.openssl.org/source/license.html>.
281
282=cut
283