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 compability 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 wether 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
82=item "encoding" (B<OSSL_PKEY_PARAM_EC_ENCODING>) <UTF8 string>
83
84Set the format used for serializing the EC group parameters.
85Valid values are "explicit" or "named_curve". The default value is "named_curve".
86
87=item "point-format" (B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>) <UTF8 string>
88
89Sets or gets the point_conversion_form for the I<key>. For a description of
90point_conversion_forms please see L<EC_POINT_new(3)>. Valid values are
91"uncompressed" or "compressed". The default value is "uncompressed".
92
93=item "group-check" (B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>) <UTF8 string>
94
95Sets or Gets the type of group check done when EVP_PKEY_param_check() is called.
96Valid values are "default", "named" and "named-nist".
97The "named" type checks that the domain parameters match the inbuilt curve parameters,
98"named-nist" is similiar but also checks that the named curve is a nist curve.
99The "default" type does domain parameter validation for the OpenSSL default provider,
100but is equivalent to "named-nist" for the OpenSSL fips provider.
101
102=item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer>
103
104Setting this value to 0 indicates that the public key should not be included when
105encoding the private key. The default value of 1 will include the public key.
106
107See also L<EVP_KEYEXCH-ECDH(7)> for the related
108B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
109per-operation basis.
110
111=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
112
113The public key value in EC point format.
114
115=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
116
117The private key value.
118
119=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
120
121Used for getting and setting the encoding of an EC public key. The public key
122is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
123Curve Cryptography") standard.
124
125=item "qx" (B<OSSL_PKEY_PARAM_EC_PUB_X>) <unsigned integer>
126
127Used for getting the EC public key X component.
128
129=item "qy" (B<OSSL_PKEY_PARAM_EC_PUB_Y>) <unsigned integer>
130
131Used for getting the EC public key Y component.
132
133=item (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string>
134
135Getter that returns the default digest name.
136(Currently returns "SHA256" as of OpenSSL 3.0).
137
138=back
139
140The following Gettable types are also available for the built-in EC algorithm:
141
142=over 4
143
144=item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string>
145
146Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
147This field is only used for a binary field F2^m.
148
149=item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer>
150
151=item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer>
152
153=item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer>
154
155=item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer>
156
157=item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer>
158
159These fields are only used for a binary field F2^m.
160I<m> is the degree of the binary field.
161
162I<tp> is the middle bit of a trinomial so its value must be in the
163range m > tp > 0.
164
165I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such
166that m > k3 > k2 > k1 > 0
167
168=back
169
170=head1 EXAMPLES
171
172An B<EVP_PKEY> context can be obtained by calling:
173
174    EVP_PKEY_CTX *pctx =
175        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
176
177An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
178calling:
179
180    pkey = EVP_EC_gen("P-256");
181
182or like this:
183
184    EVP_PKEY *key = NULL;
185    OSSL_PARAM params[2];
186    EVP_PKEY_CTX *gctx =
187        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
188
189    EVP_PKEY_keygen_init(gctx);
190
191    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
192                                                 "P-256", 0);
193    params[1] = OSSL_PARAM_construct_end();
194    EVP_PKEY_CTX_set_params(gctx, params);
195
196    EVP_PKEY_generate(gctx, &key);
197
198    EVP_PKEY_print_private(bio_out, key, 0, NULL);
199    ...
200    EVP_PKEY_free(key);
201    EVP_PKEY_CTX_free(gctx);
202
203An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
204"K-571" named group by calling:
205
206    int use_cdh = 1;
207    EVP_PKEY *key = NULL;
208    OSSL_PARAM params[3];
209    EVP_PKEY_CTX *gctx =
210        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
211
212    EVP_PKEY_keygen_init(gctx);
213
214    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
215                                                 "K-571", 0);
216    /*
217     * This curve has a cofactor that is not 1 - so setting CDH mode changes
218     * the behaviour. For many curves the cofactor is 1 - so setting this has
219     * no effect.
220     */
221    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
222                                         &use_cdh);
223    params[2] = OSSL_PARAM_construct_end();
224    EVP_PKEY_CTX_set_params(gctx, params);
225
226    EVP_PKEY_generate(gctx, &key);
227    EVP_PKEY_print_private(bio_out, key, 0, NULL);
228    ...
229    EVP_PKEY_free(key);
230    EVP_PKEY_CTX_free(gctx);
231
232=head1 SEE ALSO
233
234L<EVP_EC_gen(3)>,
235L<EVP_KEYMGMT(3)>,
236L<EVP_PKEY(3)>,
237L<provider-keymgmt(7)>,
238L<EVP_SIGNATURE-ECDSA(7)>,
239L<EVP_KEYEXCH-ECDH(7)>
240
241=head1 COPYRIGHT
242
243Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
244
245Licensed under the Apache License 2.0 (the "License").  You may not use
246this file except in compliance with the License.  You can obtain a copy
247in the file LICENSE in the source distribution or at
248L<https://www.openssl.org/source/license.html>.
249
250=cut
251