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 ga 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 gb 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 (gb)a mod p = gab mod p.

Bob knows b and ga, so he can calculate (ga)b mod p = gab mod p. Therefore both Alice and Bob know a shared secret gab mod p. Eve who was listening in on the communication knows p, g, Alice's public key (ga mod p) and Bob's public key (gb 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.

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)

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.

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.

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)

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.