summaryrefslogtreecommitdiff
path: root/doc/man-sections/tls-options.rst
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-08-15 21:29:54 +0200
committerBernhard Schmidt <berni@debian.org>2020-08-15 21:29:54 +0200
commit7c229d538824cb679351220ad8911f7b2daa7c23 (patch)
tree5c4d64b60da9018c7db3a9335a9787d326beade3 /doc/man-sections/tls-options.rst
parentd3986a312f5fbcfd0e78e6b147eef419fb4e5f54 (diff)
parent1079962e4c06f88a54e50d997c1b7e84303d30b4 (diff)
Update upstream source from tag 'upstream/2.5_beta1'
Update to upstream version '2.5~beta1' with Debian dir d53f9a482ac24eb491a294b26c24bb1d87afad24
Diffstat (limited to 'doc/man-sections/tls-options.rst')
-rw-r--r--doc/man-sections/tls-options.rst668
1 files changed, 668 insertions, 0 deletions
diff --git a/doc/man-sections/tls-options.rst b/doc/man-sections/tls-options.rst
new file mode 100644
index 0000000..8c2db7c
--- /dev/null
+++ b/doc/man-sections/tls-options.rst
@@ -0,0 +1,668 @@
+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.