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 compability 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 wether 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 similiar 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 =back
 126
 127 The following Gettable types are also available for the built-in EC algorithm:
 128
 129 =over 4
 130
 131 =item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string>
 132
 133 Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
 134 This field is only used for a binary field F2^m.
 135
 136 =item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer>
 137
 138 =item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer>
 139
 140 =item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer>
 141
 142 =item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer>
 143
 144 =item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer>
 145
 146 These fields are only used for a binary field F2^m.
 147 I<m> is the degree of the binary field.
 148
 149 I<tp> is the middle bit of a trinomial so its value must be in the
 150 range m > tp > 0.
 151
 152 I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such
 153 that m > k3 > k2 > k1 > 0
 154
 155 =back
 156
 157 =head1 EXAMPLES
 158
 159 An B<EVP_PKEY> context can be obtained by calling:
 160
 161     EVP_PKEY_CTX *pctx =
 162         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 163
 164 An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
 165 calling:
 166
 167     pkey = EVP_EC_gen("P-256");
 168
 169 or like this:
 170
 171     EVP_PKEY *key = NULL;
 172     OSSL_PARAM params[2];
 173     EVP_PKEY_CTX *gctx =
 174         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 175
 176     EVP_PKEY_keygen_init(gctx);
 177
 178     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
 179                                                  "P-256", 0);
 180     params[1] = OSSL_PARAM_construct_end();
 181     EVP_PKEY_CTX_set_params(gctx, params);
 182
 183     EVP_PKEY_generate(gctx, &key);
 184
 185     EVP_PKEY_print_private(bio_out, key, 0, NULL);
 186     ...
 187     EVP_PKEY_free(key);
 188     EVP_PKEY_CTX_free(gctx);
 189
 190 An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
 191 "K-571" named group by calling:
 192
 193     int use_cdh = 1;
 194     EVP_PKEY *key = NULL;
 195     OSSL_PARAM params[3];
 196     EVP_PKEY_CTX *gctx =
 197         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 198
 199     EVP_PKEY_keygen_init(gctx);
 200
 201     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
 202                                                  "K-571", 0);
 203     /*
 204      * This curve has a cofactor that is not 1 - so setting CDH mode changes
 205      * the behaviour. For many curves the cofactor is 1 - so setting this has
 206      * no effect.
 207      */
 208     params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
 209                                          &use_cdh);
 210     params[2] = OSSL_PARAM_construct_end();
 211     EVP_PKEY_CTX_set_params(gctx, params);
 212
 213     EVP_PKEY_generate(gctx, &key);
 214     EVP_PKEY_print_private(bio_out, key, 0, NULL);
 215     ...
 216     EVP_PKEY_free(key);
 217     EVP_PKEY_CTX_free(gctx);
 218
 219 =head1 SEE ALSO
 220
 221 L<EVP_EC_gen(3)>,
 222 L<EVP_KEYMGMT(3)>,
 223 L<EVP_PKEY(3)>,
 224 L<provider-keymgmt(7)>,
 225 L<EVP_SIGNATURE-ECDSA(7)>,
 226 L<EVP_KEYEXCH-ECDH(7)>
 227
 228 =head1 COPYRIGHT
 229
 230 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 231
 232 Licensed under the Apache License 2.0 (the "License").  You may not use
 233 this file except in compliance with the License.  You can obtain a copy
 234 in the file LICENSE in the source distribution or at
 235 L<https://www.openssl.org/source/license.html>.
 236
 237 =cut