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.

Important

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.

Approaches#

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:

X-Forwarded-Proto: https

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:

http-server.process-forwarded=true

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:

    • A commercial certificate vendor

    • Your cloud infrastructure provider

    • A domain name registrar, such as Verisign or GoDaddy

    • A free certificate generator, such as letsencrypt.org or sslforfree.com

  • 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 .p12 or .pfx extensions.

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

or:

cat clustercoord.pem

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 KEY or BEGIN_DSA_PRIVATE_KEY, this designates keys using Elliptical Curve or DSA alternatives to RSA. In these cases, consult openssl references for the appropriate versions of the commands below.

Inspect received PEM certificates#

A separate certificate file looks like the following with the cat command:

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

Validate key#

This page presumes your system provides the openssl command from OpenSSL 1.1 or later.

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

Validate certificate#

Analyze a certificate file, or the certificate portion of a concatenated file, with a different openssl command:

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 characteristics:

  • Modern browsers now enforce 398 days as the maximum validity period for a certificate. Look for Not Before and Not After dates in the Validity section 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.

Invalid certificates#

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 command line, 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 the https-server.https.keymanager.password configuration property described below.

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 ... until entry 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 a new 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.

Note

Legacy keystore and 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:

http-server.https.keystore.path=etc/clustercoord.jks
http-server.https.keystore.path=/usr/local/certs/clustercoord.p12

Relative paths are relative to the Trino server’s root directory. In a tar.gz installation, the root directory is one level above etc.

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.

http-server.https.keystore.key=<keystore-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:

http-server.https.keymanager.password=<key-password>

Restart the server and test connecting to it with a URL that begins with https:// using the Trino CLI or Web UI.

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:

http-server.authentication.allow-insecure-over-http=true

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:

http-server.http.enabled=false

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 enabled=true:

http-server.http.enabled=true
http-server.https.enabled=true