From 5f66f907cfc57b89110c08e50c7aab228e090911 Mon Sep 17 00:00:00 2001 From: Steffan Karger Date: Tue, 5 May 2015 17:47:37 +0200 Subject: 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 Acked-by: Arne Schwabe 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 --- doc/openvpn.8 | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) (limited to 'doc') 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 -- cgit v1.1