EVP_PKEY-EC, EVP_KEYMGMT-EC - EVP_PKEY EC keytype and algorithm support
The EC keytype is implemented in OpenSSL's default provider.
The normal way of specifying domain parameters for an EC curve is via the curve
  name "group". For curves with no curve name, explicit parameters can
  be used that specify "field-type", "p", "a",
  "b", "generator" and "order". Explicit
  parameters are supported for backwards compatibility reasons, but they are not
  compliant with multiple standards (including RFC5915) which only allow named
  curves.
The following KeyGen/Gettable/Import/Export types are available
    for the built-in EC algorithm:
  - "group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8
    string>
- The curve name.
- "field-type" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8
    string>
- The value should be either "prime-field" or
      "characteristic-two-field", which correspond to prime field Fp
      and binary field F2^m.
- "p" (OSSL_PKEY_PARAM_EC_P) <unsigned integer>
- For a curve over Fp p is the prime for the field. For a curve over
      F2^m p represents the irreducible polynomial - each bit represents
      a term in the polynomial. Therefore, there will either be three or five
      bits set dependent on whether the polynomial is a trinomial or a
      pentanomial.
- "a" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>
- "b" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>
- "seed" (OSSL_PKEY_PARAM_EC_SEED) <octet
    string>
- a and b represents the coefficients of the curve For Fp: y^2
      mod p = x^3 +ax + b mod p OR For F2^m: y^2 + xy = x^3 + ax^2 + b
    seed is an optional value that is for information
        purposes only. It represents the random number seed used to generate the
        coefficient b from a random number. 
- "generator" (OSSL_PKEY_PARAM_EC_GENERATOR) <octet
    string>
- "order" (OSSL_PKEY_PARAM_EC_ORDER) <unsigned
    integer>
- "cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned
    integer>
- The generator is a well defined point on the curve chosen for
      cryptographic operations. The encoding conforms with Sec. 2.3.3 of the
      SECG SEC 1 ("Elliptic Curve Cryptography") standard. See
      EC_POINT_oct2point(). Integers used for point multiplications will
      be between 0 and order - 1. cofactor is an optional value.
      order multiplied by the cofactor gives the number of points
      on the curve.
- "decoded-from-explicit"
    (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS)
    <integer>
- Gets a flag indicating whether the key or parameters were decoded from
      explicit curve parameters. Set to 1 if so or 0 if a named curve was
    used.
- "use-cofactor-flag" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH)
    <integer>
- Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal
      EC DH if the value is zero. The cofactor variant multiplies the shared
      secret by the EC curve's cofactor (note for some curves the cofactor is
      1).
    See also EVP_KEYEXCH-ECDH(7) for the related
        OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE parameter that can be
        set on a per-operation basis. 
- "encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8
    string>
- Set the format used for serializing the EC group parameters. Valid values
      are "explicit" or "named_curve". The default value is
      "named_curve".
- "point-format"
    (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string>
- Sets or gets the point_conversion_form for the key. For a
      description of point_conversion_forms please see EC_POINT_new(3).
      Valid values are "uncompressed" or "compressed". The
      default value is "uncompressed".
- "group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE)
    <UTF8 string>
- Sets or Gets the type of group check done when
      EVP_PKEY_param_check() is called. Valid values are
      "default", "named" and "named-nist". The
      "named" type checks that the domain parameters match the inbuilt
      curve parameters, "named-nist" is similar but also checks that
      the named curve is a nist curve. The "default" type does domain
      parameter validation for the OpenSSL default provider, but is equivalent
      to "named-nist" for the OpenSSL FIPS provider.
- "include-public" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC)
    <integer>
- Setting this value to 0 indicates that the public key should not be
      included when encoding the private key. The default value of 1 will
      include the public key.
