Сети‎ > ‎VPN‎ > ‎Параметры OpenVPN‎ > ‎

TLS Mode

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 distribution contains a set of scripts for managing RSA certificates & keys, located in the easy-rsa subdirectory.

The easy-rsa package is also rendered in web form here: http://openvpn.net/easyrsa.html

--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-client
Enable TLS and assume client role during TLS handshake.
--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). Available with OpenSSL version >= 0.9.7 dev. Not available with PolarSSL.
--dh file
File containing Diffie Hellman parameters in .pem format (required for --tls-server only). Use

openssl dhparam -out dh1024.pem 1024

to generate your own, or use the existing dh1024.pem file included with the OpenVPN distribution. Diffie Hellman parameters may be considered public.

--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 /usr/share/ssl/openssl.cnf -- note also that for certificate authority functions, you must set up the files index.txt (may be empty) and serial (initialize to 01 ).

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

--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 PolarSSL.
--verify-hash hash
Specify SHA1 fingerprint for level-1 cert. 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
--pkcs11-cert-private [0|1]...
Set if access to certificate object should be performed after login. Every provider has its own setting.
--pkcs11-id name
Specify the serialized certificate id to be used. The id can be gotten by the standalone --show-pkcs11-ids option.
--pkcs11-id-management
Acquire PKCS#11 id from management interface. In this case a NEED-STR 'pkcs11-id-request' real-time message will be triggered, application may use pkcs11-id-count command to retrieve available number of certificates, and pkcs11-id-get command to retrieve certificate id and certificate body.
--pkcs11-pin-cache seconds
Specify how many seconds the PIN can be cached, the default is until the token is removed.
--pkcs11-protected-authentication [0|1]...
Use PKCS#11 protected authentication path, useful for biometric and external keypad devices. Every provider has its own setting.
--pkcs11-providers provider...
Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers to load. This option can be used instead of --cert, --key, and --pkcs12.
--pkcs11-private-mode mode...
Specify which method to use in order to perform private key operations. A different mode can be specified for each provider. Mode is encoded as hex number, and can be a mask one of the following:

0 (default) -- Try to determind automatically.
1 -- Use sign.
2 -- Use sign recover.
4 -- Use decrypt.
8 -- Use unwrap.

--cryptoapicert select-string
Load the certificate and private key from the Windows Certificate System Store (Windows/OpenSSL Only).

Use this option instead of --cert and --key.

This makes it possible to use any smart card, supported by Windows, but also any kind of certificate, residing in the Cert Store, where you have access to the private key. This option has been tested with a couple of different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the client side, and also an imported PKCS12 software certificate on the server side.

To select a certificate, based on a substring search in the certificate's subject:

cryptoapicert "SUBJ:Peter Runestig"

To select a certificate, based on certificate's thumbprint:

cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."

The thumbprint hex string can easily be copy-and-pasted from the Windows Certificate Store GUI.

--key-method m
Use data channel key negotiation method m. The key method must match on both sides of the connection.

After OpenVPN negotiates a TLS session, a new set of keys for protecting the tunnel data channel is generated and exchanged over the TLS session.

In method 1 (the default for OpenVPN 1.x), both sides generate random encrypt and HMAC-send keys which are forwarded to the other host over the TLS channel.

In method 2, (the default for OpenVPN 2.0) the client generates a random key. Both client and server also generate some random seed material. All key source material is exchanged over the TLS channel. The actual keys are generated using the TLS PRF function, taking source entropy from both client and server. Method 2 is designed to closely parallel the key generation process used by TLS 1.0.

Note that in TLS mode, two separate levels of keying occur:

(1) The TLS connection is initially negotiated, with both sides of the connection producing certificates and verifying the certificate (or other authentication info provided) of the other side. The --key-method parameter has no effect on this process.

(2) After the TLS connection is established, the tunnel session keys are separately negotiated over the existing secure TLS channel. Here, --key-method determines the derivation of the tunnel session keys.

