path: root/doc/man-sections/tls-options.rst

TLS Mode Options
----------------

TLS mode is the most powerful crypto mode of OpenVPN in both security
and flexibility. TLS mode works by establishing control and data
channels which are multiplexed over a single TCP/UDP port. OpenVPN
initiates a TLS session over the control channel and uses it to exchange
cipher and HMAC keys to protect the data channel. TLS mode uses a robust
reliability layer over the UDP connection for all control channel
communication, while the data channel, over which encrypted tunnel data
passes, is forwarded without any mediation. The result is the best of
both worlds: a fast data channel that forwards over UDP with only the
overhead of encrypt, decrypt, and HMAC functions, and a control channel
that provides all of the security features of TLS, including
certificate-based authentication and Diffie Hellman forward secrecy.

To use TLS mode, each peer that runs OpenVPN should have its own local
certificate/key pair (``--cert`` and ``--key``), signed by the root
certificate which is specified in ``--ca``.

When two OpenVPN peers connect, each presents its local certificate to
the other. Each peer will then check that its partner peer presented a
certificate which was signed by the master root certificate as specified
in ``--ca``.

If that check on both peers succeeds, then the TLS negotiation will
succeed, both OpenVPN peers will exchange temporary session keys, and
the tunnel will begin passing data.

The OpenVPN project provides a set of scripts for managing RSA
certificates and keys: https://github.com/OpenVPN/easy-rsa

--askpass file
  Get certificate password from console or ``file`` before we daemonize.

  Valid syntaxes:
  ::

     askpass
     askpass file

  For the extremely security conscious, it is possible to protect your
  private key with a password. Of course this means that every time the
  OpenVPN daemon is started you must be there to type the password. The
  ``--askpass`` option allows you to start OpenVPN from the command line.
  It will query you for a password before it daemonizes. To protect a
  private key with a password you should omit the ``-nodes`` option when
  you use the ``openssl`` command line tool to manage certificates and
  private keys.

  If ``file`` is specified, read the password from the first line of
  ``file``. Keep in mind that storing your password in a file to a certain
  extent invalidates the extra security provided by using an encrypted
  key.

--ca file
  Certificate authority (CA) file in .pem format, also referred to as the
  *root* certificate. This file can have multiple certificates in .pem
  format, concatenated together. You can construct your own certificate
  authority certificate and private key by using a command such as:
  ::

     openssl req -nodes -new -x509 -keyout ca.key -out ca.crt

  Then edit your openssl.cnf file and edit the ``certificate`` variable to
  point to your new root certificate ``ca.crt``.

  For testing purposes only, the OpenVPN distribution includes a sample CA
  certificate (ca.crt). Of course you should never use the test
  certificates and test keys distributed with OpenVPN in a production
  environment, since by virtue of the fact that they are distributed with
  OpenVPN, they are totally insecure.

--capath dir
  Directory containing trusted certificates (CAs and CRLs). Not available
  with mbed TLS.

  CAs in the capath directory are expected to be named <hash>.<n>. CRLs
  are expected to be named <hash>.r<n>. See the ``-CApath`` option of
  ``openssl verify``, and the ``-hash`` option of ``openssl x509``,
  ``openssl crl`` and ``X509_LOOKUP_hash_dir()``\(3)
  for more information.

  Similar to the ``--crl-verify`` option, CRLs are not mandatory -
  OpenVPN will log the usual warning in the logs if the relevant CRL is
  missing, but the connection will be allowed.

