doc/man7/EVP_PKEY-EC.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY-EC,
   6 EVP_KEYMGMT-EC
   7 - EVP_PKEY EC keytype and algorithm support
   8
   9 =head1 DESCRIPTION
  10
  11 The B<EC> keytype is implemented in OpenSSL's default provider.
  12
  13 =head2 Common EC parameters
  14
  15 The normal way of specifying domain parameters for an EC curve is via the
  16 curve name "group". For curves with no curve name, explicit parameters can be
  17 used that specify "field-type", "p", "a", "b", "generator" and "order".
  18 Explicit parameters are supported for backwards compatibility reasons, but they
  19 are not compliant with multiple standards (including RFC5915) which only allow
  20 named curves.
  21
  22 The following KeyGen/Gettable/Import/Export types are available for the
  23 built-in EC algorithm:
  24
  25 =over 4
  26
  27 =item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
  28
  29 The curve name.
  30
  31 =item "field-type" (B<OSSL_PKEY_PARAM_EC_FIELD_TYPE>) <UTF8 string>
  32
  33 The value should be either "prime-field" or "characteristic-two-field",
  34 which correspond to prime field Fp and binary field F2^m.
  35
  36 =item "p" (B<OSSL_PKEY_PARAM_EC_P>) <unsigned integer>
  37
  38 For a curve over Fp I<p> is the prime for the field. For a curve over F2^m I<p>
  39 represents the irreducible polynomial - each bit represents a term in the
  40 polynomial. Therefore, there will either be three or five bits set dependent on
  41 whether 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
  49 I<a> and I<b> represents the coefficients of the curve
  50 For Fp:   y^2 mod p = x^3 +ax + b mod p OR
  51 For F2^m: y^2 + xy = x^3 + ax^2 + b
  52
  53 I<seed> is an optional value that is for information purposes only.
  54 It represents the random number seed used to generate the coefficient I<b> from a
  55 random 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
  63 The I<generator> is a well defined point on the curve chosen for cryptographic
  64 operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
  65 Cryptography") standard. See EC_POINT_oct2point().
  66 Integers used for point multiplications will be between 0 and
  67 I<order> - 1.
  68 I<cofactor> is an optional value.
  69 I<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
  73 Gets a flag indicating whether the key or parameters were decoded from explicit
  74 curve 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
  78 Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
  79 if the value is zero. The cofactor variant multiplies the shared secret by the
  80 EC curve's cofactor (note for some curves the cofactor is 1).
  81
  82 =item "encoding" (B<OSSL_PKEY_PARAM_EC_ENCODING>) <UTF8 string>
  83
  84 Set the format used for serializing the EC group parameters.
  85 Valid 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
  89 Sets or gets the point_conversion_form for the I<key>. For a description of
  90 point_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
  95 Sets or Gets the type of group check done when EVP_PKEY_param_check() is called.
  96 Valid values are "default", "named" and "named-nist".
  97 The "named" type checks that the domain parameters match the inbuilt curve parameters,
  98 "named-nist" is similar but also checks that the named curve is a nist curve.
  99 The "default" type does domain parameter validation for the OpenSSL default provider,
 100 but is equivalent to "named-nist" for the OpenSSL fips provider.
 101
 102 =item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer>
 103
 104 Setting this value to 0 indicates that the public key should not be included when
 105 encoding the private key. The default value of 1 will include the public key.
 106
 107 See also L<EVP_KEYEXCH-ECDH(7)> for the related
 108 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
 109 per-operation basis.
 110
 111 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
 112
 113 The public key value in EC point format.
 114
 115 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
 116
 117 The private key value.
 118
 119 =item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
 120
 121 Used for getting and setting the encoding of an EC public key. The public key
 122 is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
 123 Curve Cryptography") standard.
 124
 125 =item "qx" (B<OSSL_PKEY_PARAM_EC_PUB_X>) <unsigned integer>
 126
 127 Used for getting the EC public key X component.
 128
 129 =item "qy" (B<OSSL_PKEY_PARAM_EC_PUB_Y>) <unsigned integer>
 130
 131 Used for getting the EC public key Y component.
 132
 133 =item (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string>
 134
 135 Getter that returns the default digest name.
 136 (Currently returns "SHA256" as of OpenSSL 3.0).
 137
 138 =back
 139
 140 The 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
 146 Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
 147 This 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
 159 These fields are only used for a binary field F2^m.
 160 I<m> is the degree of the binary field.
 161
 162 I<tp> is the middle bit of a trinomial so its value must be in the
 163 range m > tp > 0.
 164
 165 I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such
 166 that m > k3 > k2 > k1 > 0
 167
 168 =back
 169
 170 =head1 EXAMPLES
 171
 172 An 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
 177 An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
 178 calling:
 179
 180     pkey = EVP_EC_gen("P-256");
 181
 182 or 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
 203 An 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
 234 L<EVP_EC_gen(3)>,
 235 L<EVP_KEYMGMT(3)>,
 236 L<EVP_PKEY(3)>,
 237 L<provider-keymgmt(7)>,
 238 L<EVP_SIGNATURE-ECDSA(7)>,
 239 L<EVP_KEYEXCH-ECDH(7)>
 240
 241 =head1 COPYRIGHT
 242
 243 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
 244
 245 Licensed under the Apache License 2.0 (the "License").  You may not use
 246 this file except in compliance with the License.  You can obtain a copy
 247 in the file LICENSE in the source distribution or at
 248 L<https://www.openssl.org/source/license.html>.
 249
 250 =cut