- "pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>
- The public key value in encoded EC point format conforming to Sec. 2.3.3
      and 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography")
      standard. This parameter is used when importing or exporting the public
      key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata()
      functions.
    Note, in particular, that the choice of point compression
        format used for encoding the exported value via EVP_PKEY_todata()
        depends on the underlying provider implementation. Before OpenSSL 3.0.8,
        the implementation of providers included with OpenSSL always opted for
        an encoding in compressed format, unconditionally. Since OpenSSL 3.0.8,
        the implementation has been changed to honor the
        OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT parameter, if set, or
        to default to uncompressed format. 
- "priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned
    integer>
- The private key value.
- "encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY)
    <octet string>
- Used for getting and setting the encoding of an EC public key. The public
      key is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1
      ("Elliptic Curve Cryptography") standard.
- "qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned
    integer>
- Used for getting the EC public key X component.
- "qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned
    integer>
- Used for getting the EC public key Y component.
- "default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST)
    <UTF8 string>
- Getter that returns the default digest name. (Currently returns
      "SHA256" as of OpenSSL 3.0).
The following Gettable types are also available for the built-in
    EC algorithm:
  - "basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8
    string>
- Supports the values "tpBasis" for a trinomial or
      "ppBasis" for a pentanomial. This field is only used for a
      binary field F2^m.
- "m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>
- "tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS)
    <integer>
- "k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1)
    <integer>
- "k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2)
    <integer>
- "k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3)
    <integer>
- These fields are only used for a binary field F2^m. m is the degree
      of the binary field.
    tp is the middle bit of a trinomial so its value must
        be in the range m > tp > 0. k1, k2 and k3 are used to get the middle
        bits of a pentanomial such that m > k3 > k2 > k1 > 0 
For EC keys, EVP_PKEY_param_check(3) behaves in the following way: For
  the OpenSSL default provider it uses either EC_GROUP_check(3) or
  EC_GROUP_check_named_curve(3) depending on the flag
  EC_FLAG_CHECK_NAMED_GROUP. The OpenSSL FIPS provider uses
  EC_GROUP_check_named_curve(3) in order to conform to SP800-56Ar3
  Assurances of Domain-Parameter Validity.For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to
    EVP_PKEY_param_check(3).
For EC keys, EVP_PKEY_public_check(3) and
    EVP_PKEY_public_check_quick(3) conform to SP800-56Ar3 ECC Full
    Public-Key Validation and ECC Partial Public-Key Validation
    respectively.
For EC Keys, EVP_PKEY_private_check(3) and
    EVP_PKEY_pairwise_check(3) conform to SP800-56Ar3 Private key
    validity and Owner Assurance of Pair-wise Consistency
    respectively.
An EVP_PKEY context can be obtained by calling:
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
An EVP_PKEY ECDSA or ECDH key can be generated with a
    "P-256" named group by calling:
    pkey = EVP_EC_gen("P-256");
or like this:
    EVP_PKEY *key = NULL;
    OSSL_PARAM params[2];
    EVP_PKEY_CTX *gctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
    EVP_PKEY_keygen_init(gctx);
    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                                 "P-256", 0);
    params[1] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(gctx, params);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);
An EVP_PKEY EC CDH (Cofactor Diffie-Hellman) key can be
    generated with a "K-571" named group by calling:
    int use_cdh = 1;
    EVP_PKEY *key = NULL;
    OSSL_PARAM params[3];
    EVP_PKEY_CTX *gctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
    EVP_PKEY_keygen_init(gctx);
    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                                 "K-571", 0);
    /*
     * This curve has a cofactor that is not 1 - so setting CDH mode changes
     * the behaviour. For many curves the cofactor is 1 - so setting this has
     * no effect.
     */
    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
                                         &use_cdh);
    params[2] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(gctx, params);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);
EVP_EC_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3),
  provider-keymgmt(7), EVP_SIGNATURE-ECDSA(7),
  EVP_KEYEXCH-ECDH(7)
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License").
    You may not use this file except in compliance with the License. You can
    obtain a copy in the file LICENSE in the source distribution or at
    <https://www.openssl.org/source/license.html>.