backport changes to ciphers(1) man page

Backport of patch:
add ECC strings to ciphers(1), point out difference between DH and ECDH

and backport of other other assorted fixes to this man page

 * Make a clear distinction between DH and ECDH key exchange.
 * Group all key exchange cipher suite identifiers, first DH then ECDH
 * add descriptions for all supported *DH* identifiers
 * add ECDSA authentication descriptions
 * add example showing how to disable all suites that offer no
   authentication or encryption
 * update status of static DH (it's now supported)
 * backport descriptions of AES128, AES256, AESGCM
 * backport descriptions of CAMELLIA128, CAMELLIA256
 * backport listing of standard names for ECC cipher suites
   and TLSv1.2 cipher suites
 * backport description of PSK cipher suites

diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
index f44aa00a2fdb5ffd5e5979a5641c6bcc10279166..695a7df12b443f501b628e0804cd6e736348ccd5 100644 (file)
--- a/doc/apps/ciphers.pod
+++ b/doc/apps/ciphers.pod
@@ -36,7 +36,7 @@ SSL v2 and for SSL v3/TLS v1.
 
 =item B<-V>
 
-Like B<-V>, but include cipher suite codes in output (hex format).
+Like B<-v>, but include cipher suite codes in output (hex format).
 
 =item B<-ssl3>
 
@@ -116,8 +116,8 @@ specified.
 =item B<COMPLEMENTOFDEFAULT>
 
 the ciphers included in B<ALL>, but not enabled by default. Currently
-this is B<ADH>. Note that this rule does not cover B<eNULL>, which is
-not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
+this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>,
+which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
 
 =item B<ALL>
 
@@ -165,21 +165,58 @@ included.
 =item B<aNULL>
 
 the cipher suites offering no authentication. This is currently the anonymous
-DH algorithms. These cipher suites are vulnerable to a "man in the middle"
-attack and so their use is normally discouraged.
+DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
+to a "man in the middle" attack and so their use is normally discouraged.
 
 =item B<kRSA>, B<RSA>
 
 cipher suites using RSA key exchange.
 
+=item B<kDHr>, B<kDHd>, B<kDH>
+
+cipher suites using DH key agreement and DH certificates signed by CAs with RSA
+and DSS keys or either respectively.
+
 =item B<kEDH>
 
-cipher suites using ephemeral DH key agreement.
+cipher suites using ephemeral DH key agreement, including anonymous cipher
+suites.
 
-=item B<kDHr>, B<kDHd>
+=item B<EDH>
 
-cipher suites using DH key agreement and DH certificates signed by CAs with RSA
-and DSS keys respectively. Not implemented.
+cipher suites using authenticated ephemeral DH key agreement.
+
+=item B<ADH>
+
+anonymous DH cipher suites, note that this does not include anonymous Elliptic
+Curve DH (ECDH) cipher suites.
+
+=item B<DH>
+
+cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
+
+=item B<kECDHr>, B<kECDHe>, B<kECDH>
+
+cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
+keys or either respectively.
+
+=item B<kEECDH>
+
+cipher suites using ephemeral ECDH key agreement, including anonymous
+cipher suites.
+
+=item B<EECDHE>
+
+cipher suites using authenticated ephemeral ECDH key agreement.
+
+=item B<AECDH>
+
+anonymous Elliptic Curve Diffie Hellman cipher suites.
+
+=item B<ECDH>
+
+cipher suites using ECDH key exchange, including anonymous, ephemeral and
+fixed ECDH.
 
 =item B<aRSA>
 
@@ -192,32 +229,41 @@ cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
 =item B<aDH>
 
 cipher suites effectively using DH authentication, i.e. the certificates carry
-DH keys.  Not implemented.
+DH keys.
+
+=item B<aECDH>
+
+cipher suites effectively using ECDH authentication, i.e. the certificates
+carry ECDH keys.
+
+=item B<aECDSA>, B<ECDSA>
+
+cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
+keys.
 
 =item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
 
 ciphers suites using FORTEZZA key exchange, authentication, encryption or all
 FORTEZZA algorithms. Not implemented.
 
-=item B<TLSv1>, B<SSLv3>, B<SSLv2>
-
-TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively.
-
-=item B<DH>
+=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2>
 
-cipher suites using DH, including anonymous DH.
+TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note:
+there are no ciphersuites specific to TLS v1.1.
 
-=item B<ADH>
+=item B<AES128>, B<AES256>, B<AES>
 
-anonymous DH cipher suites.
+cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
 
-=item B<AES>
+=item B<AESGCM>
 
-cipher suites using AES.
+AES in Galois Counter Mode (GCM): these ciphersuites are only supported
+in TLS v1.2.
 
-=item B<CAMELLIA>
+=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
 
-cipher suites using Camellia.
+cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
+CAMELLIA.
 
 =item B<3DES>
 
@@ -251,6 +297,10 @@ cipher suites using MD5.
 
 cipher suites using SHA1.
 
+=item B<SHA256>, B<SHA384>
+
+ciphersuites using SHA256 or SHA384.
+
 =item B<aGOST> 
 
 cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
@@ -277,6 +327,21 @@ cipher suites, using HMAC based on GOST R 34.11-94.
 
 cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
 
+=item B<PSK>
+
+cipher suites using pre-shared keys (PSK).
+
+=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
+
+enables suite B mode operation using 128 (permitting 192 bit mode by peer)
+128 bit (not permitting 192 bit by peer) or 192 bit level of security
+respectively. If used these cipherstrings should appear first in the cipher
+list and anything after them is ignored. Setting Suite B mode has additional
+consequences required to comply with RFC6460. In particular the supported
+signature algorithms is reduced to support only ECDSA and SHA256 or SHA384,
+only the elliptic curves P-256 and P-384 can be used and only the two suite B
+compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and
+ECDHE-ECDSA-AES256-GCM-SHA384) are permissible.
 
 =back
 
