JKS files#

This topic describes how to validate a Java keystore (JKS) file used to configure TLS and HTTPS.

The Java KeyStore (JKS) system is provided as part of your Java installation. Private keys and certificates for your server are stored in a keystore file. The JKS system supports both PKCS #12 .p12 files as well as legacy keystore .jks files.

The keystore file itself is always password-protected. The keystore file can have more than one key in the same file, each addressed by its alias name.

If you receive a keystore file from your site’s network admin group, verify that it shows the correct information for your Trino cluster, as described next.

Inspect and validate keystore#

Inspect the keystore file to make sure it contains the correct information for your Trino server. Use the keytool command, which is installed as part of your Java installation, to retrieve information from your keystore 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 an individual 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 are prompted twice.

In the output of the keytool -list command, look for:

  • The keystore may contain either a private key (Entry type: PrivateKeyEntry) or certificate (Entry type: trustedCertEntry) or both.

  • Modern browsers now enforce 398 days as the maximum validity period for a certificate. Look for the Valid from ... until entry, and make sure the time span does not exceed 398 days.

  • Modern browsers and clients require the SubjectAlternativeName (SAN) field. Make sure this shows the DNS name of your server, such as DNS:cluster.example.com. Certificates without SANs are not supported.

    Example:

SubjectAlternativeName [
    DNSName:  cluster.example.com
]

If your keystore shows valid information for your cluster, proceed to configure the Trino server, as described in Place the certificate file and Configure the coordinator.

The rest of this page describes additional steps that may apply in certain circumstances.

Extra: add PEM to keystore#

Your site may have standardized on using JKS semantics for all servers. If a vendor sends you a PEM-encoded certificate file for your Trino server, you can import it into a keystore with a command like the following. Consult keytool references for different options.

keytool -trustcacerts -import -alias cluster -file localhost.pem -keystore localkeys.jks

If the specified keystore file exists, keytool prompts for its password. If you are creating a new keystore, keytool prompts for a new password, then prompts you to confirm the same password. keytool shows you the contents of the key being added, similar to the keytool -list format, then prompts:

Trust this certificate? [no]:

Type yes to add the PEM certificate to the keystore.

The alias name is an arbitrary string used as a handle for the certificate you are adding. A keystore can contain multiple keys and certs, so keytool uses the alias to address individual entries.

Extra: Java truststores#

Note

Remember that there may be no need to identify a local truststore when directly using a signed PEM-encoded certificate, independent of a keystore. PEM certs can contain 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 Java-provided truststore file, cacerts, is part of your Java installation in a standard location.

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

However, there are cases in which you need to use an alternate truststore. For example, 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 server must use a custom truststore, identify its location in the server’s config properties file. For example:

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

If connecting clients such as browsers or the Trino CLI must be separately configured, contact your site’s network administrators for assistance.