This adds a section in the man page that details the various behaviour
of older client/servers when using OpenVPN 2.5.
Signed-off-by: Arne Schwabe <a...@rfc2549.org>
---
Changes.rst | 23 +++++++
doc/man-sections/cipher-negotiation.rst | 87 +++++++++++++++++++++++++
doc/openvpn.8.rst | 1 +
3 files changed, 111 insertions(+)
create mode 100644 doc/man-sections/cipher-negotiation.rst
diff --git a/Changes.rst b/Changes.rst
index 37792342..2cfd2ee2 100644
--- a/Changes.rst
+++ b/Changes.rst
@@ -29,6 +29,29 @@ Improved Data channel cipher negotiation
``data-ciphers ChaCha20-Poly1305:AES-256-GCM`` on the server that
prefers ChaCha20-Poly1305 but uses it only if the client supports it.
+ See the data channel negotiation section in the manual for more details.
+
+Removal of BF-CBC support in default configuration:
+ By default OpenVPN 2.5 will only accept AES-256-GCM and AES-128-GCM as
+ data ciphers. OpenVPN 2.4 allows AES-256-GCM,AES-128-GCM and BF-CBC when
+ no --cipher and --ncp-ption were present. Accepting BF-CBC can be
+ enabled by adding
+
+ data-ciphers AES-256-GCM:AES-128-GCM:BF-CBC
+
+ and when you need to support very old peers also
+
+ data-ciphers-fallback BF-CBC
+
+ to offer backwards compatiblity with older config an *explicit*
+
+ cipher BF-CBC
+
+ in the configuration will be automatically translated in adding BF-CBC
+ to the data-ciphers option and setting data-ciphers-fallback to BF-CBC
+ commands above. We strongly recommend to switching away from BF-CBC to a
+ more secure cipher.
+
Asynchronous (deferred) authentication support for auth-pam plugin.
See src/plugins/auth-pam/README.auth-pam for details.
diff --git a/doc/man-sections/cipher-negotiation.rst
b/doc/man-sections/cipher-negotiation.rst
new file mode 100644
index 00000000..98ce1fec
--- /dev/null
+++ b/doc/man-sections/cipher-negotiation.rst
@@ -0,0 +1,87 @@
+Data channel cipher negotiation
+===============================
+
+OpenVPN 2.4 and higher have the capability to dynamically negotiate the data
cipher that
+is used to encrypt data packets. This section describes the mechanism in more
detail and the
+different backwards compatibility mechanism with older server and clients.
+
+OpenVPN 2.5 and higher behaviour
+--------------------------------
+When both client and server are at least running OpenVPN 2.5, that the order of
+the ciphers of the server's ``--data-ciphers`` is used to pick the the data
cipher.
+That means that the first cipher in that last that is also in the client's
+``--data-ciphers`` list is chosen. If no common cipher is found the client is
rejected
+with a AUTH_FAILED message (as seen in client log):
+
+ AUTH: Received control message: AUTH_FAILED,Data channel cipher
negotiation failed (no shared cipher)
+
+OpenVPN 2.5 will only allow the ciphers specified in ``--data-ciphers``. To
ensure
+backwards compatibility also if a cipher is specified using the ``--cipher``
option
+it is automatically added to this list. If both options are unset the default
is
+:code:`AES-256-GCM:AES-128-GCM`.
+
+OpenVPN 2.4 clients
+-------------------
+The negotiation support in OpenVPN 2.4 was a first implementation and still
had some
+quirks. Its main goal was "upgrade to AES-256-GCM when possible".
+An OpenVPN 2.4 client that is build against a crypto library that supports AES
in GCM
+mode and does not have ``--ncp-disable`` will always announce support for
+`AES-256-GCM` and `AES-128-GCM` even if the ``--ncp-ciphers`` option does not
inlcude
+those two ciphers. It is therefore recommended to add `AES-256-GCM` and
`AES-128-GCM`
+to the ``--ncp-ciphers`` options to workaround this bug.
+
+
+OpenVPN 3 clients
+-----------------
+Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
+do not have a configurable ``--ncp-ciphers`` or ``--data-cipher`` option.
Instead
+these clients will announce support for all their supported AEAD ciphers
+(`AES-256-GCM`, `AES-128-GCM` and in newer versions also `Chacha20-Poly1305`).
+
+To support OpenVPN 3.x based clients at least one of these ciphers needs to be
+included in the ``--data-ciphers`` option.
+
+
+OpenVPN 2.3 clients and older (and clients with ``--ncp-disable``)
+------------------------------------------------------------------
+When a client without cipher negotiation support connects to a server the
+cipher specified with the ``--cipher`` option in the client configuration
+must be included in the ``--data-ciphers`` option of the server to allow
+the client to connect. Otherwise the client will be sent the ``AUTH_FAILED``
+message that indicates no shared cipher.
+
+If the client has been configured with the ``--enable-small``
+:code:``./configure`` argument, using ``data-ciphers-fallback cipher``
+with the explicit cipher used by the client is necessary.
+
+OpenVPN 2.4 server
+------------------
+When a client indicates support for `AES-128-GCM` and `AES-256-GCM`
+(with ``IV_NCP=2``) an OpenVPN 2.4 server will), send the first
+cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
+cipher is. To ensure compatibility with behaviour as a client, adding
+`AES-128-GCM` and `AES-256-GCM` to the ``--data-ciphers`` is required
+since OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if those
+ciphers are present.
+
+OpenVPN 2.3 and older servers (and servers with ``-ncp-disable``)
+-----------------------------------------------------------------
+The cipher used by the server must be included in ``--data-ciphers`` to
+allow the client connecting to a server without cipher negotiation
+suppport.
+(As compatibility OpenVPN 2.5 will also accept the cipher set with
+``--cipher``)
+
+If the server has been configured with the ``--enable-small``
+:code:``./configure` argument, using ``data-ciphers-fallback cipher``
+with the explicit cipher used by the server is necessary.
+
+Blowfish in CBC mode (BFB-CBC) deprecation
+------------------------------------------
+The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN in
+OpenVPN 2.4 and older version. The default was never changed
+to ensure backwards compatibility. In OpenVPN 2.5 this behaviour
+has now been changed that if the ``--cipher`` is not explicitly
+set it does not allow the weak ``BF-CBC`` cipher anymore and
+needs to explicitly added as ``--cipher BFC-CBC`` or added to
+``-data-ciphers``.
\ No newline at end of file
diff --git a/doc/openvpn.8.rst b/doc/openvpn.8.rst
index 4a7ca3aa..db81274f 100644
--- a/doc/openvpn.8.rst
+++ b/doc/openvpn.8.rst
@@ -75,6 +75,7 @@ placed in a configuration file.
.. include:: man-sections/client-options.rst
.. include:: man-sections/server-options.rst
.. include:: man-sections/encryption-options.rst
+.. include:: man-sections/cipher-negotiation.rst
.. include:: man-sections/network-config.rst
.. include:: man-sections/script-options.rst
.. include:: man-sections/management-options.rst
--
2.26.2
_______________________________________________
Openvpn-devel mailing list
Openvpn-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/openvpn-devel
