Allow ECDHE and DHE as forward-compatible aliases for EECDH and EDH

see RT openssl#3203

Future versions of OpenSSL use the canonical terms "ECDHE" and "DHE"
as configuration strings and compilation constants.  This patch
introduces aliases so that the stable 1.0.2 branch can be
forward-compatible with code and configuration scripts that use the
normalized terms, while avoiding changing any library output for
stable users.

Signed-off-by: Kurt Roeckx <[email protected]>
Reviewed-by: Matt Caswell <[email protected]>

Author: dkg

doc/apps/ciphers.pod

@@ -177,12 +177,12 @@ cipher suites using RSA key exchange.
 cipher suites using DH key agreement and DH certificates signed by CAs with RSA
 and DSS keys or either respectively.
 
-=item B<kEDH>
+=item B<kDHE>, B<kEDH>
 
 cipher suites using ephemeral DH key agreement, including anonymous cipher
 suites.
 
-=item B<EDH>
+=item B<DHE>, B<EDH>
 
 cipher suites using authenticated ephemeral DH key agreement.
 
@@ -200,12 +200,12 @@ cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
 cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
 keys or either respectively.
 
-=item B<kEECDH>
+=item B<kECDHE>, B<kEECDH>
 
 cipher suites using ephemeral ECDH key agreement, including anonymous
 cipher suites.
 
-=item B<EECDHE>
+=item B<ECDHE>, B<EECDH>
 
 cipher suites using authenticated ephemeral ECDH key agreement.
 

doc/ssl/SSL_CIPHER_get_name.pod

@@ -109,13 +109,24 @@ If SSL_CIPHER_description() cannot handle a built-in cipher, the according
 description of the cipher property is B<unknown>. This case should not
 occur.
 
+The standard terminology for ephemeral Diffie-Hellman schemes is DHE
+(finite field) or ECDHE (elliptic curve).  This version of OpenSSL
+idiosyncratically reports these schemes as EDH and EECDH, even though
+it also accepts the standard terminology.
+
+It is recommended to use the standard terminology (DHE and ECDHE)
+during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of
+configuration.  OpenSSL versions after 1.0.2 will report the standard
+terms via SSL_CIPHER_get_name and SSL_CIPHER_description.
+
 =head1 RETURN VALUES
 
 See DESCRIPTION
 
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,
-L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>
+L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>,
+L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>
 
 =cut

doc/ssl/SSL_CTX_set_cipher_list.pod