--cert file
  Local peer's signed certificate in .pem format -- must be signed by a
  certificate authority whose certificate is in ``--ca file``. Each peer
  in an OpenVPN link running in TLS mode should have its own certificate
  and private key file. In addition, each certificate should have been
  signed by the key of a certificate authority whose public key resides in
  the ``--ca`` certificate authority file. You can easily make your own
  certificate authority (see above) or pay money to use a commercial
  service such as thawte.com (in which case you will be helping to finance
  the world's second space tourist :). To generate a certificate, you can
  use a command such as:
  ::

     openssl req -nodes -new -keyout mycert.key -out mycert.csr

  If your certificate authority private key lives on another machine, copy
  the certificate signing request (mycert.csr) to this other machine (this
  can be done over an insecure channel such as email). Now sign the
  certificate with a command such as:
  ::

     openssl ca -out mycert.crt -in mycert.csr

  Now copy the certificate (mycert.crt) back to the peer which initially
  generated the .csr file (this can be over a public medium). Note that
  the ``openssl ca`` command reads the location of the certificate
  authority key from its configuration file such as
  :code:`/usr/share/ssl/openssl.cnf` -- note also that for certificate
  authority functions, you must set up the files :code:`index.txt` (may be
  empty) and :code:`serial` (initialize to :code:`01`).

--crl-verify args
  Check peer certificate against a Certificate Revocation List.

  Valid syntax:
  ::

     crl-verify file/directory flag

  Examples:
  ::

     crl-verify crl-file.pem
     crl-verify /etc/openvpn/crls dir

  A CRL (certificate revocation list) is used when a particular key is
  compromised but when the overall PKI is still intact.

  Suppose you had a PKI consisting of a CA, root certificate, and a number
  of client certificates. Suppose a laptop computer containing a client
  key and certificate was stolen. By adding the stolen certificate to the
  CRL file, you could reject any connection which attempts to use it,
  while preserving the overall integrity of the PKI.

  The only time when it would be necessary to rebuild the entire PKI from
  scratch would be if the root certificate key itself was compromised.

  The option is not mandatory - if the relevant CRL is missing, OpenVPN
  will log a warning in the logs - e.g.
  ::

     VERIFY WARNING: depth=0, unable to get certificate CRL

  but the connection will be allowed.  If the optional :code:`dir` flag
  is specified, enable a different mode where the ``crl-verify`` is
  pointed at a directory containing files named as revoked serial numbers
  (the files may be empty, the contents are never read). If a client
  requests a connection, where the client certificate serial number
  (decimal string) is the name of a file present in the directory, it will
  be rejected.

  *Note:*
            As the crl file (or directory) is read every time a peer
            connects, if you are dropping root privileges with
            ``--user``, make sure that this user has sufficient
            privileges to read the file.


--dh file
  File containing Diffie Hellman parameters in .pem format (required for
  ``--tls-server`` only).

  Set ``file`` to :code:`none` to disable Diffie Hellman key exchange (and
  use ECDH only). Note that this requires peers to be using an SSL library
  that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
  mbed TLS 2.0+).

  Use ``openssl dhparam -out dh2048.pem 2048`` to generate 2048-bit DH
  parameters. Diffie Hellman parameters may be considered public.

--ecdh-curve name
  Specify the curve to use for elliptic curve Diffie Hellman. Available
  curves can be listed with ``--show-curves``. The specified curve will
  only be used for ECDH TLS-ciphers.

  This option is not supported in mbed TLS builds of OpenVPN.

--extra-certs file
  Specify a ``file`` containing one or more PEM certs (concatenated
  together) that complete the local certificate chain.

  This option is useful for "split" CAs, where the CA for server certs is
  different than the CA for client certs. Putting certs in this file
  allows them to be used to complete the local certificate chain without
  trusting them to verify the peer-submitted certificate, as would be the
  case if the certs were placed in the ``ca`` file.

--hand-window n
  Handshake Window -- the TLS-based key exchange must finalize within
  ``n`` seconds of handshake initiation by any peer (default :code:`60`
  seconds). If the handshake fails we will attempt to reset our connection
  with our peer and try again. Even in the event of handshake failure we
  will still use our expiring key for up to ``--tran-window`` seconds to
  maintain continuity of transmission of tunnel data.

--key file
  Local peer's private key in .pem format. Use the private key which was
  generated when you built your peer's certificate (see ``--cert file``
  above).

--pkcs12 file
  Specify a PKCS #12 file containing local private key, local certificate,
  and root CA certificate. This option can be used instead of ``--ca``,
  ``--cert``, and ``--key``.  Not available with mbed TLS.

