]>
Commit | Line | Data |
---|---|---|
f500c49c DS |
1 | TLS Mode Options |
2 | ---------------- | |
3 | ||
4 | TLS mode is the most powerful crypto mode of OpenVPN in both security | |
5 | and flexibility. TLS mode works by establishing control and data | |
6 | channels which are multiplexed over a single TCP/UDP port. OpenVPN | |
7 | initiates a TLS session over the control channel and uses it to exchange | |
8 | cipher and HMAC keys to protect the data channel. TLS mode uses a robust | |
9 | reliability layer over the UDP connection for all control channel | |
10 | communication, while the data channel, over which encrypted tunnel data | |
11 | passes, is forwarded without any mediation. The result is the best of | |
12 | both worlds: a fast data channel that forwards over UDP with only the | |
13 | overhead of encrypt, decrypt, and HMAC functions, and a control channel | |
14 | that provides all of the security features of TLS, including | |
15 | certificate-based authentication and Diffie Hellman forward secrecy. | |
16 | ||
17 | To use TLS mode, each peer that runs OpenVPN should have its own local | |
18 | certificate/key pair (``--cert`` and ``--key``), signed by the root | |
19 | certificate which is specified in ``--ca``. | |
20 | ||
21 | When two OpenVPN peers connect, each presents its local certificate to | |
22 | the other. Each peer will then check that its partner peer presented a | |
23 | certificate which was signed by the master root certificate as specified | |
24 | in ``--ca``. | |
25 | ||
26 | If that check on both peers succeeds, then the TLS negotiation will | |
27 | succeed, both OpenVPN peers will exchange temporary session keys, and | |
28 | the tunnel will begin passing data. | |
29 | ||
30 | The OpenVPN project provides a set of scripts for managing RSA | |
31 | certificates and keys: https://github.com/OpenVPN/easy-rsa | |
32 | ||
33 | --askpass file | |
34 | Get certificate password from console or ``file`` before we daemonize. | |
35 | ||
36 | Valid syntaxes: | |
37 | :: | |
38 | ||
39 | askpass | |
40 | askpass file | |
41 | ||
42 | For the extremely security conscious, it is possible to protect your | |
43 | private key with a password. Of course this means that every time the | |
44 | OpenVPN daemon is started you must be there to type the password. The | |
45 | ``--askpass`` option allows you to start OpenVPN from the command line. | |
46 | It will query you for a password before it daemonizes. To protect a | |
47 | private key with a password you should omit the ``-nodes`` option when | |
48 | you use the ``openssl`` command line tool to manage certificates and | |
49 | private keys. | |
50 | ||
51 | If ``file`` is specified, read the password from the first line of | |
52 | ``file``. Keep in mind that storing your password in a file to a certain | |
53 | extent invalidates the extra security provided by using an encrypted | |
54 | key. | |
55 | ||
56 | --ca file | |
57 | Certificate authority (CA) file in .pem format, also referred to as the | |
58 | *root* certificate. This file can have multiple certificates in .pem | |
59 | format, concatenated together. You can construct your own certificate | |
60 | authority certificate and private key by using a command such as: | |
61 | :: | |
62 | ||
63 | openssl req -nodes -new -x509 -keyout ca.key -out ca.crt | |
64 | ||
65 | Then edit your openssl.cnf file and edit the ``certificate`` variable to | |
66 | point to your new root certificate ``ca.crt``. | |
67 | ||
68 | For testing purposes only, the OpenVPN distribution includes a sample CA | |
69 | certificate (ca.crt). Of course you should never use the test | |
70 | certificates and test keys distributed with OpenVPN in a production | |
71 | environment, since by virtue of the fact that they are distributed with | |
72 | OpenVPN, they are totally insecure. | |
73 | ||
74 | --capath dir | |
75 | Directory containing trusted certificates (CAs and CRLs). Not available | |
76 | with mbed TLS. | |
77 | ||
78 | CAs in the capath directory are expected to be named <hash>.<n>. CRLs | |
79 | are expected to be named <hash>.r<n>. See the ``-CApath`` option of | |
80 | ``openssl verify``, and the ``-hash`` option of ``openssl x509``, | |
81 | ``openssl crl`` and ``X509_LOOKUP_hash_dir()``\(3) | |
82 | for more information. | |
83 | ||
84 | Similar to the ``--crl-verify`` option, CRLs are not mandatory - | |
85 | OpenVPN will log the usual warning in the logs if the relevant CRL is | |
86 | missing, but the connection will be allowed. | |
87 | ||
88 | --cert file | |
89 | Local peer's signed certificate in .pem format -- must be signed by a | |
90 | certificate authority whose certificate is in ``--ca file``. Each peer | |
91 | in an OpenVPN link running in TLS mode should have its own certificate | |
92 | and private key file. In addition, each certificate should have been | |
93 | signed by the key of a certificate authority whose public key resides in | |
94 | the ``--ca`` certificate authority file. You can easily make your own | |
95 | certificate authority (see above) or pay money to use a commercial | |
96 | service such as thawte.com (in which case you will be helping to finance | |
97 | the world's second space tourist :). To generate a certificate, you can | |
98 | use a command such as: | |
99 | :: | |
100 | ||
101 | openssl req -nodes -new -keyout mycert.key -out mycert.csr | |
102 | ||
103 | If your certificate authority private key lives on another machine, copy | |
104 | the certificate signing request (mycert.csr) to this other machine (this | |
105 | can be done over an insecure channel such as email). Now sign the | |
106 | certificate with a command such as: | |
107 | :: | |
108 | ||
109 | openssl ca -out mycert.crt -in mycert.csr | |
110 | ||
111 | Now copy the certificate (mycert.crt) back to the peer which initially | |
112 | generated the .csr file (this can be over a public medium). Note that | |
113 | the ``openssl ca`` command reads the location of the certificate | |
114 | authority key from its configuration file such as | |
115 | :code:`/usr/share/ssl/openssl.cnf` -- note also that for certificate | |
116 | authority functions, you must set up the files :code:`index.txt` (may be | |
117 | empty) and :code:`serial` (initialize to :code:`01`). | |
118 | ||
119 | --crl-verify args | |
120 | Check peer certificate against a Certificate Revocation List. | |
121 | ||
122 | Valid syntax: | |
123 | :: | |
124 | ||
125 | crl-verify file/directory flag | |
126 | ||
127 | Examples: | |
128 | :: | |
129 | ||
130 | crl-verify crl-file.pem | |
131 | crl-verify /etc/openvpn/crls dir | |
132 | ||
133 | A CRL (certificate revocation list) is used when a particular key is | |
134 | compromised but when the overall PKI is still intact. | |
135 | ||
136 | Suppose you had a PKI consisting of a CA, root certificate, and a number | |
137 | of client certificates. Suppose a laptop computer containing a client | |
138 | key and certificate was stolen. By adding the stolen certificate to the | |
139 | CRL file, you could reject any connection which attempts to use it, | |
140 | while preserving the overall integrity of the PKI. | |
141 | ||
142 | The only time when it would be necessary to rebuild the entire PKI from | |
143 | scratch would be if the root certificate key itself was compromised. | |
144 | ||
145 | The option is not mandatory - if the relevant CRL is missing, OpenVPN | |
146 | will log a warning in the logs - e.g. | |
147 | :: | |
148 | ||
149 | VERIFY WARNING: depth=0, unable to get certificate CRL | |
150 | ||
151 | but the connection will be allowed. If the optional :code:`dir` flag | |
152 | is specified, enable a different mode where the ``crl-verify`` is | |
153 | pointed at a directory containing files named as revoked serial numbers | |
154 | (the files may be empty, the contents are never read). If a client | |
155 | requests a connection, where the client certificate serial number | |
156 | (decimal string) is the name of a file present in the directory, it will | |
157 | be rejected. | |
158 | ||
159 | *Note:* | |
160 | As the crl file (or directory) is read every time a peer | |
161 | connects, if you are dropping root privileges with | |
162 | ``--user``, make sure that this user has sufficient | |
163 | privileges to read the file. | |
164 | ||
165 | ||
166 | --dh file | |
167 | File containing Diffie Hellman parameters in .pem format (required for | |
168 | ``--tls-server`` only). | |
169 | ||
170 | Set ``file`` to :code:`none` to disable Diffie Hellman key exchange (and | |
171 | use ECDH only). Note that this requires peers to be using an SSL library | |
172 | that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or | |
173 | mbed TLS 2.0+). | |
174 | ||
175 | Use ``openssl dhparam -out dh2048.pem 2048`` to generate 2048-bit DH | |
176 | parameters. Diffie Hellman parameters may be considered public. | |
177 | ||
178 | --ecdh-curve name | |
179 | Specify the curve to use for elliptic curve Diffie Hellman. Available | |
180 | curves can be listed with ``--show-curves``. The specified curve will | |
181 | only be used for ECDH TLS-ciphers. | |
182 | ||
183 | This option is not supported in mbed TLS builds of OpenVPN. | |
184 | ||
185 | --extra-certs file | |
186 | Specify a ``file`` containing one or more PEM certs (concatenated | |
187 | together) that complete the local certificate chain. | |
188 | ||
189 | This option is useful for "split" CAs, where the CA for server certs is | |
190 | different than the CA for client certs. Putting certs in this file | |
191 | allows them to be used to complete the local certificate chain without | |
192 | trusting them to verify the peer-submitted certificate, as would be the | |
193 | case if the certs were placed in the ``ca`` file. | |
194 | ||
195 | --hand-window n | |
196 | Handshake Window -- the TLS-based key exchange must finalize within | |
197 | ``n`` seconds of handshake initiation by any peer (default :code:`60` | |
198 | seconds). If the handshake fails we will attempt to reset our connection | |
199 | with our peer and try again. Even in the event of handshake failure we | |
200 | will still use our expiring key for up to ``--tran-window`` seconds to | |
201 | maintain continuity of transmission of tunnel data. | |
202 | ||
413580b6 AS |
203 | The ``--hand-window`` parameter also controls the amount of time that |
204 | the OpenVPN client repeats the pull request until it times out. | |
205 | ||
f500c49c DS |
206 | --key file |
207 | Local peer's private key in .pem format. Use the private key which was | |
208 | generated when you built your peer's certificate (see ``--cert file`` | |
209 | above). | |
210 | ||
211 | --pkcs12 file | |
212 | Specify a PKCS #12 file containing local private key, local certificate, | |
213 | and root CA certificate. This option can be used instead of ``--ca``, | |
214 | ``--cert``, and ``--key``. Not available with mbed TLS. | |
215 | ||
216 | --remote-cert-eku oid | |
217 | Require that peer certificate was signed with an explicit *extended key | |
218 | usage*. | |
219 | ||
220 | This is a useful security option for clients, to ensure that the host | |
221 | they connect to is a designated server. | |
222 | ||
223 | The extended key usage should be encoded in *oid notation*, or *OpenSSL | |
224 | symbolic representation*. | |
225 | ||
226 | --remote-cert-ku key-usage | |
227 | Require that peer certificate was signed with an explicit | |
228 | ``key-usage``. | |
229 | ||
230 | If present in the certificate, the :code:`keyUsage` value is validated by | |
231 | the TLS library during the TLS handshake. Specifying this option without | |
232 | arguments requires this extension to be present (so the TLS library will | |
233 | verify it). | |
234 | ||
235 | If ``key-usage`` is a list of usage bits, the :code:`keyUsage` field | |
236 | must have *at least* the same bits set as the bits in *one of* the values | |
237 | supplied in the ``key-usage`` list. | |
238 | ||
239 | The ``key-usage`` values in the list must be encoded in hex, e.g. | |
240 | :: | |
241 | ||
242 | remote-cert-ku a0 | |
243 | ||
244 | --remote-cert-tls type | |
245 | Require that peer certificate was signed with an explicit *key usage* | |
246 | and *extended key usage* based on RFC3280 TLS rules. | |
247 | ||
248 | Valid syntaxes: | |
249 | :: | |
250 | ||
251 | remote-cert-tls server | |
252 | remote-cert-tls client | |
253 | ||
254 | This is a useful security option for clients, to ensure that the host | |
255 | they connect to is a designated server. Or the other way around; for a | |
256 | server to verify that only hosts with a client certificate can connect. | |
257 | ||
258 | The ``--remote-cert-tls client`` option is equivalent to | |
259 | :: | |
260 | ||
261 | remote-cert-ku | |
262 | remote-cert-eku "TLS Web Client Authentication" | |
263 | ||
264 | The ``--remote-cert-tls server`` option is equivalent to | |
265 | :: | |
266 | ||
267 | remote-cert-ku | |
268 | remote-cert-eku "TLS Web Server Authentication" | |
269 | ||
270 | This is an important security precaution to protect against a | |
271 | man-in-the-middle attack where an authorized client attempts to connect | |
272 | to another client by impersonating the server. The attack is easily | |
273 | prevented by having clients verify the server certificate using any one | |
c3a7065d AS |
274 | of ``--remote-cert-tls``, ``--verify-x509-name``, ``--peer-fingerprint`` |
275 | or ``--tls-verify``. | |
f500c49c DS |
276 | |
277 | --tls-auth args | |
278 | Add an additional layer of HMAC authentication on top of the TLS control | |
279 | channel to mitigate DoS attacks and attacks on the TLS stack. | |
280 | ||
281 | Valid syntaxes: | |
282 | :: | |
283 | ||
284 | tls-auth file | |
285 | tls-auth file 0 | |
286 | tls-auth file 1 | |
287 | ||
288 | In a nutshell, ``--tls-auth`` enables a kind of "HMAC firewall" on | |
289 | OpenVPN's TCP/UDP port, where TLS control channel packets bearing an | |
290 | incorrect HMAC signature can be dropped immediately without response. | |
291 | ||
292 | ``file`` (required) is a file in OpenVPN static key format which can be | |
293 | generated by ``--genkey``. | |
294 | ||
295 | Older versions (up to OpenVPN 2.3) supported a freeform passphrase file. | |
296 | This is no longer supported in newer versions (v2.4+). | |
297 | ||
298 | See the ``--secret`` option for more information on the optional | |
299 | ``direction`` parameter. | |
300 | ||
301 | ``--tls-auth`` is recommended when you are running OpenVPN in a mode | |
302 | where it is listening for packets from any IP address, such as when | |
303 | ``--remote`` is not specified, or ``--remote`` is specified with | |
304 | ``--float``. | |
305 | ||
306 | The rationale for this feature is as follows. TLS requires a | |
307 | multi-packet exchange before it is able to authenticate a peer. During | |
308 | this time before authentication, OpenVPN is allocating resources (memory | |
309 | and CPU) to this potential peer. The potential peer is also exposing | |
310 | many parts of OpenVPN and the OpenSSL library to the packets it is | |
311 | sending. Most successful network attacks today seek to either exploit | |
312 | bugs in programs (such as buffer overflow attacks) or force a program to | |
313 | consume so many resources that it becomes unusable. Of course the first | |
314 | line of defense is always to produce clean, well-audited code. OpenVPN | |
315 | has been written with buffer overflow attack prevention as a top | |
316 | priority. But as history has shown, many of the most widely used network | |
317 | applications have, from time to time, fallen to buffer overflow attacks. | |
318 | ||
319 | So as a second line of defense, OpenVPN offers this special layer of | |
320 | authentication on top of the TLS control channel so that every packet on | |
321 | the control channel is authenticated by an HMAC signature and a unique | |
322 | ID for replay protection. This signature will also help protect against | |
323 | DoS (Denial of Service) attacks. An important rule of thumb in reducing | |
324 | vulnerability to DoS attacks is to minimize the amount of resources a | |
325 | potential, but as yet unauthenticated, client is able to consume. | |
326 | ||
327 | ``--tls-auth`` does this by signing every TLS control channel packet | |
328 | with an HMAC signature, including packets which are sent before the TLS | |
329 | level has had a chance to authenticate the peer. The result is that | |
330 | packets without the correct signature can be dropped immediately upon | |
331 | reception, before they have a chance to consume additional system | |
332 | resources such as by initiating a TLS handshake. ``--tls-auth`` can be | |
333 | strengthened by adding the ``--replay-persist`` option which will keep | |
334 | OpenVPN's replay protection state in a file so that it is not lost | |
335 | across restarts. | |
336 | ||
337 | It should be emphasized that this feature is optional and that the key | |
338 | file used with ``--tls-auth`` gives a peer nothing more than the power | |
339 | to initiate a TLS handshake. It is not used to encrypt or authenticate | |
340 | any tunnel data. | |
341 | ||
342 | Use ``--tls-crypt`` instead if you want to use the key file to not only | |
343 | authenticate, but also encrypt the TLS control channel. | |
344 | ||
8353ae80 AS |
345 | --tls-groups list |
346 | A list of allowable groups/curves in order of preference. | |
347 | ||
348 | Set the allowed elliptic curves/groups for the TLS session. | |
349 | These groups are allowed to be used in signatures and key exchange. | |
350 | ||
351 | mbedTLS currently allows all known curves per default. | |
352 | ||
353 | OpenSSL 1.1+ restricts the list per default to | |
354 | :: | |
355 | ||
356 | "X25519:secp256r1:X448:secp521r1:secp384r1". | |
357 | ||
358 | If you use certificates that use non-standard curves, you | |
359 | might need to add them here. If you do not force the ecdh curve | |
360 | by using ``--ecdh-curve``, the groups for ecdh will also be picked | |
361 | from this list. | |
362 | ||
363 | OpenVPN maps the curve name `secp256r1` to `prime256v1` to allow | |
364 | specifying the same tls-groups option for mbedTLS and OpenSSL. | |
365 | ||
366 | Warning: this option not only affects elliptic curve certificates | |
367 | but also the key exchange in TLS 1.3 and using this option improperly | |
368 | will disable TLS 1.3. | |
369 | ||
f500c49c DS |
370 | --tls-cert-profile profile |
371 | Set the allowed cryptographic algorithms for certificates according to | |
372 | ``profile``. | |
373 | ||
374 | The following profiles are supported: | |
375 | ||
23efeb7a AS |
376 | :code:`insecure` |
377 | Identical for mbed TLS to `legacy` | |
378 | ||
f500c49c DS |
379 | :code:`legacy` (default) |
380 | SHA1 and newer, RSA 2048-bit+, any elliptic curve. | |
381 | ||
382 | :code:`preferred` | |
383 | SHA2 and newer, RSA 2048-bit+, any elliptic curve. | |
384 | ||
385 | :code:`suiteb` | |
386 | SHA256/SHA384, ECDSA with P-256 or P-384. | |
387 | ||
388 | This option is only fully supported for mbed TLS builds. OpenSSL builds | |
389 | use the following approximation: | |
390 | ||
23efeb7a AS |
391 | :code:`insecure` |
392 | sets "security level 0" | |
393 | ||
f500c49c DS |
394 | :code:`legacy` (default) |
395 | sets "security level 1" | |
396 | ||
397 | :code:`preferred` | |
398 | sets "security level 2" | |
399 | ||
400 | :code:`suiteb` | |
401 | sets "security level 3" and ``--tls-cipher "SUITEB128"``. | |
402 | ||
403 | OpenVPN will migrate to 'preferred' as default in the future. Please | |
404 | ensure that your keys already comply. | |
405 | ||
8353ae80 | 406 | *WARNING:* ``--tls-ciphers``, ``--tls-ciphersuites`` and ``tls-groups`` |
f500c49c DS |
407 | These options are expert features, which - if used correctly - can |
408 | improve the security of your VPN connection. But it is also easy to | |
409 | unwittingly use them to carefully align a gun with your foot, or just | |
410 | break your connection. Use with care! | |
411 | ||
412 | --tls-cipher l | |
413 | A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`"). | |
414 | ||
415 | These setting can be used to ensure that certain cipher suites are used | |
416 | (or not used) for the TLS connection. OpenVPN uses TLS to secure the | |
417 | control channel, over which the keys that are used to protect the actual | |
418 | VPN traffic are exchanged. | |
419 | ||
420 | The supplied list of ciphers is (after potential OpenSSL/IANA name | |
421 | translation) simply supplied to the crypto library. Please see the | |
422 | OpenSSL and/or mbed TLS documentation for details on the cipher list | |
423 | interpretation. | |
424 | ||
425 | For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below. | |
426 | ||
427 | Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto | |
428 | library. | |
429 | ||
430 | The default for ``--tls-cipher`` is to use mbed TLS's default cipher list | |
431 | when using mbed TLS or | |
432 | :code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when | |
433 | using OpenSSL. | |
434 | ||
f500c49c DS |
435 | --tls-ciphersuites l |
436 | Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no | |
437 | TLS 1.3 support yet and only the ``--tls-cipher`` setting is used. | |
438 | ||
3b1ded39 RB |
439 | The default for `--tls-ciphersuites` is to use the crypto library's |
440 | default. | |
441 | ||
f500c49c DS |
442 | --tls-client |
443 | Enable TLS and assume client role during TLS handshake. | |
444 | ||
445 | --tls-crypt keyfile | |
446 | Encrypt and authenticate all control channel packets with the key from | |
447 | ``keyfile``. (See ``--tls-auth`` for more background.) | |
448 | ||
449 | Encrypting (and authenticating) control channel packets: | |
450 | ||
451 | * provides more privacy by hiding the certificate used for the TLS | |
452 | connection, | |
453 | ||
454 | * makes it harder to identify OpenVPN traffic as such, | |
455 | ||
456 | * provides "poor-man's" post-quantum security, against attackers who will | |
457 | never know the pre-shared key (i.e. no forward secrecy). | |
458 | ||
459 | In contrast to ``--tls-auth``, ``--tls-crypt`` does *not* require the | |
460 | user to set ``--key-direction``. | |
461 | ||
462 | **Security Considerations** | |
463 | ||
464 | All peers use the same ``--tls-crypt`` pre-shared group key to | |
465 | authenticate and encrypt control channel messages. To ensure that IV | |
466 | collisions remain unlikely, this key should not be used to encrypt more | |
467 | than 2^48 client-to-server or 2^48 server-to-client control channel | |
468 | messages. A typical initial negotiation is about 10 packets in each | |
469 | direction. Assuming both initial negotiation and renegotiations are at | |
470 | most 2^16 (65536) packets (to be conservative), and (re)negotiations | |
471 | happen each minute for each user (24/7), this limits the tls-crypt key | |
472 | lifetime to 8171 years divided by the number of users. So a setup with | |
473 | 1000 users should rotate the key at least once each eight years. (And a | |
474 | setup with 8000 users each year.) | |
475 | ||
476 | If IV collisions were to occur, this could result in the security of | |
477 | ``--tls-crypt`` degrading to the same security as using ``--tls-auth``. | |
478 | That is, the control channel still benefits from the extra protection | |
479 | against active man-in-the-middle-attacks and DoS attacks, but may no | |
480 | longer offer extra privacy and post-quantum security on top of what TLS | |
481 | itself offers. | |
482 | ||
483 | For large setups or setups where clients are not trusted, consider using | |
484 | ``--tls-crypt-v2`` instead. That uses per-client unique keys, and | |
485 | thereby improves the bounds to 'rotate a client key at least once per | |
486 | 8000 years'. | |
487 | ||
488 | --tls-crypt-v2 keyfile | |
e7d8c4a7 | 489 | |
ceeb37a6 HH |
490 | Valid syntax:: |
491 | ||
e7d8c4a7 AS |
492 | tls-crypt-v2 keyfile |
493 | tls-crypt-v2 keyfile force-cookie | |
494 | tls-crypt-v2 keyfile allow-noncookie | |
495 | ||
f500c49c DS |
496 | Use client-specific tls-crypt keys. |
497 | ||
498 | For clients, ``keyfile`` is a client-specific tls-crypt key. Such a key | |
499 | can be generated using the :code:`--genkey tls-crypt-v2-client` option. | |
500 | ||
501 | For servers, ``keyfile`` is used to unwrap client-specific keys supplied | |
502 | by the client during connection setup. This key must be the same as the | |
503 | key used to generate the client-specific key (see :code:`--genkey | |
504 | tls-crypt-v2-client`). | |
505 | ||
506 | On servers, this option can be used together with the ``--tls-auth`` or | |
507 | ``--tls-crypt`` option. In that case, the server will detect whether the | |
508 | client is using client-specific keys, and automatically select the right | |
509 | mode. | |
510 | ||
e7d8c4a7 AS |
511 | The optional parameters :code:`force-cookie` allows only tls-crypt-v2 |
512 | clients that support a cookie based stateless three way handshake that | |
513 | avoids replay attacks and state exhaustion on the server side (OpenVPN | |
514 | 2.6 and later). The option :code:`allow-noncookie` explicitly allows | |
515 | older tls-crypt-v2 clients. The default is (currently) | |
516 | :code:`allow-noncookie`. | |
517 | ||
f500c49c DS |
518 | --tls-crypt-v2-verify cmd |
519 | Run command ``cmd`` to verify the metadata of the client-specific | |
520 | tls-crypt-v2 key of a connecting client. This allows server | |
521 | administrators to reject client connections, before exposing the TLS | |
522 | stack (including the notoriously dangerous X.509 and ASN.1 stacks) to | |
523 | the connecting client. | |
524 | ||
525 | OpenVPN supplies the following environment variables to the command: | |
526 | ||
527 | * :code:`script_type` is set to :code:`tls-crypt-v2-verify` | |
528 | ||
529 | * :code:`metadata_type` is set to :code:`0` if the metadata was user | |
530 | supplied, or :code:`1` if it's a 64-bit unix timestamp representing | |
531 | the key creation time. | |
532 | ||
533 | * :code:`metadata_file` contains the filename of a temporary file that | |
534 | contains the client metadata. | |
535 | ||
536 | The command can reject the connection by exiting with a non-zero exit | |
537 | code. | |
538 | ||
539 | --tls-exit | |
540 | Exit on TLS negotiation failure. | |
541 | ||
542 | --tls-export-cert directory | |
543 | Store the certificates the clients use upon connection to this | |
544 | directory. This will be done before ``--tls-verify`` is called. The | |
545 | certificates will use a temporary name and will be deleted when the | |
546 | tls-verify script returns. The file name used for the certificate is | |
547 | available via the ``peer_cert`` environment variable. | |
548 | ||
549 | --tls-server | |
550 | Enable TLS and assume server role during TLS handshake. Note that | |
551 | OpenVPN is designed as a peer-to-peer application. The designation of | |
552 | client or server is only for the purpose of negotiating the TLS control | |
553 | channel. | |
554 | ||
555 | --tls-timeout n | |
556 | Packet retransmit timeout on TLS control channel if no acknowledgment | |
557 | from remote within ``n`` seconds (default :code:`2`). When OpenVPN sends | |
558 | a control packet to its peer, it will expect to receive an | |
559 | acknowledgement within ``n`` seconds or it will retransmit the packet, | |
560 | subject to a TCP-like exponential backoff algorithm. This parameter only | |
561 | applies to control channel packets. Data channel packets (which carry | |
562 | encrypted tunnel data) are never acknowledged, sequenced, or | |
563 | retransmitted by OpenVPN because the higher level network protocols | |
564 | running on top of the tunnel such as TCP expect this role to be left to | |
565 | them. | |
566 | ||
567 | --tls-version-min args | |
968569f8 AQ |
568 | Sets the minimum TLS version we will accept from the peer (default in |
569 | 2.6.0 and later is "1.2"). | |
f500c49c DS |
570 | |
571 | Valid syntax: | |
572 | :: | |
573 | ||
574 | tls-version-min version ['or-highest'] | |
575 | ||
576 | Examples for version include :code:`1.0`, :code:`1.1`, or :code:`1.2`. If | |
577 | :code:`or-highest` is specified and version is not recognized, we will | |
578 | only accept the highest TLS version supported by the local SSL | |
579 | implementation. | |
580 | ||
581 | --tls-version-max version | |
582 | Set the maximum TLS version we will use (default is the highest version | |
583 | supported). Examples for version include :code:`1.0`, :code:`1.1`, or | |
584 | :code:`1.2`. | |
585 | ||
586 | --verify-hash args | |
5b8a1231 | 587 | **DEPRECATED** Specify SHA1 or SHA256 fingerprint for level-1 cert. |
f500c49c DS |
588 | |
589 | Valid syntax: | |
590 | :: | |
591 | ||
592 | verify-hash hash [algo] | |
593 | ||
594 | The level-1 cert is the CA (or intermediate cert) that signs the leaf | |
595 | certificate, and is one removed from the leaf certificate in the | |
596 | direction of the root. When accepting a connection from a peer, the | |
597 | level-1 cert fingerprint must match ``hash`` or certificate verification | |
598 | will fail. Hash is specified as XX:XX:... For example: | |
599 | :: | |
600 | ||
601 | AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 | |
602 | ||
603 | The ``algo`` flag can be either :code:`SHA1` or :code:`SHA256`. If not | |
604 | provided, it defaults to :code:`SHA1`. | |
605 | ||
d1fe6d52 AS |
606 | This option can also be inlined |
607 | :: | |
608 | ||
609 | <verify-hash> | |
610 | 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff | |
611 | 11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00 | |
612 | </verify-hash> | |
613 | ||
614 | If the option is inlined, ``algo`` is always :code:`SHA256`. | |
615 | ||
c3a7065d AS |
616 | --peer-fingerprint args |
617 | Specify a SHA256 fingerprint or list of SHA256 fingerprints to verify | |
618 | the peer certificate against. The peer certificate must match one of the | |
619 | fingerprint or certificate verification will fail. The option can also | |
620 | be inlined | |
621 | ||
622 | Valid syntax: | |
623 | :: | |
624 | ||
625 | peer-fingerprint AD:B0:95:D8:09:... | |
626 | ||
627 | or inline: | |
628 | :: | |
629 | ||
630 | <peer-fingerprint> | |
631 | 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff | |
632 | 11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00 | |
633 | </peer-fingerprint> | |
634 | ||
26117a82 AS |
635 | When the ``--peer-fingerprint`` option is used, specifying a CA with ``--ca`` or ``--capath`` is |
636 | optional. This allows the he ``--peer-fingerprint`` to be used as alternative to a PKI with | |
637 | self-signed certificates for small setups. See the examples section for such a setup. | |
638 | ||
f500c49c DS |
639 | --verify-x509-name args |
640 | Accept connections only if a host's X.509 name is equal to **name.** The | |
641 | remote host must also pass all other tests of verification. | |
642 | ||
643 | Valid syntax: | |
644 | :: | |
645 | ||
646 | verify-x509 name type | |
647 | ||
648 | Which X.509 name is compared to ``name`` depends on the setting of type. | |
649 | ``type`` can be :code:`subject` to match the complete subject DN | |
650 | (default), :code:`name` to match a subject RDN or :code:`name-prefix` to | |
651 | match a subject RDN prefix. Which RDN is verified as name depends on the | |
652 | ``--x509-username-field`` option. But it defaults to the common name | |
653 | (CN), e.g. a certificate with a subject DN | |
654 | :: | |
655 | ||
656 | C=KG, ST=NA, L=Bishkek, CN=Server-1 | |
657 | ||
658 | would be matched by: | |
659 | :: | |
660 | ||
661 | verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' | |
662 | verify-x509-name Server-1 name | |
663 | verify-x509-name Server- name-prefix | |
664 | ||
665 | The last example is useful if you want a client to only accept | |
666 | connections to :code:`Server-1`, :code:`Server-2`, etc. | |
667 | ||
668 | ``--verify-x509-name`` is a useful replacement for the ``--tls-verify`` | |
669 | option to verify the remote host, because ``--verify-x509-name`` works | |
670 | in a ``--chroot`` environment without any dependencies. | |
671 | ||
672 | Using a name prefix is a useful alternative to managing a CRL | |
673 | (Certificate Revocation List) on the client, since it allows the client | |
674 | to refuse all certificates except for those associated with designated | |
675 | servers. | |
676 | ||
677 | *NOTE:* | |
678 | Test against a name prefix only when you are using OpenVPN | |
679 | with a custom CA certificate that is under your control. Never use | |
680 | this option with type :code:`name-prefix` when your client | |
681 | certificates are signed by a third party, such as a commercial | |
682 | web CA. | |
683 | ||
684 | --x509-track attribute | |
685 | Save peer X509 **attribute** value in environment for use by plugins and | |
686 | management interface. Prepend a :code:`+` to ``attribute`` to save values | |
687 | from full cert chain. Values will be encoded as | |
688 | :code:`X509_<depth>_<attribute>=<value>`. Multiple ``--x509-track`` | |
689 | options can be defined to track multiple attributes. | |
690 | ||
691 | --x509-username-field args | |
3b04c34d VG |
692 | Fields in the X.509 certificate subject to be used as the username |
693 | (default :code:`CN`). If multiple fields are specified their values | |
694 | will be concatenated into the one username using :code:`_` symbol | |
695 | as a separator. | |
f500c49c DS |
696 | |
697 | Valid syntax: | |
698 | :: | |
699 | ||
3b04c34d | 700 | x509-username-field [ext:]fieldname [[ext:]fieldname...] |
f500c49c | 701 | |
3b04c34d | 702 | Typically, this option is specified with **fieldname** arguments as |
f500c49c DS |
703 | either of the following: |
704 | :: | |
705 | ||
706 | x509-username-field emailAddress | |
707 | x509-username-field ext:subjectAltName | |
3b04c34d | 708 | x509-username-field CN serialNumber |
f500c49c DS |
709 | |
710 | The first example uses the value of the :code:`emailAddress` attribute | |
711 | in the certificate's Subject field as the username. The second example | |
712 | uses the :code:`ext:` prefix to signify that the X.509 extension | |
713 | ``fieldname`` :code:`subjectAltName` be searched for an rfc822Name | |
714 | (email) field to be used as the username. In cases where there are | |
715 | multiple email addresses in :code:`ext:fieldname`, the last occurrence | |
3b04c34d VG |
716 | is chosen. The last example uses the value of the :code:`CN` attribute |
717 | in the Subject field, combined with the :code:`_` separator and the | |
718 | hexadecimal representation of the certificate's :code:`serialNumber`. | |
f500c49c DS |
719 | |
720 | When this option is used, the ``--verify-x509-name`` option will match | |
721 | against the chosen ``fieldname`` instead of the Common Name. | |
722 | ||
723 | Only the :code:`subjectAltName` and :code:`issuerAltName` X.509 | |
3b04c34d | 724 | extensions and :code:`serialNumber` X.509 attribute are supported. |
f500c49c DS |
725 | |
726 | **Please note:** This option has a feature which will convert an | |
727 | all-lowercase ``fieldname`` to uppercase characters, e.g., | |
728 | :code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the | |
729 | :code:`ext:` prefix will be left as-is. This automatic upcasing feature is | |
730 | deprecated and will be removed in a future release. | |
3b04c34d VG |
731 | |
732 | Non-compliant symbols are being replaced with the :code:`_` symbol, same as | |
733 | the field separator, so concatenating multiple fields with such or :code:`_` | |
734 | symbols can potentially lead to username collisions. |