Make EVP_PKEY_CTX_[get|set]_ec_paramgen_curve_name more generic

[thirdparty/openssl.git] / doc / man7 / EVP_PKEY-EC.pod

=pod

=head1 NAME

EVP_PKEY-EC,
EVP_KEYMGMT-EC
- EVP_PKEY EC keytype and algorithm support

=head1 DESCRIPTION

The B<EC> keytype is implemented in OpenSSL's default provider.

=head2 Common EC parameters

The following Import/Export types are available for the built-in EC algorithm:

=over 4

=item "group-name" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <utf8 string>

The curve name.

=item "use-cofactor-flag" (B<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 L<EVP_KEYEXCH-ECDH(7)> for the related
B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
per-operation basis.

=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>

The public key value in EC point format.

=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>

The private key value.

=item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>

Used for getting and setting the encoding of the EC public key used in key
exchange message for the TLS protocol.

=back

=head1 EXAMPLES

An B<EVP_PKEY> context can be obtained by calling:

    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);

An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
calling:

    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_gen(gctx, &key);

    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);

An B<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 *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_gen(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);

=head1 SEE ALSO

L<EVP_KEYMGMT(3)>,
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_SIGNATURE-ECDSA(7)>,
L<EVP_KEYEXCH-ECDH(7)>

=head1 COPYRIGHT

Copyright 2020 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
L<https://www.openssl.org/source/license.html>.

=cut