diff options
Diffstat (limited to 'doc/man-sections/protocol-options.rst')
| -rw-r--r-- | doc/man-sections/protocol-options.rst | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/doc/man-sections/protocol-options.rst b/doc/man-sections/protocol-options.rst new file mode 100644 index 0000000..e9d5d63 --- /dev/null +++ b/doc/man-sections/protocol-options.rst @@ -0,0 +1,281 @@ +Protocol options +---------------- +Options in this section affect features available in the OpenVPN wire +protocol. Many of these options also define the encryption options +of the data channel in the OpenVPN wire protocol. These options must be +configured in a compatible way between both the local and remote side. + +--allow-compression mode + As described in the ``--compress`` option, compression is a potentially + dangerous option. This option allows controlling the behaviour of + OpenVPN when compression is used and allowed. + + Valid syntaxes: + :: + + allow-compression + allow-compression mode + + The ``mode`` argument can be one of the following values: + + :code:`asym` (default) + OpenVPN will only *decompress downlink packets* but *not compress + uplink packets*. This also allows migrating to disable compression + when changing both server and client configurations to remove + compression at the same time is not a feasible option. + + :code:`no` + OpenVPN will refuse any non-stub compression. + + :code:`yes` + OpenVPN will send and receive compressed packets. + +--auth alg + Authenticate data channel packets and (if enabled) ``tls-auth`` control + channel packets with HMAC using message digest algorithm ``alg``. (The + default is ``SHA1`` ). HMAC is a commonly used message authentication + algorithm (MAC) that uses a data string, a secure hash algorithm and a + key to produce a digital signature. + + The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first + encrypt a packet then HMAC the resulting ciphertext), which prevents + padding oracle attacks. + + If an AEAD cipher mode (e.g. GCM) is chosen then the specified ``--auth`` + algorithm is ignored for the data channel and the authentication method + of the AEAD cipher is used instead. Note that ``alg`` still specifies + the digest used for ``tls-auth``. + + In static-key encryption mode, the HMAC key is included in the key file + generated by ``--genkey``. In TLS mode, the HMAC key is dynamically + generated and shared between peers via the TLS control channel. If + OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC + usually adds 16 or 20 bytes per packet. Set ``alg=none`` to disable + authentication. + + For more information on HMAC see + http://www.cs.ucsd.edu/users/mihir/papers/hmac.html + +--cipher alg + This option is deprecated for server-client mode. ``--data-ciphers`` + or possibly `--data-ciphers-fallback`` should be used instead. + + Encrypt data channel packets with cipher algorithm ``alg``. + + The default is :code:`BF-CBC`, an abbreviation for Blowfish in Cipher + Block Chaining mode. When cipher negotiation (NCP) is allowed, + OpenVPN 2.4 and newer on both client and server side will automatically + upgrade to :code:`AES-256-GCM`. See ``--data-ciphers`` and + ``--ncp-disable`` for more details on NCP. + + Using :code:`BF-CBC` is no longer recommended, because of its 64-bit + block size. This small block size allows attacks based on collisions, as + demonstrated by SWEET32. See + https://community.openvpn.net/openvpn/wiki/SWEET32 + for details. Due to this, support for :code:`BF-CBC`, :code:`DES`, + :code:`CAST5`, :code:`IDEA` and :code:`RC2` ciphers will be removed in + OpenVPN 2.6. + + To see other ciphers that are available with OpenVPN, use the + ``--show-ciphers`` option. + + Set ``alg`` to :code:`none` to disable encryption. + +--compress algorithm + **DEPRECATED** Enable a compression algorithm. Compression is generally + not recommended. VPN tunnels which use compression are susceptible to + the VORALCE attack vector. + + The ``algorithm`` parameter may be :code:`lzo`, :code:`lz4`, + :code:`lz4-v2`, :code:`stub`, :code:`stub-v2` or empty. + LZO and LZ4 are different compression algorithms, with LZ4 generally + offering the best performance with least CPU usage. + + The :code:`lz4-v2` and :code:`stub-v2` variants implement a better + framing that does not add overhead when packets cannot be compressed. All + other variants always add one extra framing byte compared to no + compression framing. + + If the ``algorithm`` parameter is :code:`stub`, :code:`stub-v2` or empty, + compression will be turned off, but the packet framing for compression + will still be enabled, allowing a different setting to be pushed later. + Additionally, :code:`stub` and :code:`stub-v2` wil disable announcing + ``lzo`` and ``lz4`` compression support via *IV_* variables to the + server. + + Note: the :code:`stub` (or empty) option is NOT compatible with the older + option ``--comp-lzo no``. + + ***Security Considerations*** + + Compression and encryption is a tricky combination. If an attacker knows + or is able to control (parts of) the plain-text of packets that contain + secrets, the attacker might be able to extract the secret if compression + is enabled. See e.g. the *CRIME* and *BREACH* attacks on TLS and + *VORACLE* on VPNs which also leverage to break encryption. If you are not + entirely sure that the above does not apply to your traffic, you are + advised to *not* enable compression. + +--comp-lzo mode + **DEPRECATED** Enable LZO compression algorithm. Compression is + generally not recommended. VPN tunnels which uses compression are + suspectible to the VORALCE attack vector. + + Use LZO compression -- may add up to 1 byte per packet for incompressible + data. ``mode`` may be :code:`yes`, :code:`no`, or :code:`adaptive` + (default). + + In a server mode setup, it is possible to selectively turn compression + on or off for individual clients. + + First, make sure the client-side config file enables selective + compression by having at least one ``--comp-lzo`` directive, such as + ``--comp-lzo no``. This will turn off compression by default, but allow + a future directive push from the server to dynamically change the + :code:`on`/:code:`off`/:code:`adaptive` setting. + + Next in a ``--client-config-dir`` file, specify the compression setting + for the client, for example: + :: + + comp-lzo yes + push "comp-lzo yes" + + The first line sets the ``comp-lzo`` setting for the server side of the + link, the second sets the client side. + +--comp-noadapt + **DEPRECATED** When used in conjunction with ``--comp-lzo``, this option + will disable OpenVPN's adaptive compression algorithm. Normally, adaptive + compression is enabled with ``--comp-lzo``. + + Adaptive compression tries to optimize the case where you have + compression enabled, but you are sending predominantly incompressible + (or pre-compressed) packets over the tunnel, such as an FTP or rsync + transfer of a large, compressed file. With adaptive compression, OpenVPN + will periodically sample the compression process to measure its + efficiency. If the data being sent over the tunnel is already + compressed, the compression efficiency will be very low, triggering + openvpn to disable compression for a period of time until the next + re-sample test. + +--key-direction + Alternative way of specifying the optional direction parameter for the + ``--tls-auth`` and ``--secret`` options. Useful when using inline files + (See section on inline files). + +--keysize n + **DEPRECATED** This option will be removed in OpenVPN 2.6. + + Size of cipher key in bits (optional). If unspecified, defaults to + cipher-specific default. The ``--show-ciphers`` option (see below) shows + all available OpenSSL ciphers, their default key sizes, and whether the + key size can be changed. Use care in changing a cipher's default key + size. Many ciphers have not been extensively cryptanalyzed with + non-standard key lengths, and a larger key may offer no real guarantee + of greater security, or may even reduce security. + +--data-ciphers cipher-list + Restrict the allowed ciphers to be negotiated to the ciphers in + ``cipher-list``. ``cipher-list`` is a colon-separated list of ciphers, + and defaults to :code:`AES-256-GCM:AES-128-GCM`. + + For servers, the first cipher from ``cipher-list`` that is also + supported by the client will be pushed to clients that support cipher + negotiation. + + Cipher negotiation is enabled in client-server mode only. I.e. if + ``--mode`` is set to 'server' (server-side, implied by setting + ``--server`` ), or if ``--pull`` is specified (client-side, implied by + setting --client). + + If no common cipher is found during cipher negotiation, the connection + is terminated. To support old clients/old servers that do not provide any + cipher negotiation support see ``--data-ciphers-fallback``. + + Additionally, to allow for more smooth transition, if NCP is enabled, + OpenVPN will inherit the cipher of the peer if that cipher is different + from the local ``--cipher`` setting, but the peer cipher is one of the + ciphers specified in ``--data-ciphers``. E.g. a non-NCP client (<=v2.3, + or with --ncp-disabled set) connecting to a NCP server (v2.4+) with + ``--cipher BF-CBC`` and ``--data-ciphers AES-256-GCM:AES-256-CBC`` set can + either specify ``--cipher BF-CBC`` or ``--cipher AES-256-CBC`` and both + will work. + + Note for using NCP with an OpenVPN 2.4 peer: This list must include the + :code:`AES-256-GCM` and :code:`AES-128-GCM` ciphers. + + This list is restricted to be 127 chars long after conversion to OpenVPN + ciphers. + + This option was called ``--ncp-ciphers`` in OpenVPN 2.4 but has been renamed + to ``--data-ciphers`` in OpenVPN 2.5 to more accurately reflect its meaning. + +--data-ciphers-fallback alg + + Configure a cipher that is used to fall back to if we could not determine + which cipher the peer is willing to use. + + This option should only be needed to + connect to peers that are running OpenVPN 2.3 and older version, and + have been configured with `--enable-small` + (typically used on routers or other embedded devices). + +--ncp-disable + **DEPRECATED** Disable "Negotiable Crypto Parameters". This completely + disables cipher negotiation. + +--secret args + Enable Static Key encryption mode (non-TLS). Use pre-shared secret + ``file`` which was generated with ``--genkey``. + + Valid syntaxes: + :: + + secret file + secret file direction + + The optional ``direction`` parameter enables the use of 4 distinct keys + (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each + data flow direction has a different set of HMAC and cipher keys. This + has a number of desirable security properties including eliminating + certain kinds of DoS and message replay attacks. + + When the ``direction`` parameter is omitted, 2 keys are used + bidirectionally, one for HMAC and the other for encryption/decryption. + + The ``direction`` parameter should always be complementary on either + side of the connection, i.e. one side should use :code:`0` and the other + should use :code:`1`, or both sides should omit it altogether. + + The ``direction`` parameter requires that ``file`` contains a 2048 bit + key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any + version of OpenVPN which supports the ``direction`` parameter, will also + support 2048 bit key file generation using the ``--genkey`` option. + + Static key encryption mode has certain advantages, the primary being + ease of configuration. + + There are no certificates or certificate authorities or complicated + negotiation handshakes and protocols. The only requirement is that you + have a pre-existing secure channel with your peer (such as ``ssh``) to + initially copy the key. This requirement, along with the fact that your + key never changes unless you manually generate a new one, makes it + somewhat less secure than TLS mode (see below). If an attacker manages + to steal your key, everything that was ever encrypted with it is + compromised. Contrast that to the perfect forward secrecy features of + TLS mode (using Diffie Hellman key exchange), where even if an attacker + was able to steal your private key, he would gain no information to help + him decrypt past sessions. + + Another advantageous aspect of Static Key encryption mode is that it is + a handshake-free protocol without any distinguishing signature or + feature (such as a header or protocol handshake sequence) that would + mark the ciphertext packets as being generated by OpenVPN. Anyone + eavesdropping on the wire would see nothing but random-looking data. + +--tran-window n + Transition window -- our old key can live this many seconds after a new + a key renegotiation begins (default :code:`3600` seconds). This feature + allows for a graceful transition from old to new key, and removes the key + renegotiation sequence from the critical path of tunnel data forwarding. |