1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
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.
|
