Add client certificate auth page

docs/src/main/sphinx/installation/cli.rst

@@ -59,7 +59,7 @@ Use ``--help`` to see information about specifying the keystore, truststore, and
 other authentication details as required. If using Kerberos, see :doc:`/security/cli`.
 
 External authentication - SSO
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``--external-authentication`` option is used for browser-based SSO
 authentication, as detailed in :doc:`/security/oauth2`. With this configuration,
@@ -80,6 +80,35 @@ The detailed behavior is as follows:
   authentication system configuration.
 * Expired tokens force you to log in again.
 
+.. _cli-certificate-auth:
+
+Certificate authentication
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following command line arguments to allow you to connect the CLI to a
+cluster that enables client :doc:`certificate authentication
+</security/certificate>`.
+
+.. list-table:: Certificate authentication options
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - ``--keystore-path=<path>``
+     - Keystore path to a :doc:`PEM </security/inspect-pem>` or :doc:`JKS
+       </security/inspect-jks>` file, which must include a certificate and
+       private key for the CLI.
+   * - ``--keystore-password=<password>``
+     - Only required if the key has a password.
+   * - ``--keystore-type=<type>``
+     - Rarely used. Specifies the service name for the keystore type in the JVM.
+       You can query the JVM for its list of supported key types.
+
+The three ``--truststore`` related options are used to specify the trust chain
+for validating the *server's* certificate, and are not part of client
+certificate authentication for the CLI.
+
 Pagination
 ----------
 

docs/src/main/sphinx/installation/jdbc.rst

@@ -110,6 +110,8 @@ These methods may be mixed; some parameters may be specified in the URL,
 while others are specified using properties. However, the same parameter
 may not be specified using both methods.
 
+.. _jdbc-parameter-reference:
+
 Parameter reference
 -------------------
 
@@ -132,17 +134,19 @@ Name                                                         Description
                                                              property nor ``ApplicationName`` or ``source`` are set, the source
                                                              name for the query is ``trino-jdbc``.
 ``accessToken``                                              Access token for token based authentication.
-``SSL``                                                      Use HTTPS for connections
-``SSLVerification``                                          The method of SSL verification. There are three modes: ``FULL``
+``SSL``                                                      Use HTTPS/TLS for connections
+``SSLVerification``                                          The method of TLS verification. There are three modes: ``FULL``
                                                              (default), ``CA`` and ``NONE``. For ``FULL``, the normal TLS
                                                              verification is performed. For ``CA``, only the CA is verified but
                                                              hostname mismatch is allowed. For ``NONE``, there is no verification.
-``SSLKeyStorePath``                                          The location of the Java KeyStore file that contains the certificate
-                                                             and private key to use for authentication.
-``SSLKeyStorePassword``                                      The password for the KeyStore.
+``SSLKeyStorePath``                                          Keystore path to a :doc:`PEM </security/inspect-pem>` or :doc:`JKS
+                                                             </security/inspect-jks>` file, which must include a certificate and
+                                                             private key for the JDBC client for use when connecting to a cluster
+                                                             with :doc:`/security/certificate` enabled.
+``SSLKeyStorePassword``                                      The password for the KeyStore, if any.
 ``SSLKeyStoreType``                                          The type of the KeyStore. The default type is provided by the Java
                                                              ``keystore.type`` security property or ``jks`` if none exists.
-``SSLTrustStorePath``                                        The location of the Java TrustStore file to use.
+``SSLTrustStorePath``                                        The location of the Java TrustStore file to use
                                                              to validate HTTPS server certificates.
 ``SSLTrustStorePassword``                                    The password for the TrustStore.
 ``SSLTrustStoreType``                                        The type of the TrustStore. The default type is provided by the Java

docs/src/main/sphinx/security.rst

@@ -33,6 +33,7 @@ Authentication
   security/oauth2
   security/kerberos
   security/cli
+  security/certificate
 
 User name management
 ====================

docs/src/main/sphinx/security/authentication-types.rst

@@ -12,7 +12,7 @@ and authenticators are available:
 
 * ``PASSSWORD`` for  :doc:`password-file`, :doc:`ldap`, and :doc:`salesforce`
 * ``OAUTH2`` for :doc:`oauth2`
