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.

The mode argument can be one of the following values:

:code:asym OpenVPN will only decompress incoming packets but not compress outgoing 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 (default) OpenVPN will refuse any compression. If data-channel offloading is enabled, OpenVPN will additionally also refuse compression framing (stub).

:code:yes DEPRECATED This option is an alias for :code:asym. Previously it did enable compression for outgoing packets, but OpenVPN never compresses packets on send now.

--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 https://tools.ietf.org/html/rfc2104

--cipher alg This option should not be used any longer in TLS mode and still exists for two reasons:

compatibility with old configurations still carrying it around;
allow users connecting to OpenVPN peers older than 2.6.0 to have --cipher configured the same way as the remote counterpart. This can avoid MTU/frame size warnings.

Before 2.4.0, this option was used to select the cipher to be configured on the data channel, however, later versions usually ignored this directive in favour of a negotiated cipher. Starting with 2.6.0, this option is always ignored in TLS mode when it comes to configuring the cipher.

If you wish to specify the cipher to use on the data channel, please see --data-ciphers (for regular negotiation) and --data-ciphers-fallback (for a fallback option when the negotiation cannot take place because the other peer is old or has negotiation disabled).

To see 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. See also the :code:migrate parameter below.

The algorithm parameter may be :code:lzo, :code:lz4, :code:lz4-v2, :code:stub, :code:stub-v2, :code:migrate 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.

Especially :code:stub-v2 is essentially identical to no compression and no compression framing as its header indicates IP version 5 in a tun setup and can (ab)used to complete disable compression to clients. (See the :code:migrate option below)

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.

Using :code:migrate as compression algorithm enables a special migration mode. It allows migration away from the --compress/--comp-lzo options to no compression. This option sets the server to no compression mode and the server behaves identical to a server without a compression option for all clients without a compression in their config. However, if a client is detected that indicates that compression is used (via OCC), the server will automatically add --push compress stub-v2 to the client specific configuration if supported by the client and otherwise switch to comp-lzo no and add --push comp-lzo to the client specific configuration.

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.

For this reason compression support was removed from current versions of OpenVPN. It will still decompress compressed packets received via a VPN connection but it will never compress any outgoing packets.

--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.

Allows the other side of the connection to use LZO compression. Due to difference in packet format this may add 1 additional byte per packet. With current versions of OpenVPN no actual compression will happen.

mode may be :code:yes, :code:no, or :code:adaptive but there is no actual change in behavior anymore.

--comp-noadapt DEPRECATED This option does not have any effect anymore since current versions of OpenVPN never compress outgoing packets.

--key-direction Alternative way of specifying the optional direction parameter for the --tls-auth option. Useful when using inline files (See section on inline files).

--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:CHACHA20-POLY1305 when Chacha20-Poly1305 is available and otherwise :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.

For more details see the chapter on Data channel cipher negotiation_. Especially if you need to support clients with OpenVPN versions older than 2.4!

Starting with OpenVPN 2.6 a cipher can be prefixed with a :code:? to mark it as optional. This allows including ciphers in the list that may not be available on all platforms. E.g. :code:AES-256-GCM:AES-128-GCM:?CHACHA20-POLY1305 would only enable Chacha20-Poly1305 if the underlying SSL library (and its configuration) supports it.

Starting with OpenVPN 2.7 the special keyword :code:DEFAULT can be used in the string and is replaced by the default ciphers. This can be used to add an additional allowed cipher to the allowed ciphers, e.g. :code:DEFAULT:AES-192-CBC to use the default ciphers but also allow :code:AES-192-CBC.

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.

If --compat-mode is set to a version older than 2.5.0 the cipher specified by --cipher will be appended to --data-ciphers if not already present.

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 or older versions, and have been configured with --enable-small (typically used on routers or other embedded devices).

--allow-deprecated-insecure-static-crypto DEPRECATED This allow using OpenVPN without TLS. This is deprecated and will be removed in OpenVPN 2.8.

--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.

--force-tls-key-material-export This option is only available in --mode server and forces to use Keying Material Exporters (RFC 5705) for clients. This can be used to simulate an environment where the cryptographic library does not support the older method to generate data channel keys anymore. This option is intended to be a test option and might be removed in a future OpenVPN version without notice.