Document tls-crypt security considerations in man page

The tls-crypt commit message contained an elaborate discussion on the
function's security properties.  This commit adds the gist of that
discussion, "rotate keys periodically" to the man page.

(The 'real' solution will follow later: add support for per-client
tls-crypt keys.  That will make tls-crypt useful for VPN providers too.)

Note to non-crypto-geek reviewers: please verify that this text is clear
enough to explain you when you need to replace tls-crypt keys.

Note to crypto-geek reviewers: please check the numbers - see the
--tls-crypt commit message (c6e24fa3) for details.

[DS: Fixed a few typos on-the-fly during commit]

Signed-off-by: Steffan Karger <steffan.karger@fox-it.com>
Acked-by: Selva Nair <selva.nair@gmail.com>
Message-Id: <1494355368-20238-1-git-send-email-steffan.karger@fox-it.com>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg14610.html
Signed-off-by: David Sommerseth <davids@openvpn.net>

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index c3248fde1df7e713b36d8e5adc2f4af6850e4bca..ce9a9c3ccb01f01852a45b91f8d174db0fabdcb5 100644 (file)
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -5090,6 +5090,29 @@ In contrast to
 .B \-\-tls\-crypt
 does *not* require the user to set
 .B \-\-key\-direction\fR.
+
+.B Security Considerations
+
+All peers use the same
+.B \-\-tls-crypt
+pre-shared group key to authenticate and encrypt control channel messages.  To
+ensure that IV collisions remain unlikely, this key should not be used to
+encrypt more than 2^48 client-to-server or 2^48 server-to-client control
+channel messages.  A typical initial negotiation is about 10 packets in each
+direction.  Assuming both initial negotiation and renegotiations are at most
+2^16 (65536) packets (to be conservative), and (re)negotiations happen each
+minute for each user (24/7), this limits the tls\-crypt key lifetime to 8171
+years divided by the number of users.  So a setup with 1000 users should rotate
+the key at least once each eight years.  (And a setup with 8000 users each
+year.)
+
+If IV collisions were to occur, this could result in the security of
+.B \-\-tls\-crypt
+degrading to the same security as using
+.B \-\-tls\-auth\fR.
+That is, the control channel still benefits from the extra protection against
+active man-in-the-middle-attacks and DoS attacks, but may no longer offer
+extra privacy and post-quantum security on top of what TLS itself offers.
 .\"*********************************************************
 .TP
 .B \-\-askpass [file]