-* ``CERTIFICATE`` for certificate authentication
+* ``CERTIFICATE`` for :doc:`certificate`
 * ``JWT`` for Java Web Token (JWT) authentication
 * ``KERBEROS`` for :doc:`kerberos`
 

docs/src/main/sphinx/security/certificate.rst

@@ -0,0 +1,108 @@
+==========================
+Certificate authentication
+==========================
+
+You can configure Trino to support client-provided certificates validated by the
+Trino server on initial connection.
+
+.. important::
+
+    This authentication method is only provided to support sites that have an
+    absolute requirement for client authentication *and already have* client
+    certificates for each client. Sites in this category have an existing PKI
+    infrastructure, possibly including an onsite Certificate Authority.
+
+    This feature is not appropriate for sites that would need to generate a set
+    of client certificates in order to use this authentication method. Consider
+    instead using another :doc:`authentication method
+    </security/authentication-types>`.
+
+Using certificate authentication
+--------------------------------
+
+All clients connecting with HTTPS/TLS go through the following initial steps:
+
+* The client attempts to contact the coordinator.
+* The coordinator returns its certificate to the client.
+* The client validates the server's certificate using the client's trust store.
+
+A cluster with certificate authentication enabled goes through the following
+additional steps:
+
+* The coordinator asks the client for its certificate.
+* The client responds with its certificate.
+* The coordinator verifies the client's certificate, using the coordinator's
+  trust store.
+
+Several rules emerge from these steps:
+
+1. Trust stores used by clients must include the certificate of the signer of
+   the coordinator's certificate.
+2. Trust stores used by coordinators must include the certificate of the signer
+   of client certificates.
+3. The trust stores used by the coordinator and clients do not need to be the
+   same.
+4. The certificate that verifies the coordinator does not need to be the same as
+   the certificate verifying clients.
+
+Trino validates based on the distinguished name (DN) from the X.509 ``Subject``
+field. The principal created for the connection is the common name (CN) from the
+``Subject`` field. You can use :doc:`user mapping </security/user-mapping>` to
+map the CN to a Trino user name.
+
+There are three levels of client certificate support possible. From the point of
+view of the server:
+
+* The server does not require a certificate from clients.
+* The server asks for a certificate from clients, but allows connection without one.
+* The server must have a certificate from clients to allow connection.
+
+Trino's client certificate support is the middle type. It asks for a certificate
+but allows connection if another authentication method passes.
+
+Certificate authentication configuration
+----------------------------------------
+
+Enable certificate authentication by setting the :doc:`Certificate
+authentication type <authentication-types>` in :ref:`etc/config.properties
+<config_properties>`:
+
+.. code-block:: properties
+
+    http-server.authentication.type=CERTIFICATE
+
+You can specify certificate authentication along with another authenticaton
+method, such as ``PASSWORD``. In this case, authentication is performed in the
+order of entries, and the first successful authentication results in access.
+
+.. code-block:: properties
+
+    http-server.authentication.type=CERTIFICATE,PASSWORD
+
+The following configuration properties are also available:
+
+.. list-table:: Configuration properties
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Property
+     - Description
+   * - ``http-server.authentication.certificate.user-mapping.pattern``
+     -  A regular expression pattern to :doc:`map all user names
+        </security/user-mapping>` for this authentication system to the format
+        expected by the Trino server.
+   * - ``http-server.authentication.certificate.user-mapping.file``
+     - The path to a JSON file that contains a set of :doc:`user mapping
+       rules </security/user-mapping>` for this authentication system.
+
+Use certificate authencation with clients
+-----------------------------------------
+
+When using the Trino :doc:`CLI </installation/cli>`, specify the
+``--keystore-path`` and ``--keystore-password`` options as described
+in :ref:`cli-certificate-auth`.
+
+When using the Trino :doc:`JDBC driver </installation/jdbc>` to connect to a
+cluster with certificate authentication enabled, use the ``SSLKeyStoreType`` and
+``SSLKeyStorePassword`` :ref:`parameters <jdbc-parameter-reference>` to specify
+the path to the client's certificate and its password, if any.