1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 DESCRIPTION 8*b077aed3SPierre Pronchery 9*b077aed3SPierre ProncheryKey exchange support for the B<ECDH> key type. 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery=head2 ECDH Key Exchange parameters 12*b077aed3SPierre Pronchery 13*b077aed3SPierre Pronchery=over 4 14*b077aed3SPierre Pronchery 15*b077aed3SPierre Pronchery=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer> 16*b077aed3SPierre Pronchery 17*b077aed3SPierre ProncherySets or gets the ECDH mode of operation for the associated key exchange ctx. 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryIn the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter 20*b077aed3SPierre Proncherycan be used to select between the plain Diffie-Hellman (DH) or Cofactor 21*b077aed3SPierre ProncheryDiffie-Hellman (CDH) variants of the key exchange algorithm. 22*b077aed3SPierre Pronchery 23*b077aed3SPierre ProncheryWhen setting, the value should be 1, 0 or -1, respectively forcing cofactor mode 24*b077aed3SPierre Proncheryon, off, or resetting it to the default for the private key associated with the 25*b077aed3SPierre Proncherygiven key exchange ctx. 26*b077aed3SPierre Pronchery 27*b077aed3SPierre ProncheryWhen getting, the value should be either 1 or 0, respectively signaling if the 28*b077aed3SPierre Proncherycofactor mode is on or off. 29*b077aed3SPierre Pronchery 30*b077aed3SPierre ProncherySee also L<provider-keymgmt(7)> for the related 31*b077aed3SPierre ProncheryB<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a 32*b077aed3SPierre Proncheryper-key basis. 33*b077aed3SPierre Pronchery 34*b077aed3SPierre Pronchery=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string> 35*b077aed3SPierre Pronchery 36*b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 37*b077aed3SPierre Pronchery 38*b077aed3SPierre Pronchery=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string> 39*b077aed3SPierre Pronchery 40*b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Pronchery=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string> 43*b077aed3SPierre Pronchery 44*b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer> 47*b077aed3SPierre Pronchery 48*b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Pronchery=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string> 51*b077aed3SPierre Pronchery 52*b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=back 55*b077aed3SPierre Pronchery 56*b077aed3SPierre Pronchery=head1 EXAMPLES 57*b077aed3SPierre Pronchery 58*b077aed3SPierre ProncheryKeys for the host and peer must be generated as shown in 59*b077aed3SPierre ProncheryL<EVP_PKEY-EC(7)/Examples> using the same curve name. 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryThe code to generate a shared secret for the normal case is identical to 62*b077aed3SPierre ProncheryL<EVP_KEYEXCH-DH(7)/Examples>. 63*b077aed3SPierre Pronchery 64*b077aed3SPierre ProncheryTo derive a shared secret on the host using the host's key and the peer's public 65*b077aed3SPierre Proncherykey but also using X963KDF with a user key material: 66*b077aed3SPierre Pronchery 67*b077aed3SPierre Pronchery /* It is assumed that the host_key, peer_pub_key and ukm are set up */ 68*b077aed3SPierre Pronchery void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key, 69*b077aed3SPierre Pronchery unsigned char *ukm, size_t ukm_len) 70*b077aed3SPierre Pronchery { 71*b077aed3SPierre Pronchery unsigned char secret[64]; 72*b077aed3SPierre Pronchery size_t out_len = sizeof(secret); 73*b077aed3SPierre Pronchery size_t secret_len = out_len; 74*b077aed3SPierre Pronchery unsigned int pad = 1; 75*b077aed3SPierre Pronchery OSSL_PARAM params[6]; 76*b077aed3SPierre Pronchery EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); 77*b077aed3SPierre Pronchery 78*b077aed3SPierre Pronchery EVP_PKEY_derive_init(dctx); 79*b077aed3SPierre Pronchery 80*b077aed3SPierre Pronchery params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); 81*b077aed3SPierre Pronchery params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE, 82*b077aed3SPierre Pronchery "X963KDF", 0); 83*b077aed3SPierre Pronchery params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST, 84*b077aed3SPierre Pronchery "SHA1", 0); 85*b077aed3SPierre Pronchery params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN, 86*b077aed3SPierre Pronchery &out_len); 87*b077aed3SPierre Pronchery params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM, 88*b077aed3SPierre Pronchery ukm, ukm_len); 89*b077aed3SPierre Pronchery params[5] = OSSL_PARAM_construct_end(); 90*b077aed3SPierre Pronchery EVP_PKEY_CTX_set_params(dctx, params); 91*b077aed3SPierre Pronchery 92*b077aed3SPierre Pronchery EVP_PKEY_derive_set_peer(dctx, peer_pub_key); 93*b077aed3SPierre Pronchery EVP_PKEY_derive(dctx, secret, &secret_len); 94*b077aed3SPierre Pronchery ... 95*b077aed3SPierre Pronchery OPENSSL_clear_free(secret, secret_len); 96*b077aed3SPierre Pronchery EVP_PKEY_CTX_free(dctx); 97*b077aed3SPierre Pronchery } 98*b077aed3SPierre Pronchery 99*b077aed3SPierre Pronchery=head1 SEE ALSO 100*b077aed3SPierre Pronchery 101*b077aed3SPierre ProncheryL<EVP_PKEY-EC(7)> 102*b077aed3SPierre ProncheryL<EVP_PKEY(3)>, 103*b077aed3SPierre ProncheryL<provider-keyexch(7)>, 104*b077aed3SPierre ProncheryL<provider-keymgmt(7)>, 105*b077aed3SPierre ProncheryL<OSSL_PROVIDER-default(7)>, 106*b077aed3SPierre ProncheryL<OSSL_PROVIDER-FIPS(7)>, 107*b077aed3SPierre Pronchery 108*b077aed3SPierre Pronchery=head1 COPYRIGHT 109*b077aed3SPierre Pronchery 110*b077aed3SPierre ProncheryCopyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. 111*b077aed3SPierre Pronchery 112*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 113*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 114*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 115*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 116*b077aed3SPierre Pronchery 117*b077aed3SPierre Pronchery=cut 118