TLS, keystores and certificates

TLS encrypts connections and proves the identity of the server (and optionally the client) with certificates.

🔎 Unravel this example

At a glance

Mental model

A passport check.

What happens, in order

1A truststore holds the CA certificates the JVM trusts (default cacerts)A keystore holds your own private key and certificate chain, used by servers (and for client certificates in mutual TLS).
2Formats: PKCS12 (.p12, default and recommended) and legacy JKSManage with keytool. Point to them with -Djavax.net.ssl.trustStore=... or server.ssl.* and spring.ssl.bundle.* in Spring Boot.
3To trust a private CA or self-signed server, build an SSLContext from a TrustManagerFactory loaded with that certificate and give it to the HTTP client
4Failures show as SSLHandshakeException: PKIX path building failed (the server certificate chain does not lead to a trusted CA) or hostname mismatch errors

Remember

The tempting fix is a trust-all TrustManager or NoopHostnameVerifier found on forums
The handshake negotiates a version and cipher suite, the server sends its certificate chain, the client verifies each signature up to a trusted root, checks validity dates, revocation hints and that the name matches the host (Subject Alternative Name), and then a key exchange (ECDHE) derives session keys used for symmetric encryption of the traffic

Watch out

Trust-all managers and disabled hostname verificationImporting a certificate into the wrong truststoreLetting certificates expire unnoticedPasswords for keystores in source code

Example (highlighted lines explain it)

KeyStore trust = KeyStore.getInstance("PKCS12");try (InputStream in = Files.newInputStream(trustStorePath)) {    trust.load(in, trustStorePassword);}TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());tmf.init(trust);SSLContext ssl = SSLContext.getInstance("TLSv1.3");ssl.init(null, tmf.getTrustManagers(), null);

line 1 uses KeyStore, the core of TLS, keystores and certificates
line 5 uses TrustManagerFactory, the core of TLS, keystores and certificates
line 7 uses SSLContext, the core of TLS, keystores and certificates

Read the full explanation (about 2 min)

TLS encrypts connections and proves the identity of the server (and optionally the client) with certificates. In Java the trust and identity material lives in keystores, and most TLS problems are about what the JVM trusts.

A mental model

A passport check. The truststore is the list of governments whose passports you accept; the keystore is your own passport. A certificate is only valid if it was issued by someone on your list and the name matches.

How it works

A truststore holds the CA certificates the JVM trusts (default cacerts). A keystore holds your own private key and certificate chain, used by servers (and for client certificates in mutual TLS).

Formats: PKCS12 (.p12, default and recommended) and legacy JKS. Manage with keytool. Point to them with -Djavax.net.ssl.trustStore=... or server.ssl.* and spring.ssl.bundle.* in Spring Boot.

To trust a private CA or self-signed server, build an SSLContext from a TrustManagerFactory loaded with that certificate and give it to the HTTP client.

Failures show as SSLHandshakeException: PKIX path building failed (the server certificate chain does not lead to a trusted CA) or hostname mismatch errors.

Going deeper

The tempting fix is a trust-all TrustManager or NoopHostnameVerifier found on forums. It disables the entire protection and allows man-in-the-middle attacks; it must never ship. Add the right CA to the truststore instead.

Certificates expire. A production outage at midnight on an expiry date is common; monitor expiry dates and automate renewal. Keep the intermediate certificates in the chain you serve.

Prefer TLS 1.2 or 1.3 only. Do not enable SSLv3 or TLSv1/1.1, and let the JVM choose modern cipher suites.

Under the hood

The handshake negotiates a version and cipher suite, the server sends its certificate chain, the client verifies each signature up to a trusted root, checks validity dates, revocation hints and that the name matches the host (Subject Alternative Name), and then a key exchange (ECDHE) derives session keys used for symmetric encryption of the traffic.

Common mistakes

Trust-all managers and disabled hostname verification.
Importing a certificate into the wrong truststore.
Letting certificates expire unnoticed.
Passwords for keystores in source code.

How Unravel recognises it

When you paste code, Unravel looks for these signs of tls, keystores and certificates. Spotting them yourself is a good habit when you read unfamiliar code:

Types: SSLContext TrustManagerFactory KeyManagerFactory KeyStore SSLSocketFactory HttpsURLConnection X509TrustManager SSLParameters HostnameVerifier CertificateFactory X509Certificate SSLHandshakeException SSLPeerUnverifiedException SslBundles and 6 more
Configuration keys: TLSv1.3 TLSv1.2 PKCS12 JKS javax.net.ssl.trustStore javax.net.ssl.keyStore server.ssl.key-store server.ssl.enabled

Part of a learning path

Security for backend developers · previous: Symmetric encryption (AES-GCM) and key handling · next: LDAP and directory lookups

Related concepts

Symmetric encryption (AES-GCM) and key handlingI/O and data HTTP clientsI/O and data

Frequently asked questions

What is TLS, keystores and certificates?

What are the most common mistakes with TLS, keystores and certificates?

Trust-all managers and disabled hostname verification. Importing a certificate into the wrong truststore. Letting certificates expire unnoticed. Passwords for keystores in source code.

How can I see TLS, keystores and certificates in real code?

Paste your own Java into Unravel and it will point out where tls, keystores and certificates appears, explain how it works at the detail level you choose, and draw the flow of the code around it.