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