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

4 files changed, 35 insertions, 11 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 0acffdf..c7b21cf 100644
--- 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 224df9d..eb09983 100644
--- 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 fd382fb..be33caa 100644
--- 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 189bf71..30c7395 100644
--- 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