---
title: "DH Key Exchange"
source_url: https://dev.digicert.com/trustcore-sdk/crypto-interface/asymmetric-key-algorithms/dh-key-exchange.html
---

The process for Diffie-Hellman key exchange in Crypto Interface is analogous to that for [ECDH key exchange](https://dev.digicert.com/md/trustcore-sdk/crypto-interface/asymmetric-key-algorithms/ecdh-key-exchange.md), except the domain parameters define a cyclic group in a finite field rather than on an elliptic curve. The domain parameters may be set by choosing one of the predefined built-in safe groups (see, for example, RFC5114, RFC3526, or RFC7919), or by setting the domain parameters directly in the context.


> **Tip**
>
> The word “context” rather than “key” is used with respect to Diffie-Hellman, but those two words are essentially interchangeable.


The following methods may be used to allocate a context:

- `CRYPTO_INTERFACE_DH_allocate`
- `CRYPTO_INTERFACE_DH_allocateServer`
- `CRYPTO_INTERFACE_DH_allocateClientAux`

The first API, `CRYPTO_INTERFACE_DH_allocate`, does not set any domain parameters.

The other two APIs, `CRYPTO_INTERFACE_DH_allocateServer` and `CRYPTO_INTERFACE_DH_allocateClientAux`, take in a `groupNum` parameter from the header `${MSS_SRC_PKG}/src/dh.h`. In addition, the `allocateServer` API generates a private/public key pair, while the allocate client API generates only the private key. For example, if a server is used to perform allocation and key generation on the 2048-bit group known as group 14, call:

```c
CRYPTO_INTERFACE_DH_allocateServer (g_pRandomContext, &pMyNewPrivCtx, DH_GROUP_14);
```

To obtain the public key to send to the client, call:

```c
CRYPTO_INTERFACE_DH_getPublicKey (pMyNewPrivCtx, &pMyPubKey, &myPubLen);
```

A buffer is allocated to hold “my private key” (`pMyNewPrivCtx`) in big-endian byte array form, and `pMyPubKey` is set to its location. Once the client’s (i.e., other party’s) public key is obtained, a copy of the shared secret may be generated by calling:

```c
CRYPTO_INTERFACE_DH_computeKeyExchangeEx(pMyNewPrivCtx, NULL, pOtherPublicKey, otherPubLen, &pSharedSecret, &sharedSecretLen);
```

`pMyNewPrivCtx` is still in `diffieHellmanContext` form, but the other party’s public key is in big-endian byte array form. A buffer to hold the resulting shared secret is allocated, and `pSharedSecret` is set to its location. To perform exponent blinding for a higher security but lower performance trade-off, a non-`NULL` RNG `pRandomContext` may be passed for the second parameter.


> **Important**
>
> The shared secret should never be used directly by an application, but should instead be digested or input into a KDF scheme to obtain usable key material.


## Complete example

A complete example using alternative APIs may be found at:

```c
${MSS_SRC_PKG}/src/crypto_interface/example/crypto_interface_dh_example.c
```

To perform asymmetric key clean up and free memory allocated for a key, call the appropriate method:

- `CRYPTO_INTERFACE_RSA_freeKeyAux`
- `CRYPTO_INTERFACE_EC_deleteKeyAux`
- `CRYPTO_INTERFACE_DSA_freeKey`
- `CRYPTO_INTERFACE_DH_freeDhContext`

However, for a key stored inside an `AsymmetricKey` structure, use the `CRYPTO_uninitAsymmetricKey` API instead to free all memory associated with the underlying key.