]>
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 | ||
392da5bd AS |
298 | The optional ``direction`` parameter enables the use of 2 distinct keys |
299 | (HMAC-send, HMAC-receive), so that each | |
300 | data flow direction has a different HMAC key. This has a number of desirable | |
301 | security properties including eliminating certain kinds of DoS and message | |
302 | replay attacks. | |
303 | ||
304 | When the ``direction`` parameter is omitted, the same key is used | |
305 | bidirectionally. | |
306 | ||
307 | The ``direction`` parameter should always be complementary on either | |
308 | side of the connection, i.e. one side should use :code:`0` and the other | |
309 | should use :code:`1`, or both sides should omit it altogether. | |
310 | ||
311 | The ``direction`` parameter requires that ``file`` contains a 2048 bit | |
312 | key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any | |
313 | version of OpenVPN which supports the ``direction`` parameter, will also | |
314 | support 2048 bit key file generation using the ``--genkey`` option. | |
315 | ||
f500c49c DS |
316 | |
317 | ``--tls-auth`` is recommended when you are running OpenVPN in a mode | |
318 | where it is listening for packets from any IP address, such as when | |
319 | ``--remote`` is not specified, or ``--remote`` is specified with | |
320 | ``--float``. | |
321 | ||
322 | The rationale for this feature is as follows. TLS requires a | |
323 | multi-packet exchange before it is able to authenticate a peer. During | |
324 | this time before authentication, OpenVPN is allocating resources (memory | |
325 | and CPU) to this potential peer. The potential peer is also exposing | |
326 | many parts of OpenVPN and the OpenSSL library to the packets it is | |
327 | sending. Most successful network attacks today seek to either exploit | |
328 | bugs in programs (such as buffer overflow attacks) or force a program to | |
329 | consume so many resources that it becomes unusable. Of course the first | |
330 | line of defense is always to produce clean, well-audited code. OpenVPN | |
331 | has been written with buffer overflow attack prevention as a top | |
332 | priority. But as history has shown, many of the most widely used network | |
333 | applications have, from time to time, fallen to buffer overflow attacks. | |
334 | ||
335 | So as a second line of defense, OpenVPN offers this special layer of | |
336 | authentication on top of the TLS control channel so that every packet on | |
337 | the control channel is authenticated by an HMAC signature and a unique | |
338 | ID for replay protection. This signature will also help protect against | |
339 | DoS (Denial of Service) attacks. An important rule of thumb in reducing | |
340 | vulnerability to DoS attacks is to minimize the amount of resources a | |
341 | potential, but as yet unauthenticated, client is able to consume. | |
342 | ||
343 | ``--tls-auth`` does this by signing every TLS control channel packet | |
344 | with an HMAC signature, including packets which are sent before the TLS | |
345 | level has had a chance to authenticate the peer. The result is that | |
346 | packets without the correct signature can be dropped immediately upon | |
347 | reception, before they have a chance to consume additional system | |
348 | resources such as by initiating a TLS handshake. ``--tls-auth`` can be | |
349 | strengthened by adding the ``--replay-persist`` option which will keep | |
350 | OpenVPN's replay protection state in a file so that it is not lost | |
351 | across restarts. | |
352 | ||
353 | It should be emphasized that this feature is optional and that the key | |
354 | file used with ``--tls-auth`` gives a peer nothing more than the power | |
355 | to initiate a TLS handshake. It is not used to encrypt or authenticate | |
356 | any tunnel data. | |
357 | ||
358 | Use ``--tls-crypt`` instead if you want to use the key file to not only | |
359 | authenticate, but also encrypt the TLS control channel. | |
360 | ||
8353ae80 AS |
361 | --tls-groups list |
362 | A list of allowable groups/curves in order of preference. | |
363 | ||
364 | Set the allowed elliptic curves/groups for the TLS session. | |
365 | These groups are allowed to be used in signatures and key exchange. | |
366 | ||
367 | mbedTLS currently allows all known curves per default. | |
368 | ||
369 | OpenSSL 1.1+ restricts the list per default to | |
370 | :: | |
371 | ||
372 | "X25519:secp256r1:X448:secp521r1:secp384r1". | |
373 | ||
374 | If you use certificates that use non-standard curves, you | |
375 | might need to add them here. If you do not force the ecdh curve | |
376 | by using ``--ecdh-curve``, the groups for ecdh will also be picked | |
377 | from this list. | |
378 | ||
379 | OpenVPN maps the curve name `secp256r1` to `prime256v1` to allow | |
380 | specifying the same tls-groups option for mbedTLS and OpenSSL. | |
381 | ||
382 | Warning: this option not only affects elliptic curve certificates | |
383 | but also the key exchange in TLS 1.3 and using this option improperly | |
384 | will disable TLS 1.3. | |
385 | ||
f500c49c DS |
386 | --tls-cert-profile profile |
387 | Set the allowed cryptographic algorithms for certificates according to | |
388 | ``profile``. | |
389 | ||
390 | The following profiles are supported: | |
391 | ||
23efeb7a AS |
392 | :code:`insecure` |
393 | Identical for mbed TLS to `legacy` | |
394 | ||
f500c49c DS |
395 | :code:`legacy` (default) |
396 | SHA1 and newer, RSA 2048-bit+, any elliptic curve. | |
397 | ||
398 | :code:`preferred` | |
399 | SHA2 and newer, RSA 2048-bit+, any elliptic curve. | |
400 | ||
401 | :code:`suiteb` | |
402 | SHA256/SHA384, ECDSA with P-256 or P-384. | |
403 | ||
404 | This option is only fully supported for mbed TLS builds. OpenSSL builds | |
405 | use the following approximation: | |
406 | ||
23efeb7a AS |
407 | :code:`insecure` |
408 | sets "security level 0" | |
409 | ||
f500c49c DS |
410 | :code:`legacy` (default) |
411 | sets "security level 1" | |
412 | ||
413 | :code:`preferred` | |
414 | sets "security level 2" | |
415 | ||
416 | :code:`suiteb` | |
417 | sets "security level 3" and ``--tls-cipher "SUITEB128"``. | |
418 | ||
419 | OpenVPN will migrate to 'preferred' as default in the future. Please | |
420 | ensure that your keys already comply. | |
421 | ||
8353ae80 | 422 | *WARNING:* ``--tls-ciphers``, ``--tls-ciphersuites`` and ``tls-groups`` |
f500c49c DS |
423 | These options are expert features, which - if used correctly - can |
424 | improve the security of your VPN connection. But it is also easy to | |
425 | unwittingly use them to carefully align a gun with your foot, or just | |
426 | break your connection. Use with care! | |
427 | ||
428 | --tls-cipher l | |
429 | A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`"). | |
430 | ||
431 | These setting can be used to ensure that certain cipher suites are used | |
432 | (or not used) for the TLS connection. OpenVPN uses TLS to secure the | |
433 | control channel, over which the keys that are used to protect the actual | |
434 | VPN traffic are exchanged. | |
435 | ||
436 | The supplied list of ciphers is (after potential OpenSSL/IANA name | |
437 | translation) simply supplied to the crypto library. Please see the | |
438 | OpenSSL and/or mbed TLS documentation for details on the cipher list | |
439 | interpretation. | |
440 | ||
441 | For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below. | |
442 | ||
443 | Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto | |
444 | library. | |
445 | ||
446 | The default for ``--tls-cipher`` is to use mbed TLS's default cipher list | |
447 | when using mbed TLS or | |
448 | :code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when | |
449 | using OpenSSL. | |
450 | ||
f500c49c DS |
451 | --tls-ciphersuites l |
452 | Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no | |
453 | TLS 1.3 support yet and only the ``--tls-cipher`` setting is used. | |
454 | ||
3b1ded39 RB |
455 | The default for `--tls-ciphersuites` is to use the crypto library's |
456 | default. | |
457 | ||
f500c49c DS |
458 | --tls-client |
459 | Enable TLS and assume client role during TLS handshake. | |
460 | ||
461 | --tls-crypt keyfile | |
462 | Encrypt and authenticate all control channel packets with the key from | |
463 | ``keyfile``. (See ``--tls-auth`` for more background.) | |
464 | ||
465 | Encrypting (and authenticating) control channel packets: | |
466 | ||
467 | * provides more privacy by hiding the certificate used for the TLS | |
468 | connection, | |
469 | ||
470 | * makes it harder to identify OpenVPN traffic as such, | |
471 | ||
472 | * provides "poor-man's" post-quantum security, against attackers who will | |
473 | never know the pre-shared key (i.e. no forward secrecy). | |
474 | ||
475 | In contrast to ``--tls-auth``, ``--tls-crypt`` does *not* require the | |
476 | user to set ``--key-direction``. | |
477 | ||
478 | **Security Considerations** | |
479 | ||
480 | All peers use the same ``--tls-crypt`` pre-shared group key to | |
481 | authenticate and encrypt control channel messages. To ensure that IV | |
482 | collisions remain unlikely, this key should not be used to encrypt more | |
483 | than 2^48 client-to-server or 2^48 server-to-client control channel | |
484 | messages. A typical initial negotiation is about 10 packets in each | |
485 | direction. Assuming both initial negotiation and renegotiations are at | |
486 | most 2^16 (65536) packets (to be conservative), and (re)negotiations | |
487 | happen each minute for each user (24/7), this limits the tls-crypt key | |
488 | lifetime to 8171 years divided by the number of users. So a setup with | |
489 | 1000 users should rotate the key at least once each eight years. (And a | |
490 | setup with 8000 users each year.) | |
491 | ||
492 | If IV collisions were to occur, this could result in the security of | |
493 | ``--tls-crypt`` degrading to the same security as using ``--tls-auth``. | |
494 | That is, the control channel still benefits from the extra protection | |
495 | against active man-in-the-middle-attacks and DoS attacks, but may no | |
496 | longer offer extra privacy and post-quantum security on top of what TLS | |
497 | itself offers. | |
498 | ||
499 | For large setups or setups where clients are not trusted, consider using | |
500 | ``--tls-crypt-v2`` instead. That uses per-client unique keys, and | |
501 | thereby improves the bounds to 'rotate a client key at least once per | |
502 | 8000 years'. | |
503 | ||
504 | --tls-crypt-v2 keyfile | |
e7d8c4a7 | 505 | |
ceeb37a6 HH |
506 | Valid syntax:: |
507 | ||
e7d8c4a7 AS |
508 | tls-crypt-v2 keyfile |
509 | tls-crypt-v2 keyfile force-cookie | |
510 | tls-crypt-v2 keyfile allow-noncookie | |
511 | ||
f500c49c DS |
512 | Use client-specific tls-crypt keys. |
513 | ||
514 | For clients, ``keyfile`` is a client-specific tls-crypt key. Such a key | |
515 | can be generated using the :code:`--genkey tls-crypt-v2-client` option. | |
516 | ||
517 | For servers, ``keyfile`` is used to unwrap client-specific keys supplied | |
518 | by the client during connection setup. This key must be the same as the | |
519 | key used to generate the client-specific key (see :code:`--genkey | |
520 | tls-crypt-v2-client`). | |
521 | ||
522 | On servers, this option can be used together with the ``--tls-auth`` or | |
523 | ``--tls-crypt`` option. In that case, the server will detect whether the | |
524 | client is using client-specific keys, and automatically select the right | |
525 | mode. | |
526 | ||
e7d8c4a7 AS |
527 | The optional parameters :code:`force-cookie` allows only tls-crypt-v2 |
528 | clients that support a cookie based stateless three way handshake that | |
529 | avoids replay attacks and state exhaustion on the server side (OpenVPN | |
530 | 2.6 and later). The option :code:`allow-noncookie` explicitly allows | |
531 | older tls-crypt-v2 clients. The default is (currently) | |
532 | :code:`allow-noncookie`. | |
533 | ||
f500c49c DS |
534 | --tls-crypt-v2-verify cmd |
535 | Run command ``cmd`` to verify the metadata of the client-specific | |
536 | tls-crypt-v2 key of a connecting client. This allows server | |
537 | administrators to reject client connections, before exposing the TLS | |
538 | stack (including the notoriously dangerous X.509 and ASN.1 stacks) to | |
539 | the connecting client. | |
540 | ||
541 | OpenVPN supplies the following environment variables to the command: | |
542 | ||
543 | * :code:`script_type` is set to :code:`tls-crypt-v2-verify` | |
544 | ||
545 | * :code:`metadata_type` is set to :code:`0` if the metadata was user | |
546 | supplied, or :code:`1` if it's a 64-bit unix timestamp representing | |
547 | the key creation time. | |
548 | ||
549 | * :code:`metadata_file` contains the filename of a temporary file that | |
550 | contains the client metadata. | |
551 | ||
552 | The command can reject the connection by exiting with a non-zero exit | |
553 | code. | |
554 | ||
555 | --tls-exit | |
ee6417e9 AS |
556 | Exit on TLS negotiation failure. This option can be useful when you only |
557 | want to make one attempt at connecting, e.g. in a test or monitoring script. | |
558 | (OpenVPN's own test suite uses it this way.) | |
f500c49c DS |
559 | |
560 | --tls-export-cert directory | |
561 | Store the certificates the clients use upon connection to this | |
562 | directory. This will be done before ``--tls-verify`` is called. The | |
563 | certificates will use a temporary name and will be deleted when the | |
564 | tls-verify script returns. The file name used for the certificate is | |
565 | available via the ``peer_cert`` environment variable. | |
566 | ||
567 | --tls-server | |
568 | Enable TLS and assume server role during TLS handshake. Note that | |
569 | OpenVPN is designed as a peer-to-peer application. The designation of | |
570 | client or server is only for the purpose of negotiating the TLS control | |
571 | channel. | |
572 | ||
573 | --tls-timeout n | |
574 | Packet retransmit timeout on TLS control channel if no acknowledgment | |
575 | from remote within ``n`` seconds (default :code:`2`). When OpenVPN sends | |
576 | a control packet to its peer, it will expect to receive an | |
577 | acknowledgement within ``n`` seconds or it will retransmit the packet, | |
578 | subject to a TCP-like exponential backoff algorithm. This parameter only | |
579 | applies to control channel packets. Data channel packets (which carry | |
580 | encrypted tunnel data) are never acknowledged, sequenced, or | |
581 | retransmitted by OpenVPN because the higher level network protocols | |
582 | running on top of the tunnel such as TCP expect this role to be left to | |
583 | them. | |
584 | ||
585 | --tls-version-min args | |
968569f8 AQ |
586 | Sets the minimum TLS version we will accept from the peer (default in |
587 | 2.6.0 and later is "1.2"). | |
f500c49c DS |
588 | |
589 | Valid syntax: | |
590 | :: | |
591 | ||
592 | tls-version-min version ['or-highest'] | |
593 | ||
594 | Examples for version include :code:`1.0`, :code:`1.1`, or :code:`1.2`. If | |
595 | :code:`or-highest` is specified and version is not recognized, we will | |
596 | only accept the highest TLS version supported by the local SSL | |
597 | implementation. | |
598 | ||
599 | --tls-version-max version | |
600 | Set the maximum TLS version we will use (default is the highest version | |
601 | supported). Examples for version include :code:`1.0`, :code:`1.1`, or | |
602 | :code:`1.2`. | |
603 | ||
604 | --verify-hash args | |
5b8a1231 | 605 | **DEPRECATED** Specify SHA1 or SHA256 fingerprint for level-1 cert. |
f500c49c DS |
606 | |
607 | Valid syntax: | |
608 | :: | |
609 | ||
610 | verify-hash hash [algo] | |
611 | ||
612 | The level-1 cert is the CA (or intermediate cert) that signs the leaf | |
613 | certificate, and is one removed from the leaf certificate in the | |
614 | direction of the root. When accepting a connection from a peer, the | |
615 | level-1 cert fingerprint must match ``hash`` or certificate verification | |
616 | will fail. Hash is specified as XX:XX:... For example: | |
617 | :: | |
618 | ||
619 | AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16 | |
620 | ||
621 | The ``algo`` flag can be either :code:`SHA1` or :code:`SHA256`. If not | |
622 | provided, it defaults to :code:`SHA1`. | |
623 | ||
d1fe6d52 AS |
624 | This option can also be inlined |
625 | :: | |
626 | ||
627 | <verify-hash> | |
628 | 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 | |
629 | 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 | |
630 | </verify-hash> | |
631 | ||
632 | If the option is inlined, ``algo`` is always :code:`SHA256`. | |
633 | ||
c3a7065d AS |
634 | --peer-fingerprint args |
635 | Specify a SHA256 fingerprint or list of SHA256 fingerprints to verify | |
636 | the peer certificate against. The peer certificate must match one of the | |
637 | fingerprint or certificate verification will fail. The option can also | |
638 | be inlined | |
639 | ||
640 | Valid syntax: | |
641 | :: | |
642 | ||
643 | peer-fingerprint AD:B0:95:D8:09:... | |
644 | ||
645 | or inline: | |
646 | :: | |
647 | ||
648 | <peer-fingerprint> | |
649 | 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 | |
650 | 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 | |
651 | </peer-fingerprint> | |
652 | ||
26117a82 AS |
653 | When the ``--peer-fingerprint`` option is used, specifying a CA with ``--ca`` or ``--capath`` is |
654 | optional. This allows the he ``--peer-fingerprint`` to be used as alternative to a PKI with | |
655 | self-signed certificates for small setups. See the examples section for such a setup. | |
656 | ||
f500c49c DS |
657 | --verify-x509-name args |
658 | Accept connections only if a host's X.509 name is equal to **name.** The | |
659 | remote host must also pass all other tests of verification. | |
660 | ||
661 | Valid syntax: | |
662 | :: | |
663 | ||
664 | verify-x509 name type | |
665 | ||
666 | Which X.509 name is compared to ``name`` depends on the setting of type. | |
667 | ``type`` can be :code:`subject` to match the complete subject DN | |
668 | (default), :code:`name` to match a subject RDN or :code:`name-prefix` to | |
669 | match a subject RDN prefix. Which RDN is verified as name depends on the | |
670 | ``--x509-username-field`` option. But it defaults to the common name | |
671 | (CN), e.g. a certificate with a subject DN | |
672 | :: | |
673 | ||
674 | C=KG, ST=NA, L=Bishkek, CN=Server-1 | |
675 | ||
676 | would be matched by: | |
677 | :: | |
678 | ||
679 | verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' | |
680 | verify-x509-name Server-1 name | |
681 | verify-x509-name Server- name-prefix | |
682 | ||
683 | The last example is useful if you want a client to only accept | |
684 | connections to :code:`Server-1`, :code:`Server-2`, etc. | |
685 | ||
686 | ``--verify-x509-name`` is a useful replacement for the ``--tls-verify`` | |
687 | option to verify the remote host, because ``--verify-x509-name`` works | |
688 | in a ``--chroot`` environment without any dependencies. | |
689 | ||
690 | Using a name prefix is a useful alternative to managing a CRL | |
691 | (Certificate Revocation List) on the client, since it allows the client | |
692 | to refuse all certificates except for those associated with designated | |
693 | servers. | |
694 | ||
695 | *NOTE:* | |
696 | Test against a name prefix only when you are using OpenVPN | |
697 | with a custom CA certificate that is under your control. Never use | |
698 | this option with type :code:`name-prefix` when your client | |
699 | certificates are signed by a third party, such as a commercial | |
700 | web CA. | |
701 | ||
702 | --x509-track attribute | |
703 | Save peer X509 **attribute** value in environment for use by plugins and | |
704 | management interface. Prepend a :code:`+` to ``attribute`` to save values | |
705 | from full cert chain. Values will be encoded as | |
706 | :code:`X509_<depth>_<attribute>=<value>`. Multiple ``--x509-track`` | |
707 | options can be defined to track multiple attributes. | |
708 | ||
709 | --x509-username-field args | |
3b04c34d VG |
710 | Fields in the X.509 certificate subject to be used as the username |
711 | (default :code:`CN`). If multiple fields are specified their values | |
712 | will be concatenated into the one username using :code:`_` symbol | |
713 | as a separator. | |
f500c49c DS |
714 | |
715 | Valid syntax: | |
716 | :: | |
717 | ||
3b04c34d | 718 | x509-username-field [ext:]fieldname [[ext:]fieldname...] |
f500c49c | 719 | |
3b04c34d | 720 | Typically, this option is specified with **fieldname** arguments as |
f500c49c DS |
721 | either of the following: |
722 | :: | |
723 | ||
724 | x509-username-field emailAddress | |
725 | x509-username-field ext:subjectAltName | |
3b04c34d | 726 | x509-username-field CN serialNumber |
f500c49c DS |
727 | |
728 | The first example uses the value of the :code:`emailAddress` attribute | |
729 | in the certificate's Subject field as the username. The second example | |
730 | uses the :code:`ext:` prefix to signify that the X.509 extension | |
731 | ``fieldname`` :code:`subjectAltName` be searched for an rfc822Name | |
732 | (email) field to be used as the username. In cases where there are | |
733 | multiple email addresses in :code:`ext:fieldname`, the last occurrence | |
3b04c34d VG |
734 | is chosen. The last example uses the value of the :code:`CN` attribute |
735 | in the Subject field, combined with the :code:`_` separator and the | |
736 | hexadecimal representation of the certificate's :code:`serialNumber`. | |
f500c49c DS |
737 | |
738 | When this option is used, the ``--verify-x509-name`` option will match | |
739 | against the chosen ``fieldname`` instead of the Common Name. | |
740 | ||
741 | Only the :code:`subjectAltName` and :code:`issuerAltName` X.509 | |
3b04c34d | 742 | extensions and :code:`serialNumber` X.509 attribute are supported. |
f500c49c DS |
743 | |
744 | **Please note:** This option has a feature which will convert an | |
745 | all-lowercase ``fieldname`` to uppercase characters, e.g., | |
746 | :code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the | |
747 | :code:`ext:` prefix will be left as-is. This automatic upcasing feature is | |
748 | deprecated and will be removed in a future release. | |
3b04c34d VG |
749 | |
750 | Non-compliant symbols are being replaced with the :code:`_` symbol, same as | |
751 | the field separator, so concatenating multiple fields with such or :code:`_` | |
752 | symbols can potentially lead to username collisions. |