diff options
Diffstat (limited to 'doc/man-sections')
| -rw-r--r-- | doc/man-sections/cipher-negotiation.rst | 96 | ||||
| -rw-r--r-- | doc/man-sections/vpn-network-options.rst | 23 |
2 files changed, 17 insertions, 102 deletions
diff --git a/doc/man-sections/cipher-negotiation.rst b/doc/man-sections/cipher-negotiation.rst deleted file mode 100644 index f143305..0000000 --- a/doc/man-sections/cipher-negotiation.rst +++ /dev/null @@ -1,96 +0,0 @@ -Data channel cipher negotiation -=============================== - -OpenVPN 2.4 and higher have the capability to 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 list 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 the first iteration of the implementation -and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible". -An OpenVPN 2.4 client that is built 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` to a server by sending :code:`IV_NCP=2`. - -This only causes a problem if ``--ncp-ciphers`` option has been changed from the -default of :code:`AES-256-GCM:AES-128-GCM` to a value that does not include -these two ciphers. When a OpenVPN servers try to use `AES-256-GCM` or -`AES-128-GCM` the connection will then fail. It is therefore recommended to -always have the `AES-256-GCM` and `AES-128-GCM` ciphers to the ``--ncp-ciphers`` -options to avoid this behaviour. - -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 server's ``--data-ciphers`` option. - - -OpenVPN 2.3 and older clients (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 is 2.3 or older and has been configured with the -``--enable-small`` :code:`./configure` argument, using -``data-ciphers-fallback cipher`` in the server config file 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 -the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close -as possible and have compatibility to a setup that depends on this quirk, -adding `AES-128-GCM` and `AES-256-GCM` to the client's ``--data-ciphers`` -option is required. 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 -support. -(For compatibility OpenVPN 2.5 will also accept the cipher set with -``--cipher``) - -If the server is 2.3 or older and has been configured with the -``--enable-small`` :code:`./configure` argument, adding -``data-ciphers-fallback cipher`` to the client config with the explicit -cipher used by the server is necessary. - -Blowfish in CBC mode (BF-CBC) deprecation ------------------------------------------- -The ``--cipher`` option defaulted to ``BF-CBC`` 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 so that if the ``--cipher`` -is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more -and needs to explicitly added as ``--cipher BFC-CBC`` or added to -``-data-ciphers``. - -We strongly recommend to switching away from BF-CBC to a -more secure cipher as soon as possible instead. diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst index 7100c1a..825dd1c 100644 --- a/doc/man-sections/vpn-network-options.rst +++ b/doc/man-sections/vpn-network-options.rst @@ -93,12 +93,18 @@ routing. or :code:`tap`. --dhcp-option args - Set additional network settings via DHCP. On Windows, this is parsed by - the ``tap-windows6`` or ``wintun`` driver. On other platforms these - options can be picked up by an ``--up`` script or plug-in if it has been - pushed by the OpenVPN server. The option will then be saved in the - client's environment before the ``--up`` script is called, under the name - :code:`foreign_option_{n}`. + Set additional network parameters on supported platforms. May be specified + on the client or pushed from the server. On Windows these options are + handled by the ``tap-windows6`` driver by default or directly by OpenVPN + if dhcp is disabled or the ``wintun`` driver is in use. The + ``OpenVPN for Android`` client also handles them internally. + + On all other platforms these options are only saved in the client's + environment under the name :code:`foreign_options_{n}` before the + ``--up`` script is called. A plugin or an ``--up`` script must be used to + pick up and interpret these as required. Many Linux distributions include + such scripts and some third-party user interfaces such as tunnelblick also + come with scripts that process these options. Valid syntax: :: @@ -108,6 +114,11 @@ routing. :code:`DOMAIN` ``name`` Set Connection-specific DNS Suffix to :code:`name`. + :code:`DOMAIN-SEARCH` ``name`` + Add :code:`name` to the domain search list. + Repeat this option to add more entries. Up to + 10 domains are supported. + :code:`DNS` ``address`` Set primary domain name server IPv4 or IPv6 address. Repeat this option to set secondary DNS server addresses. |