@@ -300,12 +365,12 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
  SSL_RSA_WITH_DES_CBC_SHA                DES-CBC-SHA
  SSL_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA
 
- SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
- SSL_DH_DSS_WITH_DES_CBC_SHA             Not implemented.
- SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.
- SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
- SSL_DH_RSA_WITH_DES_CBC_SHA             Not implemented.
- SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.
+ SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA    EXP-DH-DSS-DES-CBC-SHA
+ SSL_DH_DSS_WITH_DES_CBC_SHA             DH-DSS-DES-CBC-SHA
+ SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA        DH-DSS-DES-CBC3-SHA
+ SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA    EXP-DH-RSA-DES-CBC-SHA
+ SSL_DH_RSA_WITH_DES_CBC_SHA             DH-RSA-DES-CBC-SHA
+ SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA        DH-RSA-DES-CBC3-SHA
  SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-DSS-DES-CBC-SHA
  SSL_DHE_DSS_WITH_DES_CBC_SHA            EDH-DSS-CBC-SHA
  SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA       EDH-DSS-DES-CBC3-SHA
@@ -360,10 +425,10 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
  TLS_RSA_WITH_AES_128_CBC_SHA            AES128-SHA
  TLS_RSA_WITH_AES_256_CBC_SHA            AES256-SHA
 
- TLS_DH_DSS_WITH_AES_128_CBC_SHA         Not implemented.
- TLS_DH_DSS_WITH_AES_256_CBC_SHA         Not implemented.
- TLS_DH_RSA_WITH_AES_128_CBC_SHA         Not implemented.
- TLS_DH_RSA_WITH_AES_256_CBC_SHA         Not implemented.
+ TLS_DH_DSS_WITH_AES_128_CBC_SHA         DH-DSS-AES128-SHA
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA         DH-DSS-AES256-SHA
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA         DH-RSA-AES128-SHA
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA         DH-RSA-AES256-SHA
 
  TLS_DHE_DSS_WITH_AES_128_CBC_SHA        DHE-DSS-AES128-SHA
  TLS_DHE_DSS_WITH_AES_256_CBC_SHA        DHE-DSS-AES256-SHA
@@ -378,10 +443,10 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
  TLS_RSA_WITH_CAMELLIA_128_CBC_SHA      CAMELLIA128-SHA
  TLS_RSA_WITH_CAMELLIA_256_CBC_SHA      CAMELLIA256-SHA
 
- TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA   Not implemented.
- TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA   Not implemented.
- TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA   Not implemented.
- TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA   Not implemented.
+ TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA   DH-DSS-CAMELLIA128-SHA
+ TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA   DH-DSS-CAMELLIA256-SHA
+ TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA   DH-RSA-CAMELLIA128-SHA
+ TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA   DH-RSA-CAMELLIA256-SHA
 
  TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA  DHE-DSS-CAMELLIA128-SHA
  TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA  DHE-DSS-CAMELLIA256-SHA