@@ -41,7 +41,7 @@ RSA export ciphers with a keylength of 512 bits for the RSA key require
 a temporary 512 bit RSA key, as typically the supplied key has a length
 of 1024 bit (see
 L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
-RSA ciphers using EDH need a certificate and key and additional DH-parameters
+RSA ciphers using DHE need a certificate and key and additional DH-parameters
 (see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
 
 A DSA cipher can only be chosen, when a DSA certificate is available.

doc/ssl/SSL_CTX_set_options.pod

@@ -165,7 +165,7 @@ can only be used for signature operations (namely under export ciphers
 with restricted RSA keylength). By setting this option, ephemeral
 RSA keys are always used. This option breaks compatibility with the
 SSL/TLS specifications and may lead to interoperability problems with
-clients and should therefore never be used. Ciphers with EDH (ephemeral
+clients and should therefore never be used. Ciphers with DHE (ephemeral
 Diffie-Hellman) key exchange should be used instead.
 
 =item SSL_OP_CIPHER_SERVER_PREFERENCE

doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod

@@ -70,7 +70,7 @@ the TLS standard, when the RSA key can be used for signing only, that is
 for export ciphers. Using ephemeral RSA key exchange for other purposes
 violates the standard and can break interoperability with clients.
 It is therefore strongly recommended to not use ephemeral RSA key
-exchange and use EDH (Ephemeral Diffie-Hellman) key exchange instead
+exchange and use DHE (Ephemeral Diffie-Hellman) key exchange instead
 in order to achieve forward secrecy (see
 L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
 

doc/ssleay.txt

@@ -6026,7 +6026,7 @@ one at a time, or use 'aliases' to specify the preference and order for
 the ciphers.
 
 There are a large number of aliases, but the most importaint are
-kRSA, kDHr, kDHd and kEDH for key exchange types.
+kRSA, kDHr, kDHd and kDHE for key exchange types.
 
 aRSA, aDSS, aNULL and aDH for authentication
 DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers

ssl/ssl.h

@@ -245,11 +245,13 @@ extern "C" {
 #define SSL_TXT_kDHd		"kDHd"
 #define SSL_TXT_kDH 		"kDH"
 #define SSL_TXT_kEDH		"kEDH"
+#define SSL_TXT_kDHE		"kDHE" /* alias for kEDH */
 #define SSL_TXT_kKRB5     	"kKRB5"
 #define SSL_TXT_kECDHr		"kECDHr"
 #define SSL_TXT_kECDHe		"kECDHe"
 #define SSL_TXT_kECDH		"kECDH"
 #define SSL_TXT_kEECDH		"kEECDH"
+#define SSL_TXT_kECDHE		"kECDHE" /* alias for kEECDH */
 #define SSL_TXT_kPSK            "kPSK"
 #define SSL_TXT_kGOST		"kGOST"
 #define SSL_TXT_kSRP		"kSRP"
@@ -269,10 +271,12 @@ extern "C" {
 #define	SSL_TXT_DSS		"DSS"
 #define SSL_TXT_DH		"DH"
 #define SSL_TXT_EDH		"EDH" /* same as "kEDH:-ADH" */
+#define SSL_TXT_DHE		"DHE" /* alias for EDH */
 #define SSL_TXT_ADH		"ADH"
 #define SSL_TXT_RSA		"RSA"
 #define SSL_TXT_ECDH		"ECDH"
 #define SSL_TXT_EECDH		"EECDH" /* same as "kEECDH:-AECDH" */
+#define SSL_TXT_ECDHE		"ECDHE" /* alias for ECDHE" */
 #define SSL_TXT_AECDH		"AECDH"
 #define SSL_TXT_ECDSA		"ECDSA"
 #define SSL_TXT_KRB5      	"KRB5"

ssl/ssl3.h

@@ -155,11 +155,17 @@ extern "C" {
 #define SSL3_CK_DH_RSA_DES_192_CBC3_SHA 	0x03000010
 
 #define SSL3_CK_EDH_DSS_DES_40_CBC_SHA		0x03000011
+#define SSL3_CK_DHE_DSS_DES_40_CBC_SHA          SSL3_CK_EDH_DSS_DES_40_CBC_SHA
 #define SSL3_CK_EDH_DSS_DES_64_CBC_SHA		0x03000012
+#define SSL3_CK_DHE_DSS_DES_64_CBC_SHA		SSL3_CK_EDH_DSS_DES_64_CBC_SHA
 #define SSL3_CK_EDH_DSS_DES_192_CBC3_SHA	0x03000013
+#define SSL3_CK_DHE_DSS_DES_192_CBC3_SHA	SSL3_CK_EDH_DSS_DES_192_CBC3_SHA
 #define SSL3_CK_EDH_RSA_DES_40_CBC_SHA		0x03000014
+#define SSL3_CK_DHE_RSA_DES_40_CBC_SHA		SSL3_CK_EDH_RSA_DES_40_CBC_SHA
 #define SSL3_CK_EDH_RSA_DES_64_CBC_SHA		0x03000015
+#define SSL3_CK_DHE_RSA_DES_64_CBC_SHA		SSL3_CK_EDH_RSA_DES_64_CBC_SHA
 #define SSL3_CK_EDH_RSA_DES_192_CBC3_SHA	0x03000016
+#define SSL3_CK_DHE_RSA_DES_192_CBC3_SHA	SSL3_CK_EDH_RSA_DES_192_CBC3_SHA
 
 #define SSL3_CK_ADH_RC4_40_MD5			0x03000017
 #define SSL3_CK_ADH_RC4_128_MD5			0x03000018
@@ -213,6 +219,17 @@ extern "C" {
 #define SSL3_TXT_DH_RSA_DES_64_CBC_SHA		"DH-RSA-DES-CBC-SHA"
 #define SSL3_TXT_DH_RSA_DES_192_CBC3_SHA 	"DH-RSA-DES-CBC3-SHA"
 
+#define SSL3_TXT_DHE_DSS_DES_40_CBC_SHA		"EXP-DHE-DSS-DES-CBC-SHA"
+#define SSL3_TXT_DHE_DSS_DES_64_CBC_SHA		"DHE-DSS-DES-CBC-SHA"
+#define SSL3_TXT_DHE_DSS_DES_192_CBC3_SHA	"DHE-DSS-DES-CBC3-SHA"
+#define SSL3_TXT_DHE_RSA_DES_40_CBC_SHA		"EXP-DHE-RSA-DES-CBC-SHA"
+#define SSL3_TXT_DHE_RSA_DES_64_CBC_SHA		"DHE-RSA-DES-CBC-SHA"
+#define SSL3_TXT_DHE_RSA_DES_192_CBC3_SHA	"DHE-RSA-DES-CBC3-SHA"
+
+/* This next block of six "EDH" labels is for backward compatibility
+   with older versions of OpenSSL.  New code should use the six "DHE"
+   labels above instead:
+ */
 #define SSL3_TXT_EDH_DSS_DES_40_CBC_SHA		"EXP-EDH-DSS-DES-CBC-SHA"
 #define SSL3_TXT_EDH_DSS_DES_64_CBC_SHA		"EDH-DSS-DES-CBC-SHA"
 #define SSL3_TXT_EDH_DSS_DES_192_CBC3_SHA	"EDH-DSS-DES-CBC3-SHA"

ssl/ssl_ciph.c

@@ -242,6 +242,7 @@ static const SSL_CIPHER cipher_aliases[]={
 	{0,SSL_TXT_kDHd,0,    SSL_kDHd,  0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_kDH,0,     SSL_kDHr|SSL_kDHd,0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_kEDH,0,    SSL_kEDH,  0,0,0,0,0,0,0,0},
+	{0,SSL_TXT_kDHE,0,    SSL_kEDH,  0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_DH,0,      SSL_kDHr|SSL_kDHd|SSL_kEDH,0,0,0,0,0,0,0,0},
 
 	{0,SSL_TXT_kKRB5,0,   SSL_kKRB5, 0,0,0,0,0,0,0,0},
@@ -250,6 +251,7 @@ static const SSL_CIPHER cipher_aliases[]={
 	{0,SSL_TXT_kECDHe,0,  SSL_kECDHe,0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_kECDH,0,   SSL_kECDHr|SSL_kECDHe,0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_kEECDH,0,  SSL_kEECDH,0,0,0,0,0,0,0,0},
+	{0,SSL_TXT_kECDHE,0,  SSL_kEECDH,0,0,0,0,0,0,0,0},
 	{0,SSL_TXT_ECDH,0,    SSL_kECDHr|SSL_kECDHe|SSL_kEECDH,0,0,0,0,0,0,0,0},
 
         {0,SSL_TXT_kPSK,0,    SSL_kPSK,  0,0,0,0,0,0,0,0},
@@ -274,7 +276,9 @@ static const SSL_CIPHER cipher_aliases[]={
 
 	/* aliases combining key exchange and server authentication */
 	{0,SSL_TXT_EDH,0,     SSL_kEDH,~SSL_aNULL,0,0,0,0,0,0,0},
+	{0,SSL_TXT_DHE,0,     SSL_kEDH,~SSL_aNULL,0,0,0,0,0,0,0},
 	{0,SSL_TXT_EECDH,0,   SSL_kEECDH,~SSL_aNULL,0,0,0,0,0,0,0},
+	{0,SSL_TXT_ECDHE,0,   SSL_kEECDH,~SSL_aNULL,0,0,0,0,0,0,0},
 	{0,SSL_TXT_NULL,0,    0,0,SSL_eNULL, 0,0,0,0,0,0},
 	{0,SSL_TXT_KRB5,0,    SSL_kKRB5,SSL_aKRB5,0,0,0,0,0,0,0},
 	{0,SSL_TXT_RSA,0,     SSL_kRSA,SSL_aRSA,0,0,0,0,0,0,0},
@@ -327,6 +331,19 @@ static const SSL_CIPHER cipher_aliases[]={
 	{0,SSL_TXT_HIGH,0,    0,0,0,0,0,SSL_HIGH,  0,0,0},
 	/* FIPS 140-2 approved ciphersuite */
 	{0,SSL_TXT_FIPS,0,    0,0,~SSL_eNULL,0,0,SSL_FIPS,  0,0,0},
+       /* "DHE-" aliases to "EDH-" labels (for forward compatibility) */
+	{0,SSL3_TXT_DHE_DSS_DES_40_CBC_SHA,0,
+         SSL_kDHE,SSL_aDSS,SSL_DES,SSL_SHA1,SSL_SSLV3,SSL_EXPORT|SSL_EXP40,0,0,0,},
+	{0,SSL3_TXT_DHE_DSS_DES_64_CBC_SHA,0,
+         SSL_kDHE,SSL_aDSS,SSL_DES,SSL_SHA1,SSL_SSLV3,SSL_NOT_EXP|SSL_LOW,0,0,0,},
+	{0,SSL3_TXT_DHE_DSS_DES_192_CBC3_SHA,0,
+         SSL_kDHE,SSL_aDSS,SSL_3DES,SSL_SHA1,SSL_SSLV3,SSL_NOT_EXP|SSL_HIGH|SSL_FIPS,0,0,0,},
+	{0,SSL3_TXT_DHE_RSA_DES_40_CBC_SHA,0,
+         SSL_kDHE,SSL_aRSA,SSL_DES,SSL_SHA1,SSL_SSLV3,SSL_EXPORT|SSL_EXP40,0,0,0,},
+	{0,SSL3_TXT_DHE_RSA_DES_64_CBC_SHA,0,
+         SSL_kDHE,SSL_aRSA,SSL_DES,SSL_SHA1,SSL_SSLV3,SSL_NOT_EXP|SSL_LOW,0,0,0,},
+	{0,SSL3_TXT_DHE_RSA_DES_192_CBC3_SHA,0,
+         SSL_kDHE,SSL_aRSA,SSL_3DES,SSL_SHA1,SSL_SSLV3,SSL_NOT_EXP|SSL_HIGH|SSL_FIPS,0,0,0,},
 	};
 /* Search for public key algorithm with given name and 
  * return its pkey_id if it is available. Otherwise return 0

ssl/ssl_locl.h

@@ -292,10 +292,12 @@
 #define SSL_kDHr		0x00000002L /* DH cert, RSA CA cert */
 #define SSL_kDHd		0x00000004L /* DH cert, DSA CA cert */
 #define SSL_kEDH		0x00000008L /* tmp DH key no DH cert */
+#define SSL_kDHE		SSL_kEDH /* forward-compatible synonym */
 #define SSL_kKRB5		0x00000010L /* Kerberos5 key exchange */
 #define SSL_kECDHr		0x00000020L /* ECDH cert, RSA CA cert */
 #define SSL_kECDHe		0x00000040L /* ECDH cert, ECDSA CA cert */
 #define SSL_kEECDH		0x00000080L /* ephemeral ECDH */
+#define SSL_kECDHE		SSL_kEECDH /* forward-compatible synonym */
 #define SSL_kPSK		0x00000100L /* PSK */
 #define SSL_kGOST       0x00000200L /* GOST key exchange */
 #define SSL_kSRP        0x00000400L /* SRP */

ssl/tls1.h

@@ -555,12 +555,12 @@ SSL_CTX_callback_ctrl(ssl,SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB,(void (*)(void))cb)
 #define TLS1_CK_ECDH_RSA_WITH_AES_256_GCM_SHA384        0x0300C032
 
 /* XXX
- * Inconsistency alert:
- * The OpenSSL names of ciphers with ephemeral DH here include the string
- * "DHE", while elsewhere it has always been "EDH".
- * (The alias for the list of all such ciphers also is "EDH".)
- * The specifications speak of "EDH"; maybe we should allow both forms
- * for everything. */
+* Backward compatibility alert:
++ * Older versions of OpenSSL gave some DHE ciphers names with "EDH"
++ * instead of "DHE".  Going forward, we should be using DHE
++ * everywhere, though we may indefinitely maintain aliases for users
++ * or configurations that used "EDH"
++ */
 #define TLS1_TXT_RSA_EXPORT1024_WITH_RC4_56_MD5		"EXP1024-RC4-MD5"
 #define TLS1_TXT_RSA_EXPORT1024_WITH_RC2_CBC_56_MD5	"EXP1024-RC2-CBC-MD5"
 #define TLS1_TXT_RSA_EXPORT1024_WITH_DES_CBC_SHA	"EXP1024-DES-CBC-SHA"