Minor patch: check only match @STRENGTH and remove eNULL
authorDr. Stephen Henson <steve@openssl.org>
Sat, 22 Jan 2000 23:34:44 +0000 (23:34 +0000)
committerDr. Stephen Henson <steve@openssl.org>
Sat, 22 Jan 2000 23:34:44 +0000 (23:34 +0000)
comment.

Add documentation for the ciphers command including a full
description of cipher lists.

doc/apps/ciphers.pod [new file with mode: 0644]
ssl/ssl_ciph.c

diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
new file mode 100644 (file)
index 0000000..c961d2d
--- /dev/null
@@ -0,0 +1,339 @@
+=pod
+
+=head1 NAME
+
+ciphers - SSL cipher display and cipher list tool.
+
+=head1 SYNOPSIS
+
+B<openssl> B<ciphers>
+[B<-v>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<cipherlist> command converts OpenSSL cipher lists into ordered
+SSL cipher preference lists. It can be used as a test tool to determine
+the appropriate cipherlist.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-v>
+
+verbose option. List ciphers with a complete decsription of the authentication,
+key exchange, encryption and mac algorithms used along with any key size
+restrictions and whether the algorithm is classed as an "export" cipher.
+
+=item B<-ssl3>
+
+only include SSL v3 ciphers.
+
+=item B<-ssl2>
+
+only include SSL v2 ciphers.
+
+=item B<-tls1>
+
+only include TLS v1 ciphers.
+
+=item B<-h>, B<-?>
+
+print a brief usage message.
+
+=item B<cipherlist>
+
+a cipher list to convert to a cipher preference list. If it is not included
+then the default cipher list will be used. The format is described below.
+
+=head1 CIPHER LIST FORMAT
+
+The cipher list consists of one or more I<cipher strings> separated by colons.
+Commas or spaces are also acceptable separators but colons are normally used.
+
+The actual cipher string can take several different forms.
+
+It can consist of a single cipher suite such as B<RC4-SHA>.
+
+It can represent a list of cipher suites containing a certain algorithm, or
+cipher suites of a certain type. For example B<SHA1> represents all ciphers
+suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
+algorithms.
+
+Lists of cipher suites can be combined in a single cipher string using the
+B<+> character. This is used as a logical B<and> operation. For example
+B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
+algorithms.
+
+Each cipher string can be optionally preceded by the characters B<!>,
+B<-> or B<+>.
+
+If B<!> is used then the ciphers are permanently deleted from the list.
+The ciphers deleted can never reappear in the list even if they are
+explicitly stated.
+
+If B<-> is used then the ciphers are deleted from the list, but some or
+all of the ciphers can be added again by later options.
+
+If B<+> is used then the ciphers are moved to the end of the list. This
+option doesn't add any new ciphers it just moves matching existing ones.
+
+If none of these characters is present then the string is just interpreted
+as a list of ciphers to be appended to the current preference list. If the
+list includes any ciphers already present they will be ignored: that is they
+will not moved to the end of the list.
+
+Additionally the cipher string B<@STRENGTH> can be used at any point to sort
+the current cipher list in order of encryption algorithm key length.
+
+=head1 CIPHER STRINGS
+
+The following is a list of all permitted cipher strings and their meanings.
+
+=over 4
+
+=item B<DEFAULT>
+
+the default cipher list. This is determined at compile time and is normally
+B<TBA>. This must be the first cipher string specified.
+
+=item B<ALL>
+
+all ciphers suites except the B<eNULL> ciphers which must be explicitly enabled.
+
+=item B<HIGH>
+
+"high" encryption cipher suites. This currently means those with key lengths larger
+than 128 bits.
+
+=item B<MEDIUM>
+
+"medium" encryption cipher suites, currently those using 128 bit encryption.
+
+=item B<LOW>
+
+"low" encryption cipher suites, currently those using 64 or 56 bit encryption algorithms
+but excluding export cipher suites.
+
+=item B<EXP>, B<EXPORT>
+
+export encryption algorithms. Including 40 and 56 bits algorithms.
+
+=item B<EXPORT40>
+
+40 bit export encryption algorithms
+
+=item B<EXPORT56>
+
+56 bit export encryption algorithms.
+
+=item B<eNULL>, B<NULL>
+
+the "NULL" ciphers that is those offering no encryption. Because these offer no
+encryption at all and are a security risk they are disabled unless explicitly
+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 there use is normally discouraged.
+
+=item B<kRSA>, B<RSA>
+
+cipher suites using RSA key exchange.
+
+=item B<kEDH>
+
+cipher suites using ephemeral DH key agreement.
+
+=item B<kDHr>, B<kDHd>
+
+cipher suites using DH key agreement and DH certificates signed by CAs with RSA
+and DSS keys respectively. Not implemented.
+
+=item B<aRSA>
+
+cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
+
+=item B<aDSS>, B<DSS>
+
+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.
+
+=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>
+
+cipher suites using DH, including anonymous DH.
+
+=item B<ADH>
+
+anoymous DH cipher suites.
+
+=item B<3DES>
+
+cipher suites using triple DES.
+
+=item B<DES>
+
+cipher suites using DES (not triple DES).
+
+=item B<RC4>
+
+cipher suites using RC4.
+
+=item B<RC2>
+
+cipher suites using RC2.
+
+=item B<IDEA>
+
+cipher suites using IDEA.
+
+=item B<MD5>
+
+cipher suites using MD5.
+
+=item B<SHA1>, B<SHA>
+
+cipher suites using SHA1.
+
+=back
+
+=head1 CIPHER SUITE NAMES
+
+The following lists give the SSL or TLS cipher suites names from the
+relevant specification and their OpenSSL equivalents.
+
+=head2 SSL v3.0 cipher suites.
+
+ SSL_RSA_WITH_NULL_MD5                   NULL-MD5
+ SSL_RSA_WITH_NULL_SHA                   NULL-SHA
+ SSL_RSA_EXPORT_WITH_RC4_40_MD5          EXP-RC4-MD5
+ SSL_RSA_WITH_RC4_128_MD5                RC4-MD5
+ SSL_RSA_WITH_RC4_128_SHA                RC4-SHA
+ SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5      EXP-RC2-CBC-MD5
+ SSL_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA
+ SSL_RSA_EXPORT_WITH_DES40_CBC_SHA       EXP-DES-CBC-SHA
+ 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_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
+ SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-RSA-DES-CBC-SHA
+ SSL_DHE_RSA_WITH_DES_CBC_SHA            EDH-RSA-DES-CBC-SHA
+ SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA       EDH-RSA-DES-CBC3-SHA
+
+ SSL_DH_anon_EXPORT_WITH_RC4_40_MD5      EXP-ADH-RC4-MD5
+ SSL_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5
+ SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA   EXP-ADH-DES-CBC-SHA
+ SSL_DH_anon_WITH_DES_CBC_SHA            ADH-DES-CBC-SHA
+ SSL_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA
+
+ SSL_FORTEZZA_KEA_WITH_NULL_SHA          Not implemented.
+ SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA  Not implemented.
+ SSL_FORTEZZA_KEA_WITH_RC4_128_SHA       Not implemented.
+
+=head2 TLS v1.0 cipher suites.
+
+ TLS_RSA_WITH_NULL_MD5                   NULL-MD5
+ TLS_RSA_WITH_NULL_SHA                   NULL-SHA
+ TLS_RSA_EXPORT_WITH_RC4_40_MD5          EXP-RC4-MD5
+ TLS_RSA_WITH_RC4_128_MD5                RC4-MD5
+ TLS_RSA_WITH_RC4_128_SHA                RC4-SHA
+ TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5      EXP-RC2-CBC-MD5
+ TLS_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA
+ TLS_RSA_EXPORT_WITH_DES40_CBC_SHA       EXP-DES-CBC-SHA
+ TLS_RSA_WITH_DES_CBC_SHA                DES-CBC-SHA
+ TLS_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA
+
+ TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
+ TLS_DH_DSS_WITH_DES_CBC_SHA             Not implemented.
+ TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.
+ TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA    Not implemented.
+ TLS_DH_RSA_WITH_DES_CBC_SHA             Not implemented.
+ TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.
+ TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-DSS-DES-CBC-SHA
+ TLS_DHE_DSS_WITH_DES_CBC_SHA            EDH-DSS-CBC-SHA
+ TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA       EDH-DSS-DES-CBC3-SHA
+ TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA   EXP-EDH-RSA-DES-CBC-SHA
+ TLS_DHE_RSA_WITH_DES_CBC_SHA            EDH-RSA-DES-CBC-SHA
+ TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA       EDH-RSA-DES-CBC3-SHA
+
+ TLS_DH_anon_EXPORT_WITH_RC4_40_MD5      EXP-ADH-RC4-MD5
+ TLS_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5
+ TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA   EXP-ADH-DES-CBC-SHA
+ TLS_DH_anon_WITH_DES_CBC_SHA            ADH-DES-CBC-SHA
+ TLS_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA
+
+=head2 Additional Export 1024 and other cipher suites
+
+Note: these ciphers can also be used in SSL v3.
+
+ TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA     EXP1024-DES-CBC-SHA
+ TLS_RSA_EXPORT1024_WITH_RC4_56_SHA      EXP1024-RC4-SHA
+ TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA
+ 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.
+
+ SSL_CK_RC4_128_WITH_MD5                 RC4-MD5
+ SSL_CK_RC4_128_EXPORT40_WITH_MD5        EXP-RC4-MD5
+ SSL_CK_RC2_128_CBC_WITH_MD5             RC2-MD5
+ SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5    EXP-RC2-MD5
+ SSL_CK_IDEA_128_CBC_WITH_MD5            IDEA-CBC-MD5
+ SSL_CK_DES_64_CBC_WITH_MD5              DES-CBC-MD5
+ SSL_CK_DES_192_EDE3_CBC_WITH_MD5        DES-CBC3-MD5
+
+=head1 NOTES
+
+The non ephemeral DH modes are currently unimplimented 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.
+
+=head1 EXAMPLES
+
+Verbose listing of all OpenSSL ciphers including NULL ciphers:
+
+ openssl ciphers -v 'ALL:eNULL'
+
+Include all ciphers except NULL and anonymous DH then sort by
+strength:
+
+ openssl ciphers -v 'ALL:!ADH:@STRENGTH'
+
+Include only 3DES ciphers and then place RSA ciphers last:
+
+ openssl ciphers -v '3DES:+RSA'
+
+=head1 SEE ALSO
+
+s_client(1), s_server(1), ssl(3)
+
+=cut
index c86f41e..12b02a8 100644 (file)
@@ -536,19 +536,11 @@ static int ssl_cipher_strength_sort(CIPHER_ORDER *list, CIPHER_ORDER **head_p,
                        number_uses[curr->cipher->strength_bits]++;
                curr = curr->next;
                }
-#if 0
        /*
         * Go through the list of used strength_bits values in descending
-        * order, omit strength_bits "0".
+        * order.
         */
-       for (i = max_strength_bits; i > 0; i--)
-       /* Do we really want this? If so "ALL:eNULL:@STRENGTH" puts eNULL
-         * ciphers first???
-         */
-
-#else
        for (i = max_strength_bits; i >= 0; i--)
-#endif
                if (number_uses[i] > 0)
                        ssl_cipher_apply_rule(0, 0, 0, 0, CIPHER_ORD, i,
                                        list, head_p, tail_p);
@@ -679,7 +671,8 @@ static int ssl_cipher_process_rulestr(const char *rule_str,
                        if (rule == CIPHER_SPECIAL)
                                {       /* special command */
                                ok = 0;
-                               if (!strncmp(buf, "STRENGTH", buflen))
+                               if ((buflen == 8) &&
+                                       !strncmp(buf, "STRENGTH", 8))
                                        ok = ssl_cipher_strength_sort(list,
                                                        head_p, tail_p);
                                else
@@ -689,7 +682,7 @@ static int ssl_cipher_process_rulestr(const char *rule_str,
                                        retval = 0;
                                /*
                                 * We do not support any "multi" options
-                                * together with "@", so through away the
+                                * together with "@", so throw away the
                                 * rest of the command, if any left, until
                                 * end or ':' is found.
                                 */