javax.net.ssl.SSLHandshakeException: PKIX path building failed when QTest REST API uses self‑signed certificate

Answer to the Core Question

The javax.net.ssl.SSLHandshakeException: PKIX path building failed occurs because QTest’s Java client loads the JVM’s default truststore, which does not contain the self‑signed certificate presented by the QTest server. The client offers no exposed configuration to inject a custom truststore or to turn off validation, so the only ways to get past the exception are:

• Set JVM system properties for javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword when launching the QTest process. This supplies a trusted store without touching the global cacerts file.
• Patch the client code to use a custom SSLContext that loads a user‑supplied truststore or a permissive TrustManager. This requires source access and a rebuild.
• Place a reverse proxy (NGINX, Apache, or a lightweight Java proxy) in front of QTest that terminates TLS with a trusted certificate and forwards traffic internally. The proxy handles the self‑signed certificate, so the QTest client sees a standard, trusted connection.

Likely Explanation

QTest’s REST client constructs its SSLContext by calling SSLContext.getInstance("TLS") and then init with null parameters, which causes the JVM to use the default TrustManagerFactory. That factory consults the system property javax.net.ssl.trustStore or falls back to cacerts. Because the self‑signed certificate is absent from those stores, the PKIX path validation fails.

Confirmed Facts

• QTest does not expose a configuration flag or API to supply a custom truststore or disable validation.
• Setting the JVM properties -Djavax.net.ssl.trustStore=… and -Djavax.net.ssl.trustStorePassword=… is a standard, documented way to override the default truststore for any Java application that relies on the default SSLContext.
• Disabling certificate validation (e.g., via a permissive TrustManager) removes all cryptographic guarantees and is strongly discouraged outside of isolated testing environments.
• Running a TLS‑terminating proxy is a proven workaround that keeps the client code unchanged while presenting a trusted certificate to the JVM.

Practical Steps

1. Export the QTest server certificate (or obtain the PEM file you trust):

   openssl s_client -connect qtest.example.com:443 -showcerts > qtest.cert.pem
   

2. Create a dedicated truststore that contains the certificate:

   keytool -import -file qtest.cert.pem -keystore qtest-truststore.jks -storepass changeit -alias qtest
   

3. Launch QTest with the custom store (adjust the command to match your environment):

   java -Djavax.net.ssl.trustStore=/path/to/qtest-truststore.jks \
        -Djavax.net.ssl.trustStorePassword=changeit \
        -jar qtest.jar
   

4. Verify the connection (e.g., a simple REST call or a unit test that prints the response). The SSLHandshakeException should no longer appear.
5. Optional: Use a reverse proxy (NGINX example):

   # NGINX configuration snippet
   server {
       listen 443 ssl;
       server_name qtest.internal;
   
       ssl_certificate /etc/ssl/certs/valid.crt;
       ssl_certificate_key /etc/ssl/private/valid.key;
   
       location / {
           proxy_pass https://qtest.example.com;
           proxy_ssl_certificate /etc/ssl/certs/qtest.cert.pem;
           proxy_ssl_certificate_key /etc/ssl/private/qtest.key;
       }
   }
   

Security Implications of Disabling Validation

• All integrity and authenticity guarantees of HTTPS are lost; attackers can perform man‑in‑the‑middle attacks, tamper with payloads, or inject credentials.
• Applications that rely on the response for authentication or authorization become vulnerable to credential theft.
• Disabling validation typically requires storing the truststore password in plain text or in environment variables, increasing the attack surface.
• Even in a controlled environment, the risk of accidental exposure to production traffic or other Java processes is non‑negligible.

Next Diagnostic Question

To refine the recommendation, could you confirm which QTest version you are running and whether you have access to the source code or can set JVM arguments at launch? The ability to pass -Djavax.net.ssl.trustStore or to patch the client determines the most straightforward solution.