Keystores and truststores#

This guide describes the PEM and JKS certificate formats accepted by Starburst Enterprise platform (SEP) for client access to the cluster.

PEM format files#

PEM (Privacy Enhanced Mail) is an encoding standard used to transmit X.509 certificate information, or PKCS #1 public key information. PEM format is specified in the (PKCS #8 standard. SEP can also read binary PKCS #12 container format.

A single PEM-encoded file can contain either certificate or private key information, or both in the same file. PEM certified keys can contain a chain of certificates from successive authorities back to a recognized Certificate Authority (CA), and thus does not need a separate trust store.

If you receive a PEM-encoded certificate, follow the steps beginning with Inspect received PEM certificate on the HTTPS and TLS page.

Java keystore#

Trino recognizes certificates in PEM-encoded files or in JKS truststores for configuring access to the server using HTTPS.

Note

See PEM for information on the preferred certificate format.

The Java KeyStore (JKS) system is provided as part of your Java installation. Private keys and certificates for your server are stored in a JKS keystore file. The keystore file is always password-protected.

To be recognized as valid by the CLI and modern browsers, the JKS key must be signed by a trusted Certificate Authority (CA). For JKS keys, this means either that the signing authority for a key must be listed in the current machine’s trust store, or that the certificate received from a CA is chained all the way back to a recognized CA.

If you receive a JKS keystore file from your network group or from a vendor, inspect the keystore’s readiness to work with SEP. Then place the file and configure SEP to accept client connections using HTTPS.

Java truststore#

Note

Remember that there is no need to identify a local truststore when using a signed PEM-encoded certificate, if that file contains the server’s private key and the certificate chain all the way back to a recognzied CA.

Truststore files contain a list of Certificate Authorities trusted by Java to validate the private keys of servers, plus a list of the certificates of trusted TLS servers. The standard truststore file, cacerts, is provided as part of your Java installation in a standard location.

Keystores normally rely on the default location of the system truststore, which thereby does not need to be configured.

However, there are cases in which you need to append to the standard truststore or use an alternate, including:

  • If your site relies on the JKS system, your network managers may have appended site-specific, local CAs to the standard list, to validate locally signed keys.

  • If your Trino server is secured with a JKS format key, in order for clients such as the Trino CLI to trust the server, its certificate must be imported into the truststore used by those clients.

You can append certificates to a custom truststore, or to the default system truststore. Using the default truststore has the disdvantages that it may get overwritten by the next Java version upgrade, and that you may have to distribute copies to all client machhines.

In cases of using a custom truststore, identify its location in the server’s config properties file:

http-server.https.truststore.path=/mnt/shared/certs/localcacerts
http-server.https.truststore.key=<truststore-password>

Limitations of self-signed certificates#

It is possible to generate a self-signed certificate with either the openssl or keytool commands. These are meant to be forwarded to a CA with a Certificate Signing Request (CSR). The CA returns a globally signed key or a validating certificate to add to the locally-signed key.

Some sites have internal CAs and can provide an internal certificate valid for the duration of a project’s development phases.

Self-signed certificates can be useful during development of a cluster for internal use only. Starburst recommends never using a self-signed cert for a production Trino server, especially one that has a globally valid DNS name and address.

Certificate authorities are generally willing to sign CSRs for the server name localhost or for an internal DNS name with a restricted private network address.

However, CAs are generally unwilling to validate CSRs for self-signed certs under globally accessible circumstances. For a CA to validate a Certificate Signing Request for a server that has a globally accessible DNS name and URL, the CA must be able to validate that there is a server at that URI and that your company owns the specified URL and DNS name. This requirement prevents signed certs that are valid on one site from being copied and re-used on another site. Modern browsers detect cases of valid certs used on the wrong server, and block attempts to connect to them.

You cannot use a self-signed cert without validation from a Certificate Authority. Modern browsers detect servers running with such certs and either put up connection roadblocks or outright refuse to open such sites. Likewise, the Trino CLI detects a server running with an invalid self-signed cert and either warns against connecting or blocks the connection entirely.