diff options
author | Frank Lichtenheld | 2023-12-13 15:33:24 +0100 |
---|---|---|
committer | Gert Doering | 2023-12-26 21:45:49 +0100 |
commit | 139607286ce5d618ece8b17923ce12f418695f4c (patch) | |
tree | f6ae134d582e3c35b10a4d0a6c021f60e9010969 | |
parent | 3e30504d86f0fe5556acc0cb8e6975c5b2277661 (diff) | |
download | openvpn-139607286ce5d618ece8b17923ce12f418695f4c.zip openvpn-139607286ce5d618ece8b17923ce12f418695f4c.tar.gz |
documentation: improve documentation of --x509-track
In the current state it was completely unclear to me how you
would use this. Extended the description based on reading the
code and experimentation.
Change-Id: Ibf728f9d624e64ecda094d66fa562bd3916829d2
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.com>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20231213143324.226443-1-frank@lichtenheld.com>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg27804.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>
-rw-r--r-- | doc/man-sections/script-options.rst | 3 | ||||
-rw-r--r-- | doc/man-sections/tls-options.rst | 23 |
2 files changed, 24 insertions, 2 deletions
diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst index 38dcfa2..6f90e14 100644 --- a/doc/man-sections/script-options.rst +++ b/doc/man-sections/script-options.rst @@ -916,6 +916,9 @@ instances. verification level is 0 for the client certificate and 1 for the CA certificate. + You can use the ``--x509-track`` option to export more or less information + from the certificates. + :: X509_0_emailAddress=me@myhost.mydomain diff --git a/doc/man-sections/tls-options.rst b/doc/man-sections/tls-options.rst index 266167f..4c45b10 100644 --- a/doc/man-sections/tls-options.rst +++ b/doc/man-sections/tls-options.rst @@ -695,10 +695,29 @@ If the option is inlined, ``algo`` is always :code:`SHA256`. --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`` + from full cert chain. Otherwise the attribute will only be exported for + the leaf cert (i.e. depth :code:`0` of the cert chain). Values will be + encoded as :code:`X509_<depth>_<attribute>=<value>`. Multiple ``--x509-track`` options can be defined to track multiple attributes. + ``attribute`` can be any part of the X509 Subject field or any X509v3 + extension (RFC 3280). X509v3 extensions might not be supported when + not using the default TLS backend library (OpenSSL). You can also + request the ``SHA1`` and ``SHA256`` fingerprints of the cert, + but that is always exported as :code:`tls_digest_{n}` and + :code:`tls_digest_sha256_{n}` anyway. + + Note that by default **all** parts of the X509 Subject field are exported in + the environment for the whole cert chain. If you use ``--x509-track`` at least + once **only** the attributes specified by these options are exported. + + Examples:: + + x509-track CN # exports only X509_0_CN + x509-track +CN # exports X509_{n}_CN for chain + x509-track basicConstraints # exports value of "X509v3 Basic Constraints" + x509-track SHA256 # exports SHA256 fingerprint + --x509-username-field args Fields in the X.509 certificate subject to be used as the username (default :code:`CN`). If multiple fields are specified their values |