# Difference between revisions of "Diffie-Hellman parameters"

m (Added pre-encoded groups) |
m (Added section on parameter validation.) |
||

Line 61: | Line 61: | ||

Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]! | Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]! | ||

+ | |||

+ | == Validating Parameters == | ||

+ | |||

+ | The Diffie-Hellman parameters should be validated after loading. To do so, you will call <tt>DH_check</tt>. <tt>DH_check</tt> return 0 or a bitmask values of the following: | ||

+ | |||

+ | * DH_CHECK_P_NOT_PRIME (0x01) | ||

+ | * DH_CHECK_P_NOT_SAFE_PRIME (0x02) | ||

+ | * DH_UNABLE_TO_CHECK_GENERATOR (0x04) | ||

+ | * DH_NOT_SUITABLE_GENERATOR (0x08) | ||

+ | |||

+ | The validation code might look as follows (error checking omitted for clarity): | ||

+ | |||

+ | <pre>BIO* bio = ...; | ||

+ | DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL); | ||

+ | |||

+ | int rc, codes = 0; | ||

+ | rc = DH_check(dh, &codes); | ||

+ | assert(rc == 1); | ||

+ | |||

+ | if(BN_is_word(dh->g, 2)) | ||

+ | { | ||

+ | long residue = BN_mod_word(dh->p, 24); | ||

+ | if(residue == 11 || residue == 23) { | ||

+ | codes &= ~DH_NOT_SUITABLE_GENERATOR; | ||

+ | } | ||

+ | } | ||

+ | |||

+ | if (codes & DH_UNABLE_TO_CHECK_GENERATOR) | ||

+ | printf("DH_check: failed to test generator\n"); | ||

+ | |||

+ | if (codes & DH_NOT_SUITABLE_GENERATOR) | ||

+ | printf("DH_check: g is not a suitable generator\n"); | ||

+ | |||

+ | if (codes & DH_CHECK_P_NOT_PRIME) | ||

+ | printf("DH_check: p is not prime\n"); | ||

+ | |||

+ | if (codes & DH_CHECK_P_NOT_SAFE_PRIME) | ||

+ | printf("DH_check: p is not a safe prime\n");</pre> | ||

+ | |||

+ | The additional call to `BN_mod_word(dh->p, 24)` (and unmasking of <tt>DH_NOT_SUITABLE_GENERATOR</tt>) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when <tt>g = 2</tt>; while the IETF's primes are congruent to 23 when <tt>g = 2</tt>. Without the test, the IETF parameters would fail validation. For details, see [http://crypto.stackexchange.com/questions/12961/diffie-hellman-parameter-check-when-g-2-must-p-mod-24-11 Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?)]. | ||

== Elliptic curve Diffie-Hellman == | == Elliptic curve Diffie-Hellman == |

## Revision as of 22:27, 16 January 2014

To use perfect forward secrecy cipher suites, you must set up Diffie-Hellman parameters (on the server side), or the PFS cipher suites will be silently ignored.

## Contents

## Diffie-Hellman

`SSL_CTX_set_tmp_dh`

is used to set the Diffie-Hellman parameters for a context. One of the easiest ways to get Diffie-Hellman parameters to use with this function is to generate random Diffie-Hellman parameters with the dhparam command-line program with the `-C`

option, and embed the resulting code fragment in your program. For example, `openssl dhparam -C 2236`

might result in:

#ifndef HEADER_DH_H #include <openssl/dh.h> #endif DH *get_dh2236() { static unsigned char dh2236_p[]={ 0x0F,0x52,0xE5,0x24,0xF5,0xFA,0x9D,0xDC,0xC6,0xAB,0xE6,0x04, 0xE4,0x20,0x89,0x8A,0xB4,0xBF,0x27,0xB5,0x4A,0x95,0x57,0xA1, 0x06,0xE7,0x30,0x73,0x83,0x5E,0xC9,0x23,0x11,0xED,0x42,0x45, 0xAC,0x49,0xD3,0xE3,0xF3,0x34,0x73,0xC5,0x7D,0x00,0x3C,0x86, 0x63,0x74,0xE0,0x75,0x97,0x84,0x1D,0x0B,0x11,0xDA,0x04,0xD0, 0xFE,0x4F,0xB0,0x37,0xDF,0x57,0x22,0x2E,0x96,0x42,0xE0,0x7C, 0xD7,0x5E,0x46,0x29,0xAF,0xB1,0xF4,0x81,0xAF,0xFC,0x9A,0xEF, 0xFA,0x89,0x9E,0x0A,0xFB,0x16,0xE3,0x8F,0x01,0xA2,0xC8,0xDD, 0xB4,0x47,0x12,0xF8,0x29,0x09,0x13,0x6E,0x9D,0xA8,0xF9,0x5D, 0x08,0x00,0x3A,0x8C,0xA7,0xFF,0x6C,0xCF,0xE3,0x7C,0x3B,0x6B, 0xB4,0x26,0xCC,0xDA,0x89,0x93,0x01,0x73,0xA8,0x55,0x3E,0x5B, 0x77,0x25,0x8F,0x27,0xA3,0xF1,0xBF,0x7A,0x73,0x1F,0x85,0x96, 0x0C,0x45,0x14,0xC1,0x06,0xB7,0x1C,0x75,0xAA,0x10,0xBC,0x86, 0x98,0x75,0x44,0x70,0xD1,0x0F,0x20,0xF4,0xAC,0x4C,0xB3,0x88, 0x16,0x1C,0x7E,0xA3,0x27,0xE4,0xAD,0xE1,0xA1,0x85,0x4F,0x1A, 0x22,0x0D,0x05,0x42,0x73,0x69,0x45,0xC9,0x2F,0xF7,0xC2,0x48, 0xE3,0xCE,0x9D,0x74,0x58,0x53,0xE7,0xA7,0x82,0x18,0xD9,0x3D, 0xAF,0xAB,0x40,0x9F,0xAA,0x4C,0x78,0x0A,0xC3,0x24,0x2D,0xDB, 0x12,0xA9,0x54,0xE5,0x47,0x87,0xAC,0x52,0xFE,0xE8,0x3D,0x0B, 0x56,0xED,0x9C,0x9F,0xFF,0x39,0xE5,0xE5,0xBF,0x62,0x32,0x42, 0x08,0xAE,0x6A,0xED,0x88,0x0E,0xB3,0x1A,0x4C,0xD3,0x08,0xE4, 0xC4,0xAA,0x2C,0xCC,0xB1,0x37,0xA5,0xC1,0xA9,0x64,0x7E,0xEB, 0xF9,0xD3,0xF5,0x15,0x28,0xFE,0x2E,0xE2,0x7F,0xFE,0xD9,0xB9, 0x38,0x42,0x57,0x03, }; static unsigned char dh2236_g[]={ 0x02, }; DH *dh; if ((dh=DH_new()) == NULL) return(NULL); dh->p=BN_bin2bn(dh2236_p,sizeof(dh2236_p),NULL); dh->g=BN_bin2bn(dh2236_g,sizeof(dh2236_g),NULL); if ((dh->p == NULL) || (dh->g == NULL)) { DH_free(dh); return(NULL); } return(dh); }

