1. openvpn
  2. Commit bf42466dd00c56b8b61f5cd0c7f451882e5bc861
Browse code

Document different behaviour of dynamic cipher negotiation

This adds a section in the man page that details the various behaviour
of older client/servers when using OpenVPN 2.5.

Patch V2: Include grammar/spelling fixes from
Richard Bonhomme <tincanteksup@gmail.com>

Signed-off-by: Arne Schwabe <arne@rfc2549.org>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200810090032.4220-1-arne@rfc2549.org>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg20660.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>

Arne Schwabe authored on 2020/08/10 18:00:32
Showing 3 changed files
Changes.rst
History View file @ bf42466
... ... 
@@ -29,6 +29,29 @@ Improved Data channel cipher negotiation
29 29 
     ``data-ciphers ChaCha20-Poly1305:AES-256-GCM`` on the server that
30 30 
     prefers ChaCha20-Poly1305 but uses it only if the client supports it.
31 31
32 
+    See the data channel negotiation section in the manual for more details.
33 
+
34 
+Removal of BF-CBC support in default configuration:
35 
+    By default OpenVPN 2.5 will only accept AES-256-GCM and AES-128-GCM as
36 
+    data ciphers. OpenVPN 2.4 allows AES-256-GCM,AES-128-GCM and BF-CBC when
37 
+    no --cipher and --ncp-cipher options are present. Accepting BF-CBC can be
38 
+    enabled by adding
39 
+
40 
+        data-ciphers AES-256-GCM:AES-128-GCM:BF-CBC
41 
+
42 
+    and when you need to support very old peers also
43 
+
44 
+        data-ciphers-fallback BF-CBC
45 
+
46 
+    To offer backwards compatibility with older configs an *explicit*
47 
+
48 
+        cipher BF-CBC
49 
+
50 
+    in the configuration will be automatically translated into adding BF-CBC
51 
+    to the data-ciphers option and setting data-ciphers-fallback to BF-CBC
52 
+    (as in the example commands above). We strongly recommend to switching
53 
+    away from BF-CBC to a more secure cipher.
54 
+
32 55 
 Asynchronous (deferred) authentication support for auth-pam plugin.
33 56 
     See src/plugins/auth-pam/README.auth-pam for details.
34 57
doc/man-sections/cipher-negotiation.rst
History View file @ bf42466
35 58 
new file mode 100644
... ... 
@@ -0,0 +1,92 @@
0 
+Data channel cipher negotiation
1 
+===============================
2 
+
3 
+OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
4 
+is used to encrypt data packets. This section describes the mechanism in more detail and the
5 
+different backwards compatibility mechanism with older server and clients.
6 
+
7 
+OpenVPN 2.5 and higher behaviour
8 
+--------------------------------
9 
+When both client and server are at least running OpenVPN 2.5, that the order of
10 
+the ciphers of the server's ``--data-ciphers`` is used to pick the the data cipher.
11 
+That means that the first cipher in that list that is also in the client's
12 
+``--data-ciphers`` list is chosen. If no common cipher is found the client is rejected
13 
+with a AUTH_FAILED message (as seen in client log):
14 
+
15 
+    AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)
16 
+
17 
+OpenVPN 2.5 will only allow the ciphers specified in ``--data-ciphers``. To ensure
18 
+backwards compatibility also if a cipher is specified using the ``--cipher`` option
19 
+it is automatically added to this list. If both options are unset the default is
20 
+:code:`AES-256-GCM:AES-128-GCM`.
21 
+
22 
+OpenVPN 2.4 clients
23 
+-------------------
24 
+The negotiation support in OpenVPN 2.4 was a first implementation and still had some
25 
+quirks. Its main goal was "upgrade to AES-256-GCM when possible".
26 
+An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
27 
+mode and does not have ``--ncp-disable`` will always announce support for
28 
+`AES-256-GCM` and `AES-128-GCM` even if the ``--ncp-ciphers`` option does not include
29 
+those two ciphers. It is therefore recommended to add `AES-256-GCM` and `AES-128-GCM`
30 
+to the ``--ncp-ciphers`` options to workaround this bug.
31 
+
32 
+
33 
+OpenVPN 3 clients
34 
+-----------------
35 
+Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
36 
+do not have a configurable ``--ncp-ciphers`` or ``--data-cipher`` option. Instead
37 
+these clients will announce support for all their supported AEAD ciphers
38 
+(`AES-256-GCM`, `AES-128-GCM` and in newer versions also `Chacha20-Poly1305`).
39 
+
40 
+To support OpenVPN 3.x based clients at least one of these ciphers needs to be
41 
+included in the server's ``--data-ciphers`` option.
42 
+
43 
+
44 
+OpenVPN 2.3 clients and older (and clients with ``--ncp-disable``)
45 
+------------------------------------------------------------------
46 
+When a client without cipher negotiation support connects to a server the
47 
+cipher specified with the ``--cipher`` option in the client configuration
48 
+must be included in the ``--data-ciphers`` option of the server to allow
49 
+the client to connect. Otherwise the client will be sent the ``AUTH_FAILED``
50 
+message that indicates no shared cipher.
51 
+
52 
+If the client has been configured with the ``--enable-small``
53 
+:code:``./configure`` argument, using ``data-ciphers-fallback cipher``
54 
+in the server config file with the explicit cipher used by the client
55 
+is necessary.
56 
+
57 
+OpenVPN 2.4 server
58 
+------------------
59 
+When a client indicates support for `AES-128-GCM` and `AES-256-GCM`
60 
+(with ``IV_NCP=2``) an OpenVPN 2.4 server will send the first
61 
+cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
62 
+the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
63 
+as possible and have compatibility to a setup that depends on this quirk,
64 
+adding  `AES-128-GCM` and `AES-256-GCM` to the client's ``--data-ciphers``
65 
+option is required. OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if
66 
+those ciphers are present.
67 
+
68 
+OpenVPN 2.3 and older servers (and servers with ``-ncp-disable``)
69 
+-----------------------------------------------------------------
70 
+The cipher used by the server must be included in ``--data-ciphers`` to
71 
+allow the client connecting to a server without cipher negotiation
72 
+support.
73 
+(For compatibility OpenVPN 2.5 will also accept the cipher set with
74 
+``--cipher``)
75 
+
76 
+If the server has been configured with the ``--enable-small``
77 
+:code:``./configure` argument, adding ``data-ciphers-fallback cipher``
78 
+to the client config with the explicit cipher used by the server
79 
+is necessary.
80 
+
81 
+Blowfish in CBC mode (BF-CBC) deprecation
82 
+------------------------------------------
83 
+The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN 2.4 and older
84 
+version. The default was never changed to ensure backwards compatibility.
85 
+In OpenVPN 2.5 this behaviour has now been changed so that if the ``--cipher``
86 
+is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more
87 
+and needs to explicitly added as ``--cipher BFC-CBC`` or added to
88 
+``-data-ciphers``.
89 
+
90 
+We strongly recommend to switching away from BF-CBC to a
91 
+more secure cipher as soon as possible instead.
doc/openvpn.8.rst
History View file @ bf42466
... ... 
@@ -75,6 +75,7 @@ placed in a configuration file.
75 75 
 .. include:: man-sections/client-options.rst
76 76 
 .. include:: man-sections/server-options.rst
77 77 
 .. include:: man-sections/encryption-options.rst
78 
+.. include:: man-sections/cipher-negotiation.rst
78 79 
 .. include:: man-sections/network-config.rst
79 80 
 .. include:: man-sections/script-options.rst
80 81 
 .. include:: man-sections/management-options.rst