Improve --tls-cipher and --show-tls man page description

As reported in trac tickets #304, #358 and #359 (and possibly more), the
usage and interpretation of --tls-cipher (and --show-tls) is tricky.  This
patch extends the man page to explain those a bit better and point out
that --tls-cipher is an expert feature (i.e. easy to get wrong).  Also add
a notice to the --show-tls output, referring to the man page explanation.

Signed-off-by: Steffan Karger <steffan@karger.me>
Acked-by: Arne Schwabe <arne@rfc2549.org>
Message-Id: <1430840857-6123-1-git-send-email-steffan@karger.me>
URL: http://article.gmane.org/gmane.network.openvpn.devel/9651
Signed-off-by: Gert Doering <gert@greenie.muc.de>
(cherry picked from commit 5f66f907cfc57b89110c08e50c7aab228e090911)

Conflicts:
	doc/openvpn.8
	src/openvpn/ssl_polarssl.c

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 0acffdf9824ec4ec65f0ea077d7c4f924f933db6..c7b21cf2d36c200fd076562be7ee800266cb4e4e 100644 (file)
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -4479,14 +4479,28 @@ determines the derivation of the tunnel session keys.
 A list
 .B l
 of allowable TLS ciphers delimited by a colon (":").
-If you require a high level of security,
-you may want to set this parameter manually, to prevent a
-version rollback attack where a man-in-the-middle attacker tries
-to force two peers to negotiate to the lowest level
-of security they both support.
+
+This setting can be used to ensure that certain cipher suites are used (or
+not used) for the TLS connection.  OpenVPN uses TLS to secure the control
+channel, over which the keys that are used to protect the actual VPN traffic
+are exchanged.
+
+The supplied list of ciphers is (after potential OpenSSL/IANA name translation)
+simply supplied to the crypto library.  Please see the OpenSSL and/or PolarSSL
+documentation for details on the cipher list interpretation.
+
 Use
 .B \-\-show\-tls
-to see a list of supported TLS ciphers.
+to see a list of TLS ciphers supported by your crypto library.
+
+Warning!
+.B \-\-tls\-cipher
+is an expert feature, which - if used correcly - can improve the security of
+your VPN connection.  But it is also easy to unwittingly use it to carefully
+align a gun with your foot, or just break your connection.  Use with care!
+
+The default for --tls-cipher is to use PolarSSL's default cipher list
+when using PolarSSL or "DEFAULT:!EXP:!PSK:!SRP:!kRSA" when using OpenSSL.
 .\"*********************************************************
 .TP
 .B \-\-tls\-timeout n
@@ -5057,9 +5071,14 @@ option.
 .TP
 .B \-\-show\-tls
 (Standalone)
-Show all TLS ciphers (TLS used only as a control channel).  The TLS
-ciphers will be sorted from highest preference (most secure) to
-lowest.
+Show all TLS ciphers supported by the crypto library.  OpenVPN uses TLS to
+secure the control channel, over which the keys that are used to protect the
+actual VPN traffic are exchanged.  The TLS ciphers will be sorted from highest
+preference (most secure) to lowest.
+
+Be aware that whether a cipher suite in this list can actually work depends on
+the specific setup of both peers (e.g. both peers must support the cipher, and
+an ECDSA cipher suite will not work if you are using an RSA certificate, etc.).
 .\"*********************************************************
 .TP
 .B \-\-show\-engines

diff --git a/src/openvpn/ssl_common.h b/src/openvpn/ssl_common.h
index 224df9d29e6516bcd94ccb17e9facee424eea30d..eb09983c3841e89158f97948fa53bb9e6ec590cf 100644 (file)
--- a/src/openvpn/ssl_common.h
+++ b/src/openvpn/ssl_common.h
@@ -504,4 +504,9 @@ struct tls_multi
 };
 
 
+#define SHOW_TLS_CIPHER_LIST_WARNING \
+  "Be aware that that whether a cipher suite in this list can actually work\n" \
+  "depends on the specific setup of both peers. See the man page entries of\n" \
+  "--tls-cipher and --show-tls for more details.\n\n"
+
 #endif /* SSL_COMMON_H_ */

diff --git a/src/openvpn/ssl_openssl.c b/src/openvpn/ssl_openssl.c
index fd382fb91a2f6c54d23b4959981dce4ca2c034c0..be33caa23c38188d51a0c5f3245d5e5f29b6df5b 100644 (file)
--- a/src/openvpn/ssl_openssl.c
+++ b/src/openvpn/ssl_openssl.c
@@ -1340,7 +1340,7 @@ show_available_tls_ciphers (const char *cipher_list)
       }
 
     }
-  printf ("\n");
+  printf ("\n" SHOW_TLS_CIPHER_LIST_WARNING);
 
   SSL_free (ssl);
   SSL_CTX_free (tls_ctx.ctx);

diff --git a/src/openvpn/ssl_polarssl.c b/src/openvpn/ssl_polarssl.c
index 189bf7158eeb0b96cecd4c14f3ebb9b4403c537e..30c73957d5c4fdd72092d49e0dd1e4092aabf730 100644 (file)
--- a/src/openvpn/ssl_polarssl.c
+++ b/src/openvpn/ssl_polarssl.c
@@ -1095,7 +1095,7 @@ show_available_tls_ciphers (const char *cipher_list)
       printf ("%s\n", ssl_get_ciphersuite_name(*ciphers));
       ciphers++;
     }
-  printf ("\n");
+  printf ("\n" SHOW_TLS_CIPHER_LIST_WARNING);
 }
 
 void