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