98. Keytool vs openssl for Java

Note: This article is generated by Gemini.

This technical deep-dive explores the nuances of managing SSL Trust Anchors in Java 23, specifically focusing on Let’s Encrypt certificates and why standard OpenSSL exports often fail where Java’s native tools succeed.

---

Understanding Java Trust Anchors: A Let’s Encrypt Case Study

When developing or debugging secure Java applications, you will inevitably encounter the dreaded javax.net.ssl.SSLHandshakeException. This guide documents the process of isolating a specific Root Certificate Authority (CA) and forcing Java to use it as the sole “Trust Anchor.”

1. Locating the Let’s Encrypt Root on macOS

On a MacBook, the OS maintains its own trusted certificates. To test a connection manually, we first need to extract the ISRG Root X1 (the primary root for Let’s Encrypt).

The Command:

security find-certificate -c "ISRG Root X1" -p /System/Library/Keychains/SystemRootCertificates.keychain > isrg_root.pem

2. The “Trust Anchor” Problem

In Java, a “Trust Anchor” is a certificate you have explicitly decided to trust. If you tell Java to use a custom trust store, it ignores the thousands of default certificates (like Google, Amazon, or Digicert) and relies only on what you provide.

The Common Error

If you pass a raw .pem file to the Java trustStore property, you will likely see:

java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty

This occurs because Java expects a KeyStore container (a structured database), not a flat text file. If it cannot parse the file, it finds zero certificates, and the “anchor” list remains empty.

---

3. JKS vs. PKCS12 in Java 23

While JKS (Java KeyStore) is the legacy format, PKCS12 is the modern industry standard. However, Java 23 is picky about how these are structured.

Why OpenSSL Exports Often Fail

When you use openssl pkcs12 -export to create a trust store, it often misses a critical metadata tag: the TrustedCertificateEntry. OpenSSL sees the file as a “bundle of data,” while Java is looking for a “list of trusted authorities.” Without this internal flagging, Java sees the certs but refuses to use them as anchors.

The Solution: Using keytool

The most reliable way to create a Java-compatible trust store is using Java’s own keytool. This ensures the certificate is correctly labeled as a trusted entry.

List trusted cert of Java

# This searches your Java truststore for the Let's Encrypt root
keytool -list -v -cacerts -storepass changeit | grep "ISRG Root X1"

Creating the Store:

keytool -importcert -file isrg_root.pem -keystore learning.p12 -storetype PKCS12 -alias letsencrypt -storepass changeit -noprompt

---

4. Technical Implementation (Java 23)

The following code can be used to verify if your custom trust store is working correctly.

import javax.net.ssl.SSLSocket;
import javax.net.ssl.SSLSocketFactory;

public class VerifyCert {
    public static void main(String[] args) {
        String host = "letsencrypt.org";
        try {
            SSLSocketFactory factory = (SSLSocketFactory) SSLSocketFactory.getDefault();
            SSLSocket socket = (SSLSocket) factory.createSocket(host, 443);
            socket.startHandshake();
            System.out.println("Handshake Successful: Trusted by custom Anchor.");
            socket.close();
        } catch (Exception e) {
            System.err.println("Handshake Failed: " + e.getMessage());
        }
    }
}

Execution

Run the application by pointing specifically to your new PKCS12 file:

# compile 
javac VerifyCert.java

# run
java -Djavax.net.ssl.trustStore=learning.p12 \
     -Djavax.net.ssl.trustStoreType=PKCS12 \
     -Djavax.net.ssl.trustStorePassword=changeit \
     VerifyCert

5. Summary Findings

• Java doesn’t use the Mac Keychain: It uses its own cacerts file or a custom trust store provided at runtime.
• Format Matters: Use PKCS12 for modern compatibility, but build it with keytool to ensure the “Trusted” metadata is present.
• The “Empty” Error: This is almost always a sign that Java couldn’t parse your trust store file or didn’t find any certificates flagged as trusted within it.

---