which can then be used like this:

DH *dh = get_dh2236 (); if (1 != SSL_CTX_set_tmp_dh (ctx, dh)) error (); DH_free (dh);

Be sure to choose a bit length appropriate to the security level you want to achieve, although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be incompatible with older versions of NSS. Even worse, it appears that versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits!

## Validating Parameters

The Diffie-Hellman parameters should be validated after loading. To do so, you will call `DH_check`. `DH_check` return 0 or a bitmask values of the following:

* DH_CHECK_P_NOT_PRIME (0x01) * DH_CHECK_P_NOT_SAFE_PRIME (0x02) * DH_UNABLE_TO_CHECK_GENERATOR (0x04) * DH_NOT_SUITABLE_GENERATOR (0x08)

The validation code might look as follows (error checking omitted for clarity):

BIO* bio = ...; DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL); int rc, codes = 0; rc = DH_check(dh, &codes); assert(rc == 1); if(BN_is_word(dh->g, 2)) { long residue = BN_mod_word(dh->p, 24); if(residue == 11 || residue == 23) { codes &= ~DH_NOT_SUITABLE_GENERATOR; } } if (codes & DH_UNABLE_TO_CHECK_GENERATOR) printf("DH_check: failed to test generator\n"); if (codes & DH_NOT_SUITABLE_GENERATOR) printf("DH_check: g is not a suitable generator\n"); if (codes & DH_CHECK_P_NOT_PRIME) printf("DH_check: p is not prime\n"); if (codes & DH_CHECK_P_NOT_SAFE_PRIME) printf("DH_check: p is not a safe prime\n");

The additional call to `BN_mod_word(dh->p, 24)` (and unmasking of `DH_NOT_SUITABLE_GENERATOR`) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when `g = 2`; while the IETF's primes are congruent to 23 when `g = 2`. Without the test, the IETF parameters would fail validation. For details, see Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?).

## Elliptic curve Diffie-Hellman

For elliptic curve Diffie-Hellman, you can do something like this:

EC_KEY *ecdh = EC_KEY_new_by_curve_name (NID_X9_62_prime256v1); if (! ecdh) error (); if (1 != SSL_CTX_set_tmp_ecdh (ctx, ecdh)) error (); EC_KEY_free (ecdh);

Or, in OpenSSL 1.0.2 (not yet released, as of Feb 2013) and higher, you should be able to do:

SSL_CTX_set_ecdh_auto (ctx, 1)

For more information, see Elliptic Curve Diffie Hellman and Elliptic Curve Cryptography.

## RFC 3526 PEM Encoded Groups

Below are three Diffie-Hellman MODP groups specified in RFC 3526, More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE). They can be used with `PEM_read_bio_DHparams` and a memory `BIO`. RFC 3526 also offers 1536-bit, 6144-bit and 8192-bit primes.

static const char g_dh2048_sz[] = "-----BEGIN DH PARAMETERS-----\n" "MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n" "IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n" "awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n" "mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n" "fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n" "5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n" "-----END DH PARAMETERS-----"; static const char g_dh3072_sz[] = "-----BEGIN DH PARAMETERS-----\n" "MIIBiAKCAYEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n" "IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n" "awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n" "mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n" "fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n" "5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n" "fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n" "ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqTrS\n" "yv//////////AgEC\n" "-----END DH PARAMETERS-----"; static const char g_dh4096_sz[] = "-----BEGIN DH PARAMETERS-----\n" "MIICCAKCAgEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n" "IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n" "awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n" "mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n" "fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n" "5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n" "fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n" "ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqSEI\n" "ARpyPBKnh+bXiHGaEL26WyaZwycYavTiPBqUaDS2FQvaJYPpyirUTOjbu8LbBN6O\n" "+S6O/BQfvsqmKHxZR05rwF2ZspZPoJDDoiM7oYZRW+ftH2EpcM7i16+4G912IXBI\n" "HNAGkSfVsFqpk7TqmI2P3cGG/7fckKbAj030Nck0BjGZ//////////8CAQI=\n" "-----END DH PARAMETERS-----";