1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_KEYEXCH-DH 6b077aed3SPierre Pronchery- DH Key Exchange algorithm support 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 DESCRIPTION 9b077aed3SPierre Pronchery 10*a7148ab3SEnji CooperKey exchange support for the B<DH> and B<DHX> key types. 11b077aed3SPierre Pronchery 12*a7148ab3SEnji CooperPlease note that although both key types support the same key exchange 13*a7148ab3SEnji Cooperoperations, they cannot be used together in a single key exchange. It 14*a7148ab3SEnji Cooperis not possible to use a private key of the B<DH> type in key exchange 15*a7148ab3SEnji Cooperwith the public key of B<DHX> type and vice versa. 16*a7148ab3SEnji Cooper 17*a7148ab3SEnji Cooper=head2 DH and DHX key exchange parameters 18b077aed3SPierre Pronchery 19b077aed3SPierre Pronchery=over 4 20b077aed3SPierre Pronchery 21b077aed3SPierre Pronchery=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> 22b077aed3SPierre Pronchery 23b077aed3SPierre ProncherySets the padding mode for the associated key exchange ctx. 24b077aed3SPierre ProncherySetting a value of 1 will turn padding on. 25b077aed3SPierre ProncherySetting a value of 0 will turn padding off. 26b077aed3SPierre ProncheryIf padding is off then the derived shared secret may be smaller than the 27b077aed3SPierre Proncherylargest possible secret size. 28b077aed3SPierre ProncheryIf padding is on then the derived shared secret will have its first bytes 29b077aed3SPierre Proncheryfilled with zeros where necessary to make the shared secret the same size as 30b077aed3SPierre Proncherythe largest possible secret size. 31b077aed3SPierre ProncheryThe padding mode parameter is ignored (and padding implicitly enabled) when 32b077aed3SPierre Proncherythe KDF type is set to "X942KDF-ASN1" (B<OSSL_KDF_NAME_X942KDF_ASN1>). 33b077aed3SPierre Pronchery 34b077aed3SPierre Pronchery=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <UTF8 string> 35b077aed3SPierre Pronchery 36b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 37b077aed3SPierre Pronchery 38b077aed3SPierre Pronchery=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <UTF8 string> 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 41b077aed3SPierre Pronchery 42b077aed3SPierre Pronchery=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <UTF8 string> 43b077aed3SPierre Pronchery 44b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 45b077aed3SPierre Pronchery 46b077aed3SPierre Pronchery=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <unsigned integer> 47b077aed3SPierre Pronchery 48b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 49b077aed3SPierre Pronchery 50b077aed3SPierre Pronchery=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet string> 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncherySee L<provider-keyexch(7)/Common Key Exchange parameters>. 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <octet string ptr> 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncherySee L<provider-kdf(7)/KDF Parameters>. 57b077aed3SPierre Pronchery 58b077aed3SPierre Pronchery=back 59b077aed3SPierre Pronchery 60b077aed3SPierre Pronchery=head1 EXAMPLES 61b077aed3SPierre Pronchery 62b077aed3SPierre ProncheryThe examples assume a host and peer both generate keys using the same 63b077aed3SPierre Proncherynamed group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>. 64b077aed3SPierre ProncheryBoth the host and peer transfer their public key to each other. 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryTo convert the peer's generated key pair to a public key in DER format in order 67b077aed3SPierre Proncheryto transfer to the host: 68b077aed3SPierre Pronchery 69b077aed3SPierre Pronchery EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ 70b077aed3SPierre Pronchery unsigned char *peer_pub_der = NULL; 71b077aed3SPierre Pronchery int peer_pub_der_len; 72b077aed3SPierre Pronchery 73b077aed3SPierre Pronchery peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); 74b077aed3SPierre Pronchery ... 75b077aed3SPierre Pronchery OPENSSL_free(peer_pub_der); 76b077aed3SPierre Pronchery 77b077aed3SPierre ProncheryTo convert the received peer's public key from DER format on the host: 78b077aed3SPierre Pronchery 79b077aed3SPierre Pronchery const unsigned char *pd = peer_pub_der; 80b077aed3SPierre Pronchery EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); 81b077aed3SPierre Pronchery ... 82b077aed3SPierre Pronchery EVP_PKEY_free(peer_pub_key); 83b077aed3SPierre Pronchery 84b077aed3SPierre ProncheryTo derive a shared secret on the host using the host's key and the peer's public 85b077aed3SPierre Proncherykey: 86b077aed3SPierre Pronchery 87b077aed3SPierre Pronchery /* It is assumed that the host_key and peer_pub_key are set up */ 88b077aed3SPierre Pronchery void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) 89b077aed3SPierre Pronchery { 90b077aed3SPierre Pronchery unsigned int pad = 1; 91b077aed3SPierre Pronchery OSSL_PARAM params[2]; 92b077aed3SPierre Pronchery unsigned char *secret = NULL; 93b077aed3SPierre Pronchery size_t secret_len = 0; 94b077aed3SPierre Pronchery EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); 95b077aed3SPierre Pronchery 96b077aed3SPierre Pronchery EVP_PKEY_derive_init(dctx); 97b077aed3SPierre Pronchery 98b077aed3SPierre Pronchery /* Optionally set the padding */ 99b077aed3SPierre Pronchery params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); 100b077aed3SPierre Pronchery params[1] = OSSL_PARAM_construct_end(); 101b077aed3SPierre Pronchery EVP_PKEY_CTX_set_params(dctx, params); 102b077aed3SPierre Pronchery 103b077aed3SPierre Pronchery EVP_PKEY_derive_set_peer(dctx, peer_pub_key); 104b077aed3SPierre Pronchery 105b077aed3SPierre Pronchery /* Get the size by passing NULL as the buffer */ 106b077aed3SPierre Pronchery EVP_PKEY_derive(dctx, NULL, &secret_len); 107b077aed3SPierre Pronchery secret = OPENSSL_zalloc(secret_len); 108b077aed3SPierre Pronchery 109b077aed3SPierre Pronchery EVP_PKEY_derive(dctx, secret, &secret_len); 110b077aed3SPierre Pronchery ... 111b077aed3SPierre Pronchery OPENSSL_clear_free(secret, secret_len); 112b077aed3SPierre Pronchery EVP_PKEY_CTX_free(dctx); 113b077aed3SPierre Pronchery } 114b077aed3SPierre Pronchery 115b077aed3SPierre ProncheryVery similar code can be used by the peer to derive the same shared secret 116b077aed3SPierre Proncheryusing the host's public key and the peer's generated key pair. 117b077aed3SPierre Pronchery 118b077aed3SPierre Pronchery=head1 SEE ALSO 119b077aed3SPierre Pronchery 120b077aed3SPierre ProncheryL<EVP_PKEY-DH(7)>, 121b077aed3SPierre ProncheryL<EVP_PKEY-FFC(7)>, 122b077aed3SPierre ProncheryL<EVP_PKEY(3)>, 123b077aed3SPierre ProncheryL<provider-keyexch(7)>, 124b077aed3SPierre ProncheryL<provider-keymgmt(7)>, 125b077aed3SPierre ProncheryL<OSSL_PROVIDER-default(7)>, 126b077aed3SPierre ProncheryL<OSSL_PROVIDER-FIPS(7)>, 127b077aed3SPierre Pronchery 128b077aed3SPierre Pronchery=head1 COPYRIGHT 129b077aed3SPierre Pronchery 130*a7148ab3SEnji CooperCopyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 131b077aed3SPierre Pronchery 132b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 133b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 134b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 135b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 136b077aed3SPierre Pronchery 137b077aed3SPierre Pronchery=cut 138