Diffie Hellman

The Diffie-Hellman algorithm provides the capability for two communicating parties to agree upon a shared secret between them. Its an agreement scheme because both parties add material used to derive the key (as opposed to transport, where one party selects the key). The shared secret can then be used as the basis for some encryption key to be used for further communication.

If Alice and Bob wish to communicate with each other, they first agree between them a large prime number p, and a generator (or base) g (where 0 < g < p).

Alice chooses a secret integer a (her private key) and then calculates g^a mod p (which is her public key). Bob chooses his private key b, and calculates his public key in the same way.

Alice and Bob then send each other their public keys. Alice now knows a and Bob's public key g^b mod p. She is not able to calculate the value b from Bob's public key as this is a hard mathematical problem (known as the discrete logarithm problem). She can however calculate (g^b)^a mod p = g^ab mod p.

Bob knows b and g^a, so he can calculate (g^a)^b mod p = g^ab mod p. Therefore both Alice and Bob know a shared secret g^ab mod p. Eve who was listening in on the communication knows p, g, Alice's public key (g^a mod p) and Bob's public key (g^b mod p). She is unable to calculate the shared secret from these values.

In static-static mode both Alice and Bob retain their private/public keys over multiple communications. Therefore the resulting shared secret will be the same every time. In ephemeral-static mode one party will generate a new private/public key every time, thus a new shared secret will be generated.

Diffie-Hellman Standards

There are a number of standards relevant to Diffie-Hellman key agreement. Some of the key ones are:

• PKCS 3 defines the basic algorithm and data formats to be used.
• ANSI X9.42 is a later standard than PKCS 3 and provides further guidance on its use (note OpenSSL does not support ANSI X9.42 in the released versions - support is available in the as yet unreleased 1.0.2 and 1.1.0)
• RFC 2631 summarizes the key points of ANSI X9.42
• RFC 5114 defines 3 standard sets of parameters for use with Diffie-Hellman (OpenSSL will have built-in support for these parameters from OpenSSL 1.0.2 - not yet released)
• NIST SP 800-56A is a NIST publication that provides recommendations on the implementation of X9.42

Diffie-Hellman in SSL/TLS

There are three versions of Diffie-Hellman used in SSL/TLS.

• Anonymous Diffie-Hellman
• Fixed Diffie-Hellman
• Ephemeral Diffie-Hellman

Anonymous Diffie-Hellman uses Diffie-Hellman, but without authentication. Because the keys used in the exchange are not authenticated, the protocol is susceptible to Man-in-the-Middle attacks. Note: if you use this scheme, a call to SSL_get_peer_certificate will return NULL because you have selected an anonymous protocol. This is the only time SSL_get_peer_certificate is allowed to return NULL under normal circumstances.

You should not use Anonymous Diffie-Hellman. You can prohibit its use in your code by using "!ADH" in your call to SSL_set_cipher_list.

Fixed Diffie-Hellman embeds the server's public parameter in the certificate, and the CA then signs the certificate. That is, the certificate contains the Diffie-Hellman public-key parameters, and those parameters never change.

Ephemeral Diffie-Hellman uses temporary, public keys. Each instance or run of the protocol uses a different public key. The authenticity of the server's temporary key can be verified by checking the signature on the key. Because the public keys are temporary, a compromise of the server's long term signing key does not jeopardize the privacy of past sessions. This is known as Perfect Forward Secrecy (PFS).

You should always use Ephemeral Diffie-Hellman because it provides PFS. You can specify ephemeral methods by providing "kEECDH:kEDH" in your call to SSL_set_cipher_list.

Working with Parameters and Generating Keys

The first step with the Diffie-Hellman algorithm is to ensure that both parties are using the same set of parameters (i.e. the same values for p and g). Since parameter generation can be an expensive process this is normally done once in advance and then the same set of parameters are used over many key exchanges. A new set of parameters can be generated by OpenSSL, or alternatively there is support for built-in standard sets of parameters.

