HTTPS and TLS#
Trino runs with no security configuration in its default installation. This allows you to connect to the server using URLs that specify the HTTP protocol with the Trino CLI, the Web UI, or other clients.
This guide describes how to configure your Trino server to use Transport Layer Security (TLS), thereby requiring the HTTPS protocol from client connections. All authentication and authorization technologies supported by Trino require configuring TLS as the foundation.
When configured to use TLS, a Trino server responds to connections from TLS 1.2 and TLS 1.3 certificates. The server rejects TLS 1.1, TLS 1.0, and all SSL format certificates.
This page discusses only how to prepare the Trino server for client connections from outside of the Trino cluster to its coordinator.
Transport Layer Security (TLS) is the successor to its now-deprecated predecessor, Secure Sockets Layer (SSL). This page uses the term TLS to refer to TLS and SSL.
To configure Trino with TLS support, there are two alternative paths to consider:
Use the load balancer or proxy at your site or cloud environment to terminate HTTPS/TLS. This approach is the simplest and strongly preferred solution.
Secure the Trino server directly. This requires you to obtain a valid certificate, and add it to the Trino coordinator’s configuration.
Use a load balancer to terminate HTTPS/TLS#
Your site or cloud environment may already have a load balancer or proxy server configured and running with a valid TLS certificate. In this case, you can work with your network administration group to set up your Trino server behind the load balancer. The load balancer or proxy server accepts TLS connections and forwards them to the Trino coordinator, which typically runs with default HTTP configuration on the default port, 8080.
When a load balancer accepts a TLS encrypted connection, it places the following string in the HTML header of connection attempts:
This tells the Trino coordinator to process the connection as if a TLS
connection has already been successfully negotiated for it. This is why you do
not need to configure
http-server.https.enabled=true for a coordinator
behind a load balancer.
However, to enable processing of such forwarded headers, the server’s config properties file must include the following:
This completes any necessary configuration for using HTTPS with a load balancer. Client tools can access Trino with the URL exposed by the load balancer.
Secure Trino directly#
Instead of the preferred mechanism of using an external load balancer, you can secure the Trino coordinator itself. This requires you to obtain and install a TLS certificate and configure Trino to use it for any client connections.
Add a TLS certificate#
Obtain a TLS certificate file for use with your Trino server. Consider the following types of certificates:
Globally trusted certificates. A certificate that is automatically trusted by browsers and clients such as
curl. This is the easiest type to use because you do not need to configure clients. Obtain a certificate of this type from:
Corporate trusted certificates. A certificate trusted by browsers and clients in your company. Typically, a site’s IT department runs a local certificate authority and preconfigures clients and servers to trust this CA.
Generated self-signed certificates. A certificate generated just for Trino that is not automatically trusted by any client. However, see Limitations of self-signed certificates.
Trino recognizes public and private keys as specified in the PKCS #1 standard,
and recognizes x.509 certificates. Both keys and certificates can be simple
PEM-encoded files or can be imported into legacy JKS containers. Directly using
PEM-encoded files, as specified in the PKCS #8 standard, is preferred and is
easier to work with. Trino also recognizes certifificates and keys in the binary
PKCS #12 keystore format, usually in a file with
Make sure you obtain a certificate that is validated by a recognized certification authority (CA).
Inspect received key files#
This section shows how to inspect and validate key and certificate files received in PEM-encoded format. The Inspect JKS keystores section below shows how to validate keys in the legacy JKS truststore format.
When you receive your PEM format key and certificate file or files, inspect them to verify that they show the correct information for your Trino server. The file name extensions shown on this page are examples only; there is no extension naming standard.
You may receive a single file that includes a private key and its certificate,
or separate files. First, use the
cat command to view these plain text
files. For example:
cat clustercoord.key cat clustercoord.cert
A key file looks something like the following:
-----BEGIN PRIVATE KEY----- MIIEowIBAAKCAQEAwJL8CLeDFAHhZe3QOOF1vWt4Vuk9vyO38Y1y9SgBfB02b2jW .... -----END PRIVATE KEY-----
If your key file reports
BEGIN ENCRYPTED PRIVATE KEY instead, you must
specify the key’s password to open or inspect the file. You specified the
password when requesting the key, or the password could be assigned by your
site’s network managers.
If your key file reports
BEGIN EC PRIVATE KEYor
BEGIN_DSA_PRIVATE_KEY, this designates keys using Elliptical Curve or DSA alternatives to RSA. In these cases, consult
opensslreferences for the appropriate versions of the commands below.
Inspect received PEM certificates#
A separate certificate file looks like the following with the
-----BEGIN CERTIFICATE----- MIIDujCCAqICAQEwDQYJKoZIhvcNAQEFBQAwgaIxCzAJBgNVBAYTAlVTMRYwFAYD .... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIDwjCCAqoCCQCxyqwZ9GK50jANBgkqhkiG9w0BAQsFADCBojELMAkGA1UEBhMC .... -----END CERTIFICATE-----
The file can show a single certificate section, or more than one to express a chain of authorities, each certifying the previous.
If you received a single file, make sure it shows at least one KEY and CERTIFICATE section. If you received separate files, concatenate them into one, typically in order from key to certificate. For example:
cat clustercoord.key clustercoord.cert > clustercoord.pem
This page presumes your system provides the
openssl command from OpenSSL 1.1
Test an RSA-encoded private key’s validity with the following command:
openssl rsa -in clustercoord.pem -check -noout
Look for the following confirmation message:
RSA key ok
Analyze a certificate file, or the certificate portion of a concatenated file,
with a different
openssl x509 -in server.pem -text -noout
If your certificate was generated with a password,
openssl prompts for it.
In the output of the
openssl command, look for the following
Modern browsers now enforce 398 days as the maximum validity period for a certificate. Look for
Not Afterdates in the
Validitysection of the output, and make sure the time span does not exceed 398 days.
Modern browsers and clients require the Subject Alternative Name (SAN) field. Make sure this shows the DNS name of your server, such as
DNS:clustercoord.example.com. Certificates without SANs are not supported.
If your certificate does not pass validation, or does not show the expected information upon inspection, contact the group or vendor who provided it.
Inspect JKS keystores#
The Java KeyStore (JKS) system is provided by your Java installation. JKS keys are stored in a JKS keystore file.
Inspect the JKS keystore file to make sure it contains the correct information
for your Trino server. Use the
keytool command, which is installed as part
of Java, to retrieve information from your keystore container file:
keytool -list -v -keystore yourKeystore.jks
Keystores always require a password. If not provided on the
keytool prompts for the password.
Independent of the keystore’s password, it is possible that the JKS key has its
own password. It is easiest to make sure these passwords are the same. If the
JKS key inside the keystore has a different password, you must specify it with
https-server.https.keymanager.password configuration property described
In the output of the
keytool -list command, look for:
The keystore must contain a private key, such as
Entry type: PrivateKeyEntry
Depending on the origin of your keystore file, it may also contain a certificate. Example:
Entry type: trustedCertEntry
Confirm that the
Valid from ... untilentry shows no more than 398 days.
Verify that the subject alternative name, if present, matches your server’s DNS name. Example:
SubjectAlternativeName [ DNSName: cluster.example.com ]
The JKS system works in conjunction with a truststore, described in Java truststore.
Place the certificate file#
There are no location requirements for the certificate file as long as the following applies:
The location is visible from the server’s configuration file location with a relative path reference from the server’s root directory, or with an absolute path reference.
The location is secure from copying or tampering by malicious actors.
You can place your file in the Trino server’s
etc directory, which allows
you to use a relative path reference in configuration files. However, this
location can require you to keep track of the certificate file, and move it to
etc directory when you upgrade your Trino version.
Configure the coordinator#
On the coordinator, add the following lines to the config properties file to enable HTTPS support for the server.
truststore wording is used in property names,
even when using PEM format certificates. PEM certs generally do not require
truststore properties, because this format incorporates its chain of
authorizing certificates back to the originating CA (or possibly back to an
intermediate CA assigned by a large international CA).
http-server.https.enabled=true http-server.https.port=8443 http-server.https.keystore.path=etc/clustercoord.pem
Possible alternatives for the third line include:
Relative paths are relative to the Trino server’s root directory. In a
tar.gz installation, the root directory is one level above
JKS keystores always require a password, while PEM format certificates can optionally require a password. For these cases, add the following line to specify the password.
It is possible for a key inside a keystore to have its own password, independent of the keystore’s password. In this case, specify the key’s password with the following property:
When your Trino coordinator has an authenticator enabled along with HTTPS enabled, it disables HTTP access to the Web UI. Although not recommended, you can re-enable it by setting:
When configured to provide HTTPS connections as shown above, the server continues to allow HTTP connections to all clients except the Web UI. When you are certain HTTPS connections are stable and reliable from the clients of interest, you can disable HTTP access:
However, there are configuration scenarios such as HA that requires HTTP to be
enabled, even with HTTPS enabled for client access. In these cases, configure
both server types as