| 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 | See L<provider-keyexch(7)/Common Key Exchange parameters>.
|
|---|
| 37 |
|
|---|
| 38 | =item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string>
|
|---|
| 39 |
|
|---|
| 40 | See L<provider-keyexch(7)/Common Key Exchange parameters>.
|
|---|
| 41 |
|
|---|
| 42 | =item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string>
|
|---|
| 43 |
|
|---|
| 44 | See L<provider-keyexch(7)/Common Key Exchange parameters>.
|
|---|
| 45 |
|
|---|
| 46 | =item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer>
|
|---|
| 47 |
|
|---|
| 48 | See L<provider-keyexch(7)/Common Key Exchange parameters>.
|
|---|
| 49 |
|
|---|
| 50 | =item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string>
|
|---|
| 51 |
|
|---|
| 52 | See L<provider-keyexch(7)/Common Key Exchange parameters>.
|
|---|
| 53 |
|
|---|
| 54 | =back
|
|---|
| 55 |
|
|---|
| 56 | =head1 EXAMPLES
|
|---|
| 57 |
|
|---|
| 58 | Keys for the host and peer must be generated as shown in
|
|---|
| 59 | L<EVP_PKEY-EC(7)/Examples> using the same curve name.
|
|---|
| 60 |
|
|---|
| 61 | The code to generate a shared secret for the normal case is identical to
|
|---|
| 62 | L<EVP_KEYEXCH-DH(7)/Examples>.
|
|---|
| 63 |
|
|---|
| 64 | To derive a shared secret on the host using the host's key and the peer's public
|
|---|
| 65 | key but also using X963KDF with a user key material:
|
|---|
| 66 |
|
|---|
| 67 | /* It is assumed that the host_key, peer_pub_key and ukm are set up */
|
|---|
| 68 | void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
|
|---|
| 69 | unsigned char *ukm, size_t ukm_len)
|
|---|
| 70 | {
|
|---|
| 71 | unsigned char secret[64];
|
|---|
| 72 | size_t out_len = sizeof(secret);
|
|---|
| 73 | size_t secret_len = out_len;
|
|---|
| 74 | unsigned int pad = 1;
|
|---|
| 75 | OSSL_PARAM params[6];
|
|---|
| 76 | EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
|
|---|
| 77 |
|
|---|
| 78 | EVP_PKEY_derive_init(dctx);
|
|---|
| 79 |
|
|---|
| 80 | params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
|
|---|
| 81 | params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
|
|---|
| 82 | "X963KDF", 0);
|
|---|
| 83 | params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
|
|---|
| 84 | "SHA1", 0);
|
|---|
| 85 | params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
|
|---|
| 86 | &out_len);
|
|---|
| 87 | params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
|
|---|
| 88 | ukm, ukm_len);
|
|---|
| 89 | params[5] = OSSL_PARAM_construct_end();
|
|---|
| 90 | EVP_PKEY_CTX_set_params(dctx, params);
|
|---|
| 91 |
|
|---|
| 92 | EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
|
|---|
| 93 | EVP_PKEY_derive(dctx, secret, &secret_len);
|
|---|
| 94 | ...
|
|---|
| 95 | OPENSSL_clear_free(secret, secret_len);
|
|---|
| 96 | EVP_PKEY_CTX_free(dctx);
|
|---|
| 97 | }
|
|---|
| 98 |
|
|---|
| 99 | =head1 SEE ALSO
|
|---|
| 100 |
|
|---|
| 101 | L<EVP_PKEY-EC(7)>
|
|---|
| 102 | L<EVP_PKEY(3)>,
|
|---|
| 103 | L<provider-keyexch(7)>,
|
|---|
| 104 | L<provider-keymgmt(7)>,
|
|---|
| 105 | L<OSSL_PROVIDER-default(7)>,
|
|---|
| 106 | L<OSSL_PROVIDER-FIPS(7)>,
|
|---|
| 107 |
|
|---|
| 108 | =head1 COPYRIGHT
|
|---|
| 109 |
|
|---|
| 110 | Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 111 |
|
|---|
| 112 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 113 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 114 | in the file LICENSE in the source distribution or at
|
|---|
| 115 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 116 |
|
|---|
| 117 | =cut
|
|---|
