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>

4 files changed, 35 insertions, 14 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index b09f7d7..d2f47b3 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -4524,18 +4524,29 @@ separately negotiated over the existing secure TLS channel.  Here,
 determines the derivation of the tunnel session keys.
 .\"*********************************************************
 .TP
-.B \-\-tls-cipher l
+.B \-\-tls\-cipher l
 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.
+.B \-\-show\-tls
+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.
@@ -5091,11 +5102,16 @@ Show all message digest algorithms to use with the
 option.
 .\"*********************************************************
 .TP
-.B \-\-show-tls
+.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 6222bd6..bb1c1c2 100644
--- a/src/openvpn/ssl_common.h
+++ b/src/openvpn/ssl_common.h
@@ -511,4 +511,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 d9abc6e..df9fa87 100644
--- a/src/openvpn/ssl_openssl.c
+++ b/src/openvpn/ssl_openssl.c
@@ -1395,7 +1395,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 913585d..cb282d9 100644
--- a/src/openvpn/ssl_polarssl.c
+++ b/src/openvpn/ssl_polarssl.c
@@ -1099,7 +1099,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);
 
   tls_ctx_free(&tls_ctx);
 }