/* Use built-in parameters */
if(NULL == (params = EVP_PKEY_new())) handleErrors();
if(1 != EVP_PKEY_assign(params, EVP_PKEY_DHX, DH_get_2048_256())) handleErrors();

/* Create context for the key generation */
if(!(kctx = EVP_PKEY_CTX_new(params, NULL))) handleErrors();

/* Generate a new key */
if(1 != EVP_PKEY_keygen_init(kctx)) handleErrors();
if(1 != EVP_PKEY_keygen(kctx, &dhkey)) handleErrors();

/* Optional : useful if you want to check your private key*/
BIO* fp = BIO_new_fp(stdout, BIO_NOCLOSE);
EVP_PKEY_print_private(fp, dhkey, 0, NULL);

To generate your own parameters refer to EVP Key and Parameter Generation.

Note: The function DH_get_2048_256 is scheduled for release in OpenSSL 1.0.2; it is not available in 1.0.1e or earlier.

Generating a Shared Secret

Having obtained a private/public key pair you need to also obtain the public key of the other communicating party. Refer to EVP Key Agreement for information on how to agree a shared secret.

Using the Low Level APIs

Users of the OpenSSL library are expected to normally use the EVP method for working with Diffie Hellman as described above and on the EVP Key Agreement page. The EVP api is implemented by a lower level Diffie Hellman API. In some circumstances, expert users may need to use the low level api. This is not recommended for most users. However, if you need to use this then an example of use is shown below. The manual page for the low level API is available here: Manual:dh(3)

DH *privkey;
int codes;
int secret_size;

/* Generate the parameters to be used */
if(NULL == (privkey = DH_new())) handleErrors();
if(1 != DH_generate_parameters_ex(privkey, 2048, DH_GENERATOR_2, NULL)) handleErrors();

if(1 != DH_check(privkey, &codes)) handleErrors();
if(codes != 0)
{
    /* Problems have been found with the generated parameters */
    /* Handle these here - we'll just abort for this example */
    printf("DH_check failed\n");
    abort();
}

/* Generate the public and private key pair */
if(1 != DH_generate_key(privkey)) handleErrors();

/* Send the public key to the peer.
 * How this occurs will be specific to your situation (see main text below) */


/* Receive the public key from the peer. In this example we're just hard coding a value */
BIGNUM *pubkey = NULL;
if(0 == (BN_dec2bn(&pubkey, "01234567890123456789012345678901234567890123456789"))) handleErrors();

/* Compute the shared secret */
unsigned char *secret;
if(NULL == (secret = OPENSSL_malloc(sizeof(unsigned char) * (DH_size(privkey))))) handleErrors();

if(0 > (secret_size = DH_compute_key(secret, pubkey, privkey))) handleErrors();

/* Do something with the shared secret */
/* Note secret_size may be less than DH_size(privkey) */
printf("The shared secret is:\n");
BIO_dump_fp(stdout, secret, secret_size);

/* Clean up */
OPENSSL_free(secret);
BN_free(pubkey);
DH_free(privkey);

There are (currently) no DH_ level routines to read and write a public OR private key, but the generic PUBKEY and PrivateKey routines do so as an X.509 SubjectPublickKeyInfo structure (aka SPKI or PKCS#8). This includes the parameters plus the public key (and the private key for the PrivateKey routines) (see Manual:Pem(3)).

There are three possible cases:

• ephemeral parameters: A must send new parameters AND the public key to the peer (B), who needs to send back only their public key (although it may be convenient to embed it in an SPKI structure)
• static but undistributed parameters: effectively the same
• pre-distributed parameters: A only needs to send their public key, but may embed in an SPKI structure; B doesn't need to wait for A to get parameters but may wait anyway, and only needs to send B's public key but may embed it in an SPKI structure.

See also

• EVP Key Agreement
• Elliptic Curve Diffie Hellman
• EVP
• Libcrypto API