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 See also L<EVP_KEYEXCH-ECDH(7)> for the related
  83 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
  84 per-operation basis.
  85
  86 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
  87
  88 The public key value in EC point format.
  89
  90 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
  91
  92 The private key value.
  93
  94 =item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
  95
  96 Used for getting and setting the encoding of the EC public key used in key
  97 exchange message for the TLS protocol.
  98
  99 =back
 100
 101 The following Gettable types are also available for the built-in EC algorithm:
 102
 103 =over 4
 104
 105 =item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <utf8 string>
 106
 107 Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial.
 108 This field is only used for a binary field F2^m.
 109
 110 =item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer>
 111
 112 =item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer>
 113
 114 =item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer>
 115
 116 =item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer>
 117
 118 =item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer>
 119
 120 These fields are only used for a binary field F2^m.
 121 I<m> is the degree of the binary field.
 122
 123 I<tp> is the middle bit of a trinomial so its value must be in the
 124 range m > tp > 0.
 125
 126 I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such
 127 that m > k3 > k2 > k1 > 0
 128
 129 =back
 130
 131 =head1 EXAMPLES
 132
 133 An B<EVP_PKEY> context can be obtained by calling:
 134
 135     EVP_PKEY_CTX *pctx =
 136         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 137
 138 An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
 139 calling:
 140
 141     EVP_PKEY *key = NULL;
 142     OSSL_PARAM params[2];
 143     EVP_PKEY_CTX *gctx =
 144         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 145
 146     EVP_PKEY_keygen_init(gctx);
 147
 148     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
 149                                                  "P-256", 0);
 150     params[1] = OSSL_PARAM_construct_end();
 151     EVP_PKEY_CTX_set_params(gctx, params);
 152
 153     EVP_PKEY_gen(gctx, &key);
 154
 155     EVP_PKEY_print_private(bio_out, key, 0, NULL);
 156     ...
 157     EVP_PKEY_free(key);
 158     EVP_PKEY_CTX_free(gctx);
 159
 160 An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
 161 "K-571" named group by calling:
 162
 163     int use_cdh = 1;
 164     EVP_PKEY *key = NULL;
 165     OSSL_PARAM params[3];
 166     EVP_PKEY_CTX *gctx =
 167         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 168
 169     EVP_PKEY_keygen_init(gctx);
 170
 171     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
 172                                                  "K-571", 0);
 173     /*
 174      * This curve has a cofactor that is not 1 - so setting CDH mode changes
 175      * the behaviour. For many curves the cofactor is 1 - so setting this has
 176      * no effect.
 177      */
 178     params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
 179                                          &use_cdh);
 180     params[2] = OSSL_PARAM_construct_end();
 181     EVP_PKEY_CTX_set_params(gctx, params);
 182
 183     EVP_PKEY_gen(gctx, &key);
 184     EVP_PKEY_print_private(bio_out, key, 0, NULL);
 185     ...
 186     EVP_PKEY_free(key);
 187     EVP_PKEY_CTX_free(gctx);
 188
 189 =head1 SEE ALSO
 190
 191 L<EVP_KEYMGMT(3)>,
 192 L<EVP_PKEY(3)>,
 193 L<provider-keymgmt(7)>,
 194 L<EVP_SIGNATURE-ECDSA(7)>,
 195 L<EVP_KEYEXCH-ECDH(7)>
 196
 197 =head1 COPYRIGHT
 198
 199 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 200
 201 Licensed under the Apache License 2.0 (the "License").  You may not use
 202 this file except in compliance with the License.  You can obtain a copy
 203 in the file LICENSE in the source distribution or at
 204 L<https://www.openssl.org/source/license.html>.
 205
 206 =cut