--remote-cert-eku oid
  Require that peer certificate was signed with an explicit *extended key
  usage*.

  This is a useful security option for clients, to ensure that the host
  they connect to is a designated server.

  The extended key usage should be encoded in *oid notation*, or *OpenSSL
  symbolic representation*.

--remote-cert-ku key-usage
  Require that peer certificate was signed with an explicit
  ``key-usage``.

  If present in the certificate, the :code:`keyUsage` value is validated by
  the TLS library during the TLS handshake. Specifying this option without
  arguments requires this extension to be present (so the TLS library will
  verify it).

  If ``key-usage`` is a list of usage bits, the :code:`keyUsage` field
  must have *at least* the same bits set as the bits in *one of* the values
  supplied in the ``key-usage`` list.

  The ``key-usage`` values in the list must be encoded in hex, e.g.
  ::

     remote-cert-ku a0

--remote-cert-tls type
  Require that peer certificate was signed with an explicit *key usage*
  and *extended key usage* based on RFC3280 TLS rules.

  Valid syntaxes:
  ::

     remote-cert-tls server
     remote-cert-tls client

  This is a useful security option for clients, to ensure that the host
  they connect to is a designated server. Or the other way around; for a
  server to verify that only hosts with a client certificate can connect.

  The ``--remote-cert-tls client`` option is equivalent to
  ::

     remote-cert-ku
     remote-cert-eku "TLS Web Client Authentication"

  The ``--remote-cert-tls server`` option is equivalent to
  ::

     remote-cert-ku
     remote-cert-eku "TLS Web Server Authentication"

  This is an important security precaution to protect against a
  man-in-the-middle attack where an authorized client attempts to connect
  to another client by impersonating the server. The attack is easily
  prevented by having clients verify the server certificate using any one
  of ``--remote-cert-tls``, ``--verify-x509-name``, or ``--tls-verify``.

--tls-auth args
  Add an additional layer of HMAC authentication on top of the TLS control
  channel to mitigate DoS attacks and attacks on the TLS stack.

  Valid syntaxes:
  ::

     tls-auth file
     tls-auth file 0
     tls-auth file 1

  In a nutshell, ``--tls-auth`` enables a kind of "HMAC firewall" on
  OpenVPN's TCP/UDP port, where TLS control channel packets bearing an
  incorrect HMAC signature can be dropped immediately without response.

  ``file`` (required) is a file in OpenVPN static key format which can be
  generated by ``--genkey``.

  Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
  This is no longer supported in newer versions (v2.4+).

  See the ``--secret`` option for more information on the optional
  ``direction`` parameter.

  ``--tls-auth`` is recommended when you are running OpenVPN in a mode
  where it is listening for packets from any IP address, such as when
  ``--remote`` is not specified, or ``--remote`` is specified with
  ``--float``.

  The rationale for this feature is as follows. TLS requires a
  multi-packet exchange before it is able to authenticate a peer. During
  this time before authentication, OpenVPN is allocating resources (memory
  and CPU) to this potential peer. The potential peer is also exposing
  many parts of OpenVPN and the OpenSSL library to the packets it is
  sending. Most successful network attacks today seek to either exploit
  bugs in programs (such as buffer overflow attacks) or force a program to
  consume so many resources that it becomes unusable. Of course the first
  line of defense is always to produce clean, well-audited code. OpenVPN
  has been written with buffer overflow attack prevention as a top
  priority. But as history has shown, many of the most widely used network
  applications have, from time to time, fallen to buffer overflow attacks.

  So as a second line of defense, OpenVPN offers this special layer of
  authentication on top of the TLS control channel so that every packet on
  the control channel is authenticated by an HMAC signature and a unique
  ID for replay protection. This signature will also help protect against
  DoS (Denial of Service) attacks. An important rule of thumb in reducing
  vulnerability to DoS attacks is to minimize the amount of resources a
  potential, but as yet unauthenticated, client is able to consume.

  ``--tls-auth`` does this by signing every TLS control channel packet
  with an HMAC signature, including packets which are sent before the TLS
  level has had a chance to authenticate the peer. The result is that
  packets without the correct signature can be dropped immediately upon
  reception, before they have a chance to consume additional system
  resources such as by initiating a TLS handshake. ``--tls-auth`` can be
  strengthened by adding the ``--replay-persist`` option which will keep
  OpenVPN's replay protection state in a file so that it is not lost
  across restarts.

  It should be emphasized that this feature is optional and that the key
  file used with ``--tls-auth`` gives a peer nothing more than the power
  to initiate a TLS handshake. It is not used to encrypt or authenticate
  any tunnel data.

  Use ``--tls-crypt`` instead if you want to use the key file to not only
  authenticate, but also encrypt the TLS control channel.