@@ -395,8 +460,8 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
 
  TLS_RSA_WITH_SEED_CBC_SHA              SEED-SHA
 
- TLS_DH_DSS_WITH_SEED_CBC_SHA           Not implemented.
- TLS_DH_RSA_WITH_SEED_CBC_SHA           Not implemented.
+ TLS_DH_DSS_WITH_SEED_CBC_SHA           DH-DSS-SEED-SHA
+ TLS_DH_RSA_WITH_SEED_CBC_SHA           DH-RSA-SEED-SHA
 
  TLS_DHE_DSS_WITH_SEED_CBC_SHA          DHE-DSS-SEED-SHA
  TLS_DHE_RSA_WITH_SEED_CBC_SHA          DHE-RSA-SEED-SHA
@@ -423,7 +488,100 @@ Note: these ciphers can also be used in SSL v3.
  TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA  EXP1024-DHE-DSS-RC4-SHA
  TLS_DHE_DSS_WITH_RC4_128_SHA            DHE-DSS-RC4-SHA
 
-=head2 SSL v2.0 cipher suites.
+=head2 Elliptic curve cipher suites.
+
+ TLS_ECDH_RSA_WITH_NULL_SHA              ECDH-RSA-NULL-SHA
+ TLS_ECDH_RSA_WITH_RC4_128_SHA           ECDH-RSA-RC4-SHA
+ TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA      ECDH-RSA-DES-CBC3-SHA
+ TLS_ECDH_RSA_WITH_AES_128_CBC_SHA       ECDH-RSA-AES128-SHA
+ TLS_ECDH_RSA_WITH_AES_256_CBC_SHA       ECDH-RSA-AES256-SHA
+
+ TLS_ECDH_ECDSA_WITH_NULL_SHA            ECDH-ECDSA-NULL-SHA
+ TLS_ECDH_ECDSA_WITH_RC4_128_SHA         ECDH-ECDSA-RC4-SHA
+ TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA    ECDH-ECDSA-DES-CBC3-SHA
+ TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA     ECDH-ECDSA-AES128-SHA
+ TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA     ECDH-ECDSA-AES256-SHA
+
+ TLS_ECDHE_RSA_WITH_NULL_SHA             ECDHE-RSA-NULL-SHA
+ TLS_ECDHE_RSA_WITH_RC4_128_SHA          ECDHE-RSA-RC4-SHA
+ TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA     ECDHE-RSA-DES-CBC3-SHA
+ TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA      ECDHE-RSA-AES128-SHA
+ TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA      ECDHE-RSA-AES256-SHA
+
+ TLS_ECDHE_ECDSA_WITH_NULL_SHA           ECDHE-ECDSA-NULL-SHA
+ TLS_ECDHE_ECDSA_WITH_RC4_128_SHA        ECDHE-ECDSA-RC4-SHA
+ TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA   ECDHE-ECDSA-DES-CBC3-SHA
+ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA    ECDHE-ECDSA-AES128-SHA
+ TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA    ECDHE-ECDSA-AES256-SHA
+
+ TLS_ECDH_anon_WITH_NULL_SHA             AECDH-NULL-SHA
+ TLS_ECDH_anon_WITH_RC4_128_SHA          AECDH-RC4-SHA
+ TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA     AECDH-DES-CBC3-SHA
+ TLS_ECDH_anon_WITH_AES_128_CBC_SHA      AECDH-AES128-SHA
+ TLS_ECDH_anon_WITH_AES_256_CBC_SHA      AECDH-AES256-SHA
+
+=head2 TLS v1.2 cipher suites
+
+ TLS_RSA_WITH_NULL_SHA256                  NULL-SHA256
+
+ TLS_RSA_WITH_AES_128_CBC_SHA256           AES128-SHA256
+ TLS_RSA_WITH_AES_256_CBC_SHA256           AES256-SHA256
+ TLS_RSA_WITH_AES_128_GCM_SHA256           AES128-GCM-SHA256
+ TLS_RSA_WITH_AES_256_GCM_SHA384           AES256-GCM-SHA384
+
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA256        DH-RSA-AES128-SHA256
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA256        DH-RSA-AES256-SHA256
+ TLS_DH_RSA_WITH_AES_128_GCM_SHA256        DH-RSA-AES128-GCM-SHA256
+ TLS_DH_RSA_WITH_AES_256_GCM_SHA384        DH-RSA-AES256-GCM-SHA384
+
+ TLS_DH_DSS_WITH_AES_128_CBC_SHA256        DH-DSS-AES128-SHA256
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA256        DH-DSS-AES256-SHA256
+ TLS_DH_DSS_WITH_AES_128_GCM_SHA256        DH-DSS-AES128-GCM-SHA256
+ TLS_DH_DSS_WITH_AES_256_GCM_SHA384        DH-DSS-AES256-GCM-SHA384
+
+ TLS_DHE_RSA_WITH_AES_128_CBC_SHA256       DHE-RSA-AES128-SHA256
+ TLS_DHE_RSA_WITH_AES_256_CBC_SHA256       DHE-RSA-AES256-SHA256
+ TLS_DHE_RSA_WITH_AES_128_GCM_SHA256       DHE-RSA-AES128-GCM-SHA256
+ TLS_DHE_RSA_WITH_AES_256_GCM_SHA384       DHE-RSA-AES256-GCM-SHA384
+
+ TLS_DHE_DSS_WITH_AES_128_CBC_SHA256       DHE-DSS-AES128-SHA256
+ TLS_DHE_DSS_WITH_AES_256_CBC_SHA256       DHE-DSS-AES256-SHA256
+ TLS_DHE_DSS_WITH_AES_128_GCM_SHA256       DHE-DSS-AES128-GCM-SHA256
+ TLS_DHE_DSS_WITH_AES_256_GCM_SHA384       DHE-DSS-AES256-GCM-SHA384
+
+ TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256      ECDH-RSA-AES128-SHA256
+ TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384      ECDH-RSA-AES256-SHA384
+ TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256      ECDH-RSA-AES128-GCM-SHA256
+ TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384      ECDH-RSA-AES256-GCM-SHA384
+
+ TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256    ECDH-ECDSA-AES128-SHA256
+ TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384    ECDH-ECDSA-AES256-SHA384
+ TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256    ECDH-ECDSA-AES128-GCM-SHA256
+ TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384    ECDH-ECDSA-AES256-GCM-SHA384
+
+ TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256     ECDHE-RSA-AES128-SHA256
+ TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384     ECDHE-RSA-AES256-SHA384
+ TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256     ECDHE-RSA-AES128-GCM-SHA256
+ TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384     ECDHE-RSA-AES256-GCM-SHA384
+
+ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256   ECDHE-ECDSA-AES128-SHA256
+ TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384   ECDHE-ECDSA-AES256-SHA384
+ TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256   ECDHE-ECDSA-AES128-GCM-SHA256
+ TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384   ECDHE-ECDSA-AES256-GCM-SHA384
+
+ TLS_DH_anon_WITH_AES_128_CBC_SHA256       ADH-AES128-SHA256
+ TLS_DH_anon_WITH_AES_256_CBC_SHA256       ADH-AES256-SHA256
+ TLS_DH_anon_WITH_AES_128_GCM_SHA256       ADH-AES128-GCM-SHA256
+ TLS_DH_anon_WITH_AES_256_GCM_SHA384       ADH-AES256-GCM-SHA384
+
+=head2 Pre shared keying (PSK) cipheruites
+
+ TLS_PSK_WITH_RC4_128_SHA                  PSK-RC4-SHA
+ TLS_PSK_WITH_3DES_EDE_CBC_SHA             PSK-3DES-EDE-CBC-SHA
+ TLS_PSK_WITH_AES_128_CBC_SHA              PSK-AES128-CBC-SHA
+ TLS_PSK_WITH_AES_256_CBC_SHA              PSK-AES256-CBC-SHA
+
+=head2 Deprecated SSL v2.0 cipher suites.
 
  SSL_CK_RC4_128_WITH_MD5                 RC4-MD5
  SSL_CK_RC4_128_EXPORT40_WITH_MD5        EXP-RC4-MD5
@@ -435,9 +593,6 @@ Note: these ciphers can also be used in SSL v3.
 
 =head1 NOTES
 
-The non-ephemeral DH modes are currently unimplemented in OpenSSL
-because there is no support for DH certificates.
-
 Some compiled versions of OpenSSL may not include all the ciphers
 listed here because some ciphers were excluded at compile time.
 
@@ -452,6 +607,11 @@ strength:
 
  openssl ciphers -v 'ALL:!ADH:@STRENGTH'
 
+Include all ciphers except ones with no encryption (eNULL) or no
+authentication (aNULL):
+
+ openssl ciphers -v 'ALL:!aNULL'
+
 Include only 3DES ciphers and then place RSA ciphers last:
 
  openssl ciphers -v '3DES:+RSA'