--tls-cipher l
A list l of allowable TLS ciphers delimited by a colon (":"). If you require a high level of security, you may want to set this parameter manually, to prevent a version rollback attack where a man-in-the-middle attacker tries to force two peers to negotiate to the lowest level of security they both support. Use --show-tls to see a list of supported TLS ciphers.
--tls-timeout n
Packet retransmit timeout on TLS control channel if no acknowledgment from remote within n seconds (default=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.
--reneg-bytes n
Renegotiate data channel key after n bytes sent or received (disabled by default). OpenVPN allows the lifetime of a key to be expressed as a number of bytes encrypted/decrypted, a number of packets, or a number of seconds. A key renegotiation will be forced if any of these three criteria are met by either peer.
--reneg-pkts n
Renegotiate data channel key after n packets sent and received (disabled by default).
--reneg-sec n
Renegotiate data channel key after n seconds (default=3600).

When using dual-factor authentication, note that this default value may cause the end user to be challenged to reauthorize once per hour.

Also, keep in mind that this option can be used on both the client and server, and whichever uses the lower value will be the one to trigger the renegotiation. A common mistake is to set --reneg-sec to a higher value on either the client or server, while the other side of the connection is still using the default value of 3600 seconds, meaning that the renegotiation will still occur once per 3600 seconds. The solution is to increase --reneg-sec on both the client and server, or set it to 0 on one side of the connection (to disable), and to your chosen value on the other side.

--hand-window n
Handshake Window -- the TLS-based key exchange must finalize within n seconds of handshake initiation by any peer (default = 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.
--tran-window n
Transition window -- our old key can live this many seconds after a new a key renegotiation begins (default = 3600 seconds). This feature allows for a graceful transition from old to new key, and removes the key renegotiation sequence from the critical path of tunnel data forwarding.
--single-session
After initially connecting to a remote peer, disallow any new connections. Using this option means that a remote peer cannot connect, disconnect, and then reconnect.

If the daemon is reset by a signal or --ping-restart, it will allow one new connection.

--single-session can be used with --ping-exit or --inactive to create a single dynamic session that will exit when finished.

--tls-exit
Exit on TLS negotiation failure.
--tls-auth file [direction]
Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.

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 key file which can be in one of two formats:

(1) An OpenVPN static key file generated by --genkey (required if direction parameter is used).

(2) A freeform passphrase file. In this case the HMAC key will be derived by taking a secure hash of this file, similar to the md5sum(1) or sha1sum(1) commands.

OpenVPN will first try format (1), and if the file fails to parse as a static key file, format (2) will be used.

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

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

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 (Note: OpenVPN will only read passwords from a file if it has been built with the --enable-password-save configure option, or on Windows by defining ENABLE_PASSWORD_SAVE in win/settings.in).

--auth-nocache
Don't cache --askpass or --auth-user-pass username/passwords in virtual memory.

If specified, this directive will cause OpenVPN to immediately forget username/password inputs after they are used. As a result, when OpenVPN needs a username/password, it will prompt for input from stdin, which may be multiple times during the duration of an OpenVPN session.

This directive does not affect the --http-proxy username/password. It is always cached.

--tls-verify cmd
Run command cmd to verify the X509 name of a pending TLS connection that has otherwise passed all other tests of certification (except for revocation via --crl-verify directive; the revocation test occurs after the --tls-verify test).

cmd should return 0 to allow the TLS handshake to proceed, or 1 to fail.

cmd consists of a path to script (or executable program), optionally followed by arguments. The path and arguments may be single- or double-quoted and/or escaped using a backslash, and should be separated by one or more spaces.

When cmd is executed two arguments are appended after any arguments specified in cmd , as follows:

cmd certificate_depth subject

These arguments are, respectively, the current certificate depth and the X509 common name (cn) of the peer.

This feature is useful if the peer you want to trust has a certificate which was signed by a certificate authority who also signed many other certificates, where you don't necessarily want to trust all of them, but rather be selective about which peer certificate you will accept. This feature allows you to write a script which will test the X509 name on a certificate and decide whether or not it should be accepted. For a simple perl script which will test the common name field on the certificate, see the file verify-cn in the OpenVPN distribution.

See the "Environmental Variables" section below for additional parameters passed as environmental variables.

--tls-export-cert directory
Store the certificates the clients uses 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.
--x509-username-field fieldname
Field in x509 certificate subject to be used as username (default=CN). Fieldname will be uppercased before matching. When this option is used, the --verify-x509-username option will match against the chosen fieldname instead of the CN.
--tls-remote name (DEPRECATED)
Accept connections only from a host with X509 name or common name equal to name. The remote host must also pass all other tests of verification.

NOTE: Because tls-remote may test against a common name prefix, only use this option when you are using OpenVPN with a custom CA certificate that is under your control. Never use this option when your client certificates are signed by a third party, such as a commercial web CA.

Name can also be a common name prefix, for example if you want a client to only accept connections to "Server-1", "Server-2", etc., you can simply use --tls-remote Server

Using a common 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.

--tls-remote is a useful replacement for the --tls-verify option to verify the remote host, because --tls-remote works in a --chroot environment too.

Please also note: This option is now deprecated. It will be removed either in OpenVPN v2.4 or v2.5. So please make sure you support the new X.509 name formatting described with the --compat-names option as soon as possible by updating your configurations to use --verify-x509-name instead.

--verify-x509-name name type
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.

Which X.509 name is compared to name depends on the setting of type. type can be "subject" to match the complete subject DN (default), "name" to match a subject RDN or "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' and --verify-x509-name Server-1 name or you could use --verify-x509-name Server- name-prefix if you want a client to only accept connections to "Server-1", "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 "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 '+' to attribute to save values from full cert chain. Values will be encoded as X509_<depth>_<attribute>=<value>. Multiple --x509-track options can be defined to track multiple attributes. Not available with PolarSSL.
--ns-cert-type client|server
Require that peer certificate was signed with an explicit nsCertType designation of "client" or "server".

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

See the easy-rsa/build-key-server script for an example of how to generate a certificate with the nsCertType field set to "server".

If the server certificate's nsCertType field is set to "server", then the clients can verify this with --ns-cert-type server.

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 --ns-cert-type, --verify-x509-name, or --tls-verify.

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

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

The key usage should be encoded in hex, more than one key usage can be specified.

--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-tls client|server
Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules.

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

The --remote-cert-tls client option is equivalent to --remote-cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authentication"

The key usage is digitalSignature and/or keyAgreement.

The --remote-cert-tls server option is equivalent to --remote-cert-ku a0 88 --remote-cert-eku "TLS Web Server Authentication"

The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).

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.

--crl-verify crl ['dir']
Check peer certificate against the file crl in PEM format.

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.

If the optional dir flag is specified, enable a different mode where crl is 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.

Comments