Diffie Hellman

The Diffie-Hellman algorithm provides the capability for two communicating parties to agree a shared secret between them. This 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: ftp://ftp.rsasecurity.com/pub/pkcs/ascii/pkcs-3.asc
• 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)
• RFC 2631 summarises the key points of ANSI X9.42: http://www.ietf.org/rfc/rfc2631.txt
• 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): http://www.ietf.org/rfc/rfc5114

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_set1_DH(params,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();

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 Derivation for information on how to derive 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 Derivation 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: http://www.openssl.org/docs/crypto/dh.html

	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, 1024, 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. In this example we just write it out to a file */
	BIO *bp;
	if(NULL == (bp = BIO_new_file("out.dhparams", "wb"))) handleErrors();
	if(1 != i2d_DHparams_bio(bp, privkey)) handleErrors();
	BIO_free(bp);

	/* 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 */
	printf("The shared secret is:\n");
	BIO_dump_fp(stdout, secret, DH_size(privkey));

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

See also

• EVP
• Libcrypto API