--tls-groups list
    A list of allowable groups/curves in order of preference.

    Set the allowed elliptic curves/groups for the TLS session.
    These groups are allowed to be used in signatures and key exchange.

    mbedTLS currently allows all known curves per default.

    OpenSSL 1.1+ restricts the list per default to
    ::

      "X25519:secp256r1:X448:secp521r1:secp384r1".

    If you use certificates that use non-standard curves, you
    might need to add them here. If you do not force the ecdh curve
    by using ``--ecdh-curve``, the groups for ecdh will also be picked
    from this list.

    OpenVPN maps the curve name `secp256r1` to `prime256v1` to allow
    specifying the same tls-groups option for mbedTLS and OpenSSL.

    Warning: this option not only affects elliptic curve certificates
    but also the key exchange in TLS 1.3 and using this option improperly
    will disable TLS 1.3.

--tls-cert-profile profile
  Set the allowed cryptographic algorithms for certificates according to
  ``profile``.

  The following profiles are supported:

  :code:`legacy` (default)
      SHA1 and newer, RSA 2048-bit+, any elliptic curve.

  :code:`preferred`
      SHA2 and newer, RSA 2048-bit+, any elliptic curve.

  :code:`suiteb`
      SHA256/SHA384, ECDSA with P-256 or P-384.

  This option is only fully supported for mbed TLS builds. OpenSSL builds
  use the following approximation:

  :code:`legacy` (default)
      sets "security level 1"

  :code:`preferred`
      sets "security level 2"

  :code:`suiteb`
      sets "security level 3" and ``--tls-cipher "SUITEB128"``.

  OpenVPN will migrate to 'preferred' as default in the future. Please
  ensure that your keys already comply.

*WARNING:* ``--tls-ciphers``, ``--tls-ciphersuites`` and ``tls-groups``
    These options are expert features, which - if used correctly - can
    improve the security of your VPN connection. But it is also easy to
    unwittingly use them to carefully align a gun with your foot, or just
    break your connection. Use with care!

--tls-cipher l
  A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`").

  These setting can be used to ensure that certain cipher suites are used
  (or not used) for the TLS connection. OpenVPN uses TLS to secure the
  control channel, over which the keys that are used to protect the actual
  VPN traffic are exchanged.

  The supplied list of ciphers is (after potential OpenSSL/IANA name
  translation) simply supplied to the crypto library. Please see the
  OpenSSL and/or mbed TLS documentation for details on the cipher list
  interpretation.

  For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below.

  Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto
  library.

  The default for ``--tls-cipher`` is to use mbed TLS's default cipher list
  when using mbed TLS or
  :code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when
  using OpenSSL.

  The default for `--tls-ciphersuites` is to use the crypto library's
  default.

--tls-ciphersuites l
  Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no
  TLS 1.3 support yet and only the ``--tls-cipher`` setting is used.

--tls-client
  Enable TLS and assume client role during TLS handshake.

--tls-crypt keyfile
  Encrypt and authenticate all control channel packets with the key from
  ``keyfile``. (See ``--tls-auth`` for more background.)

  Encrypting (and authenticating) control channel packets:

  * provides more privacy by hiding the certificate used for the TLS
    connection,

  * makes it harder to identify OpenVPN traffic as such,

  * provides "poor-man's" post-quantum security, against attackers who will
    never know the pre-shared key (i.e. no forward secrecy).

  In contrast to ``--tls-auth``, ``--tls-crypt`` does *not* require the
  user to set ``--key-direction``.

  **Security Considerations**

  All peers use the same ``--tls-crypt`` pre-shared group key to
  authenticate and encrypt control channel messages. To ensure that IV
  collisions remain unlikely, this key should not be used to encrypt more
  than 2^48 client-to-server or 2^48 server-to-client control channel
  messages. A typical initial negotiation is about 10 packets in each
  direction. Assuming both initial negotiation and renegotiations are at
  most 2^16 (65536) packets (to be conservative), and (re)negotiations
  happen each minute for each user (24/7), this limits the tls-crypt key
  lifetime to 8171 years divided by the number of users. So a setup with
  1000 users should rotate the key at least once each eight years. (And a
  setup with 8000 users each year.)

  If IV collisions were to occur, this could result in the security of
  ``--tls-crypt`` degrading to the same security as using ``--tls-auth``.
  That is, the control channel still benefits from the extra protection
  against active man-in-the-middle-attacks and DoS attacks, but may no
  longer offer extra privacy and post-quantum security on top of what TLS
  itself offers.

  For large setups or setups where clients are not trusted, consider using
  ``--tls-crypt-v2`` instead. That uses per-client unique keys, and
  thereby improves the bounds to 'rotate a client key at least once per
  8000 years'.

--tls-crypt-v2 keyfile
  Use client-specific tls-crypt keys.

  For clients, ``keyfile`` is a client-specific tls-crypt key. Such a key
  can be generated using the :code:`--genkey tls-crypt-v2-client` option.

  For servers, ``keyfile`` is used to unwrap client-specific keys supplied
  by the client during connection setup. This key must be the same as the
  key used to generate the client-specific key (see :code:`--genkey
  tls-crypt-v2-client`).

  On servers, this option can be used together with the ``--tls-auth`` or
  ``--tls-crypt`` option. In that case, the server will detect whether the
  client is using client-specific keys, and automatically select the right
  mode.

--tls-crypt-v2-verify cmd
  Run command ``cmd`` to verify the metadata of the client-specific
  tls-crypt-v2 key of a connecting client. This allows server
  administrators to reject client connections, before exposing the TLS
  stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
  the connecting client.

  OpenVPN supplies the following environment variables to the command:

  * :code:`script_type` is set to :code:`tls-crypt-v2-verify`

  * :code:`metadata_type` is set to :code:`0` if the metadata was user
    supplied, or :code:`1` if it's a 64-bit unix timestamp representing
    the key creation time.

  * :code:`metadata_file` contains the filename of a temporary file that
    contains the client metadata.

  The command can reject the connection by exiting with a non-zero exit
  code.

--tls-exit
  Exit on TLS negotiation failure.

--tls-export-cert directory
  Store the certificates the clients use upon connection to this
  directory. This will be done before ``--tls-verify`` is called. The
  certificates will use a temporary name and will be deleted when the
  tls-verify script returns. The file name used for the certificate is
  available via the ``peer_cert`` environment variable.

--tls-server
  Enable TLS and assume server role during TLS handshake. Note that
  OpenVPN is designed as a peer-to-peer application. The designation of
  client or server is only for the purpose of negotiating the TLS control
  channel.

--tls-timeout n
  Packet retransmit timeout on TLS control channel if no acknowledgment
  from remote within ``n`` seconds (default :code:`2`). When OpenVPN sends
  a control packet to its peer, it will expect to receive an
  acknowledgement within ``n`` seconds or it will retransmit the packet,
  subject to a TCP-like exponential backoff algorithm. This parameter only
  applies to control channel packets. Data channel packets (which carry
  encrypted tunnel data) are never acknowledged, sequenced, or
  retransmitted by OpenVPN because the higher level network protocols
  running on top of the tunnel such as TCP expect this role to be left to
  them.

--tls-version-min args
  Sets the minimum TLS version we will accept from the peer (default is
  "1.0").

  Valid syntax:
  ::

     tls-version-min version ['or-highest']

  Examples for version include :code:`1.0`, :code:`1.1`, or :code:`1.2`. If
  :code:`or-highest` is specified and version is not recognized, we will
  only accept the highest TLS version supported by the local SSL
  implementation.

--tls-version-max version
  Set the maximum TLS version we will use (default is the highest version
  supported). Examples for version include :code:`1.0`, :code:`1.1`, or
  :code:`1.2`.

--verify-hash args
  Specify SHA1 or SHA256 fingerprint for level-1 cert.

  Valid syntax:
  ::

     verify-hash hash [algo]

  The level-1 cert is the CA (or intermediate cert) that signs the leaf
  certificate, and is one removed from the leaf certificate in the
  direction of the root. When accepting a connection from a peer, the
  level-1 cert fingerprint must match ``hash`` or certificate verification
  will fail. Hash is specified as XX:XX:... For example:
  ::

     AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16

  The ``algo`` flag can be either :code:`SHA1` or :code:`SHA256`. If not
  provided, it defaults to :code:`SHA1`.

--verify-x509-name args
  Accept connections only if a host's X.509 name is equal to **name.** The
  remote host must also pass all other tests of verification.

  Valid syntax:
  ::

     verify-x509 name type

  Which X.509 name is compared to ``name`` depends on the setting of type.
  ``type`` can be :code:`subject` to match the complete subject DN
  (default), :code:`name` to match a subject RDN or :code:`name-prefix` to
  match a subject RDN prefix. Which RDN is verified as name depends on the
  ``--x509-username-field`` option. But it defaults to the common name
  (CN), e.g. a certificate with a subject DN
  ::

     C=KG, ST=NA, L=Bishkek, CN=Server-1

  would be matched by:
  ::

     verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
     verify-x509-name Server-1 name
     verify-x509-name Server- name-prefix

  The last example is useful if you want a client to only accept
  connections to :code:`Server-1`, :code:`Server-2`, etc.

  ``--verify-x509-name`` is a useful replacement for the ``--tls-verify``
  option to verify the remote host, because ``--verify-x509-name`` works
  in a ``--chroot`` environment without any dependencies.

  Using a name prefix is a useful alternative to managing a CRL
  (Certificate Revocation List) on the client, since it allows the client
  to refuse all certificates except for those associated with designated
  servers.

  *NOTE:*
      Test against a name prefix only when you are using OpenVPN
      with a custom CA certificate that is under your control. Never use
      this option with type :code:`name-prefix` when your client
      certificates are signed by a third party, such as a commercial
      web CA.

--x509-track attribute
  Save peer X509 **attribute** value in environment for use by plugins and
  management interface. Prepend a :code:`+` to ``attribute`` to save values
  from full cert chain. Values will be encoded as
  :code:`X509_<depth>_<attribute>=<value>`. Multiple ``--x509-track``
  options can be defined to track multiple attributes.

--x509-username-field args
  Field in the X.509 certificate subject to be used as the username
  (default :code:`CN`).

  Valid syntax:
  ::

     x509-username-field [ext:]fieldname

  Typically, this option is specified with **fieldname** as
  either of the following:
  ::

     x509-username-field emailAddress
     x509-username-field ext:subjectAltName

  The first example uses the value of the :code:`emailAddress` attribute
  in the certificate's Subject field as the username. The second example
  uses the :code:`ext:` prefix to signify that the X.509 extension
  ``fieldname`` :code:`subjectAltName` be searched for an rfc822Name
  (email) field to be used as the username. In cases where there are
  multiple email addresses in :code:`ext:fieldname`, the last occurrence
  is chosen.

  When this option is used, the ``--verify-x509-name`` option will match
  against the chosen ``fieldname`` instead of the Common Name.

  Only the :code:`subjectAltName` and :code:`issuerAltName` X.509
  extensions are supported.

  **Please note:** This option has a feature which will convert an
  all-lowercase ``fieldname`` to uppercase characters, e.g.,
  :code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the
  :code:`ext:` prefix will be left as-is. This automatic upcasing feature is
  deprecated and will be removed in a future release.