| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support
|
|---|
| 6 |
|
|---|
| 7 | =head1 DESCRIPTION
|
|---|
| 8 |
|
|---|
| 9 | Key exchange support for the B<ECDH> key type.
|
|---|
| 10 |
|
|---|
| 11 | =head2 ECDH Key Exchange parameters
|
|---|
| 12 |
|
|---|
| 13 | =over 4
|
|---|
| 14 |
|
|---|
| 15 | =item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
|
|---|
| 16 |
|
|---|
| 17 | Sets or gets the ECDH mode of operation for the associated key exchange ctx.
|
|---|
| 18 |
|
|---|
| 19 | In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
|
|---|
| 20 | can be used to select between the plain Diffie-Hellman (DH) or Cofactor
|
|---|
| 21 | Diffie-Hellman (CDH) variants of the key exchange algorithm.
|
|---|
| 22 |
|
|---|
| 23 | When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
|
|---|
| 24 | on, off, or resetting it to the default for the private key associated with the
|
|---|
| 25 | given key exchange ctx.
|
|---|
| 26 |
|
|---|
| 27 | When getting, the value should be either 1 or 0, respectively signaling if the
|
|---|
| 28 | cofactor mode is on or off.
|
|---|
| 29 |
|
|---|
| 30 | See also L<provider-keymgmt(7)> for the related
|
|---|
| 31 | B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
|
|---|
| 32 | per-key basis.
|
|---|
| 33 |
|
|---|
| 34 | =item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string>
|
|---|
| 35 |
|
|---|
| 36 | Sets or gets the Key Derivation Function type to apply within the associated key
|
|---|
| 37 | exchange ctx.
|
|---|
| 38 |
|
|---|
| 39 | =item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string>
|
|---|
| 40 |
|
|---|
| 41 | Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
|
|---|
| 42 | associated with the given key exchange ctx.
|
|---|
| 43 |
|
|---|
| 44 | =item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string>
|
|---|
| 45 |
|
|---|
| 46 | Sets properties to be used upon look up of the implementation for the selected
|
|---|
| 47 | Digest algorithm for the Key Derivation Function associated with the given key
|
|---|
| 48 | exchange ctx.
|
|---|
| 49 |
|
|---|
| 50 | =item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer>
|
|---|
| 51 |
|
|---|
| 52 | Sets or gets the desired size for the output of the chosen Key Derivation Function
|
|---|
| 53 | associated with the given key exchange ctx.
|
|---|
| 54 | The length of the "kdf-outlen" parameter should not exceed that of a B<size_t>.
|
|---|
| 55 |
|
|---|
| 56 | =item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string>
|
|---|
| 57 |
|
|---|
| 58 | Sets the User Key Material to be used as part of the selected Key Derivation
|
|---|
| 59 | Function associated with the given key exchange ctx.
|
|---|
| 60 |
|
|---|
| 61 | =item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string ptr>
|
|---|
| 62 |
|
|---|
| 63 | Gets a pointer to the User Key Material to be used as part of the selected
|
|---|
| 64 | Key Derivation Function associated with the given key exchange ctx. Providers
|
|---|
| 65 | usually do not need to support this gettable parameter as its sole purpose
|
|---|
| 66 | is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
|
|---|
| 67 | function.
|
|---|
| 68 |
|
|---|
| 69 | =back
|
|---|
| 70 |
|
|---|
| 71 | =head1 EXAMPLES
|
|---|
| 72 |
|
|---|
| 73 | Keys for the host and peer must be generated as shown in
|
|---|
| 74 | L<EVP_PKEY-EC(7)/Examples> using the same curve name.
|
|---|
| 75 |
|
|---|
| 76 | The code to generate a shared secret for the normal case is identical to
|
|---|
| 77 | L<EVP_KEYEXCH-DH(7)/Examples>.
|
|---|
| 78 |
|
|---|
| 79 | To derive a shared secret on the host using the host's key and the peer's public
|
|---|
| 80 | key but also using X963KDF with a user key material:
|
|---|
| 81 |
|
|---|
| 82 | /* It is assumed that the host_key, peer_pub_key and ukm are set up */
|
|---|
| 83 | void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
|
|---|
| 84 | unsigned char *ukm, size_t ukm_len)
|
|---|
| 85 | {
|
|---|
| 86 | unsigned char secret[64];
|
|---|
| 87 | size_t out_len = sizeof(secret);
|
|---|
| 88 | size_t secret_len = out_len;
|
|---|
| 89 | unsigned int pad = 1;
|
|---|
| 90 | OSSL_PARAM params[6];
|
|---|
| 91 | EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
|
|---|
| 92 |
|
|---|
| 93 | EVP_PKEY_derive_init(dctx);
|
|---|
| 94 |
|
|---|
| 95 | params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
|
|---|
| 96 | params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
|
|---|
| 97 | "X963KDF", 0);
|
|---|
| 98 | params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
|
|---|
| 99 | "SHA1", 0);
|
|---|
| 100 | params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
|
|---|
| 101 | &out_len);
|
|---|
| 102 | params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
|
|---|
| 103 | ukm, ukm_len);
|
|---|
| 104 | params[5] = OSSL_PARAM_construct_end();
|
|---|
| 105 | EVP_PKEY_CTX_set_params(dctx, params);
|
|---|
| 106 |
|
|---|
| 107 | EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
|
|---|
| 108 | EVP_PKEY_derive(dctx, secret, &secret_len);
|
|---|
| 109 | ...
|
|---|
| 110 | OPENSSL_clear_free(secret, secret_len);
|
|---|
| 111 | EVP_PKEY_CTX_free(dctx);
|
|---|
| 112 | }
|
|---|
| 113 |
|
|---|
| 114 | =head1 SEE ALSO
|
|---|
| 115 |
|
|---|
| 116 | L<EVP_PKEY-EC(7)>
|
|---|
| 117 | L<EVP_PKEY(3)>,
|
|---|
| 118 | L<provider-keyexch(7)>,
|
|---|
| 119 | L<provider-keymgmt(7)>,
|
|---|
| 120 | L<OSSL_PROVIDER-default(7)>,
|
|---|
| 121 | L<OSSL_PROVIDER-FIPS(7)>,
|
|---|
| 122 |
|
|---|
| 123 | =head1 COPYRIGHT
|
|---|
| 124 |
|
|---|
| 125 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 126 |
|
|---|
| 127 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 128 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 129 | in the file LICENSE in the source distribution or at
|
|---|
| 130 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 131 |
|
|---|
| 132 | =cut
|
|---|
