diff options
Diffstat (limited to 'doc/man7/EVP_KEYEXCH-DH.pod')
-rw-r--r-- | doc/man7/EVP_KEYEXCH-DH.pod | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod new file mode 100644 index 0000000000..9e9cee7dce --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-DH.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-DH +- DH Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B<DH> key type. + +=head2 DH key exchange parameters + +=over 4 + +=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> + +See L<provider-keyexch(7)/Common Key Exchange parameters>. + +=back + +=head1 EXAMPLES + +The examples assume a host and peer both generate keys using the same +named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>. +Both the host and peer transfer their public key to each other. + +To convert the peer's generated key pair to a public key in DER format in order +to transfer to the host: + + EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */ + unsigned char *peer_pub_der = NULL; + int peer_pub_der_len; + + peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der); + ... + OPENSSL_free(peer_pub_der); + +To convert the received peer's public key from DER format on the host: + + const unsigned char *pd = peer_pub_der; + EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len); + ... + EVP_PKEY_free(peer_pub_key); + +To derive a shared secret on the host using the host's key and the peer's public +key: + /* It is assumed that the host_key and peer_pub_key are set up */ + void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key) + { + unsigned int pad = 1; + OSSL_PARAM params[2]; + unsigned char *secret = NULL; + size_t secret_len = 0; + EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL); + + EVP_PKEY_derive_init(dctx); + + /* Optionally set the padding */ + params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad); + params[1] = OSSL_PARAM_construct_end(); + EVP_PKEY_CTX_set_params(dctx, params); + + EVP_PKEY_derive_set_peer(dctx, peer_pub_key); + + /* Get the size by passing NULL as the buffer */ + EVP_PKEY_derive(dctx, NULL, &secret_len); + secret = OPENSSL_zalloc(secret_len); + + EVP_PKEY_derive(dctx, secret, &secret_len); + ... + OPENSSL_clear_free(secret, secret_len); + EVP_PKEY_CTX_free(dctx); + } + +Very similar code can be used by the peer to derive the same shared secret +using the host's public key and the peer's generated key pair. + +=head1 SEE ALSO + +L<EVP_PKEY-DH(7)>, +L<EVP_PKEY-FFC(7)>, +L<EVP_PKEY(3)>, +L<provider-keyexch(7)>, +L<provider-keymgmt(7)>, +L<OSSL_PROVIDER-default(7)>, +L<OSSL_PROVIDER-FIPS(7)>, + +=head1 COPYRIGHT + +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |