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 following Import/Export types are available for the built-in EC algorithm:
  16
  17 =over 4
  18
  19 =item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <utf8 string>
  20
  21 The curve name.
  22
  23 =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
  24
  25 Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
  26 if the value is zero. The cofactor variant multiplies the shared secret by the
  27 EC curve's cofactor (note for some curves the cofactor is 1).
  28
  29
  30 See also L<EVP_KEYEXCH-ECDH(7)> for the related
  31 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
  32 per-operation basis.
  33
  34 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
  35
  36 The public key value in EC point format.
  37
  38 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
  39
  40 The private key value.
  41
  42 =item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string>
  43
  44 Used for getting and setting the encoding of the EC public key used in key
  45 exchange message for the TLS protocol.
  46
  47 =back
  48
  49 =head1 EXAMPLES
  50
  51 An B<EVP_PKEY> context can be obtained by calling:
  52
  53     EVP_PKEY_CTX *pctx =
  54         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
  55
  56 An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
  57 calling:
  58
  59     EVP_PKEY *key = NULL;
  60     OSSL_PARAM params[2];
  61     EVP_PKEY_CTX *gctx =
  62         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
  63
  64     EVP_PKEY_keygen_init(gctx);
  65
  66     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
  67                                                  "P-256", 0);
  68     params[1] = OSSL_PARAM_construct_end();
  69     EVP_PKEY_CTX_set_params(gctx, params);
  70
  71     EVP_PKEY_gen(gctx, &key);
  72
  73     EVP_PKEY_print_private(bio_out, key, 0, NULL);
  74     ...
  75     EVP_PKEY_free(key);
  76     EVP_PKEY_CTX_free(gctx);
  77
  78 An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
  79 "K-571" named group by calling:
  80
  81     int use_cdh = 1;
  82     EVP_PKEY *key = NULL;
  83     OSSL_PARAM params[3];
  84     EVP_PKEY_CTX *gctx =
  85         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
  86
  87     EVP_PKEY *key = NULL;
  88     OSSL_PARAM params[3];
  89     EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
  90
  91     EVP_PKEY_keygen_init(gctx);
  92
  93     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
  94                                                  "K-571", 0);
  95     /*
  96      * This curve has a cofactor that is not 1 - so setting CDH mode changes
  97      * the behaviour. For many curves the cofactor is 1 - so setting this has
  98      * no effect.
  99      */
 100     params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
 101                                          &use_cdh);
 102     params[2] = OSSL_PARAM_construct_end();
 103     EVP_PKEY_CTX_set_params(gctx, params);
 104
 105     EVP_PKEY_gen(gctx, &key);
 106     EVP_PKEY_print_private(bio_out, key, 0, NULL);
 107     ...
 108     EVP_PKEY_free(key);
 109     EVP_PKEY_CTX_free(gctx);
 110
 111 =head1 SEE ALSO
 112
 113 L<EVP_KEYMGMT(3)>,
 114 L<EVP_PKEY(3)>,
 115 L<provider-keymgmt(7)>,
 116 L<EVP_SIGNATURE-ECDSA(7)>,
 117 L<EVP_KEYEXCH-ECDH(7)>
 118
 119 =head1 COPYRIGHT
 120
 121 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 122
 123 Licensed under the Apache License 2.0 (the "License").  You may not use
 124 this file except in compliance with the License.  You can obtain a copy
 125 in the file LICENSE in the source distribution or at
 126 L<https://www.openssl.org/source/license.html>.
 127
 128 =cut