cyberangles blog

Java SSL CertificateException: How to Resolve 'No name matching ssl.someUrl.de found' Error After Using InstallCert.java

If you’ve worked with Java applications that communicate over HTTPS, you’ve likely encountered SSL/TLS-related errors. One common frustration is the javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching ssl.someUrl.de found error—even after using the popular InstallCert.java tool to import the server’s certificate into your truststore.

This error is not about whether Java trusts the certificate (that’s what InstallCert fixes) but about whether the certificate correctly identifies the domain you’re trying to access. In this blog, we’ll demystify this error, explain why InstallCert might not resolve it, and walk through a step-by-step guide to fix it for good.

2025-12

Table of Contents#

  1. What Causes the 'No name matching' Error?
    • 1.1 Hostname Verification in Java
    • 1.2 The Role of Subject Alternative Names (SAN) and Common Name (CN)
  2. Why InstallCert.java Might Not Resolve the Error
    • 2.1 What InstallCert Actually Does
    • 2.2 Limitation: Trust ≠ Valid Identity
  3. Step-by-Step Resolution Guide
    • 3.1 Reproduce the Error and Gather Details
    • 3.2 Inspect the Certificate’s SAN and CN
    • 3.3 Fix the Root Cause: Update the Server Certificate (Recommended)
    • 3.4 Temporary Workaround: Bypass Hostname Verification (Not for Production!)
    • 3.5 Verify the Fix
  4. Common Pitfalls to Avoid
  5. Conclusion
  6. References

What Causes the 'No name matching' Error?#

Before diving into solutions, let’s understand why Java throws this error. At its core, it’s a hostname verification failure during the SSL/TLS handshake.

1.1 Hostname Verification in Java#

When your Java application connects to an HTTPS server (e.g., https://ssl.someUrl.de), the server presents its SSL certificate. Java’s SSL stack then performs two critical checks:

  1. Trust Check: Is the certificate signed by a trusted authority (or explicitly trusted via a truststore like cacerts)?
  2. Identity Check: Does the certificate’s metadata explicitly state that it is valid for the domain being accessed (ssl.someUrl.de)?

The No name matching error occurs when the identity check fails—even if the trust check passes (which is why InstallCert might not help).

1.2 The Role of Subject Alternative Names (SAN) and Common Name (CN)#

To validate the server’s identity, Java checks two fields in the certificate:

  • Subject Alternative Name (SAN): A modern, flexible field that allows specifying multiple domains (e.g., ssl.someUrl.de, *.someUrl.de). Java (and most browsers) prioritize SAN over CN.
  • Common Name (CN): A legacy field historically used to specify the primary domain. While still supported, it is considered secondary to SAN in Java 8u181+ and later.

If neither the SAN nor CN includes the domain you’re accessing (e.g., ssl.someUrl.de), Java rejects the certificate with the "No name matching" error—even if the certificate is trusted.

Example Scenario:
Suppose the server’s certificate has:

  • CN=old.someUrl.de (no SAN entries).
    You’re trying to access https://ssl.someUrl.de.
    Java will check SAN first (none found), then CN (old.someUrl.de ≠ ssl.someUrl.de), and throw the error.

Why InstallCert.java Might Not Resolve the Error#

InstallCert.java is a widely used utility to import untrusted certificates into Java’s truststore. But it has a critical limitation:

2.1 What InstallCert Actually Does#

InstallCert connects to a server, retrieves its SSL certificate, and adds it to Java’s truststore (typically $JAVA_HOME/jre/lib/security/cacerts). This fixes trust check failures (e.g., "unable to find valid certification path to requested target").

2.2 Limitation: Trust ≠ Valid Identity#

InstallCert solves the trust problem, but not the identity problem. If the certificate itself is misconfigured (e.g., missing ssl.someUrl.de in SAN/CN), adding it to the truststore won’t make Java ignore the hostname mismatch.

In short: Trusted ≠ Correctly Identified.

Step-by-Step Resolution Guide#

To fix the "No name matching" error, we’ll systematically diagnose and resolve the hostname verification failure.

3.1 Reproduce the Error and Gather Details#

First, confirm the error is reproducible. Run your Java application or use curl/wget to test the connection:

# Example: Using curl to check for hostname issues (may not show Java-specific errors, but helps)
curl -v https://ssl.someUrl.de

Look for errors like SSL: no alternative certificate subject name matches target host name.

3.2 Inspect the Certificate’s SAN and CN#

Next, check the server’s certificate to see if it includes ssl.someUrl.de in SAN or CN. Use openssl (command-line tool) or Java’s keytool for this.

Option 1: Use openssl to Inspect the Certificate#

Run this command to fetch and print the certificate details:

openssl s_client -connect ssl.someUrl.de:443 < /dev/null | openssl x509 -noout -text -in -

Look for the X509v3 Subject Alternative Name and Subject: CN= fields in the output.

Example of a Valid Certificate:

X509v3 Subject Alternative Name:
    DNS:ssl.someUrl.de, DNS:www.someUrl.de
Subject: CN=ssl.someUrl.de, O=SomeOrg, L=SomeCity, C=DE

Example of an Invalid Certificate (missing ssl.someUrl.de):

X509v3 Subject Alternative Name:
    DNS:old.someUrl.de, DNS:*.old.someUrl.de
Subject: CN=old.someUrl.de, O=SomeOrg, L=SomeCity, C=DE

Option 2: Use keytool to Inspect the Trusted Certificate#

If you already used InstallCert to import the certificate, check it in your truststore (default: $JAVA_HOME/jre/lib/security/cacerts):

keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts -alias ssl.someUrl.de

(Replace ssl.someUrl.de with the alias InstallCert used—often the domain name.)

Look for SubjectAlternativeName and Subject: CN= in the output.

If the certificate’s SAN/CN do not include ssl.someUrl.de, the correct long-term solution is to update the server’s SSL certificate.

Steps for Server Admins:#

  1. Regenerate the certificate signing request (CSR) to include ssl.someUrl.de in the SAN field.
    • For OpenSSL, use the -addext "subjectAltName=DNS:ssl.someUrl.de" flag when generating the CSR.
  2. Obtain a new certificate from a trusted CA (or self-sign with the corrected SAN/CN).
  3. Replace the old certificate on the server.

Once the server uses the updated certificate, your Java application will pass the identity check (assuming the trust check already passes via InstallCert or a trusted CA).

3.4 Temporary Workaround: Bypass Hostname Verification (Not for Production!)#

If you’re in a development/test environment and need a quick fix (e.g., the server admin can’t update the certificate immediately), you can disable Java’s hostname verification.

WARNING: This bypasses a critical security check and exposes your application to man-in-the-middle attacks. Never use this in production!

Option 1: Bypass in Code (Java Applications)#

Add this code to your application before making HTTPS requests to disable hostname verification:

import javax.net.ssl.*;
import java.security.cert.X509Certificate;
 
public class SSLUtils {
    public static void disableHostnameVerification() {
        HttpsURLConnection.setDefaultHostnameVerifier((hostname, session) -> true);
    }
}
 
// Call this once at application startup
SSLUtils.disableHostnameVerification();

Option 2: Bypass via JVM Argument (Limited Use Cases)#

Some tools (e.g., wget, custom scripts) allow setting a system property to disable hostname verification. For Java, use:

java -Djdk.tls.disableSNIHostnameVerification=true -jar your-app.jar

Note: This property is deprecated in Java 17+ and may not work in all cases.

3.5 Verify the Fix#

After updating the certificate (or applying the workaround), retest the connection. The error should no longer occur.

To confirm, re-run the openssl command or check your Java application logs for successful HTTPS handshakes.

Common Pitfalls to Avoid#

  • Relying on CN Instead of SAN: Modern Java versions (8u181+, 11+) prioritize SAN over CN. Even if CN matches, missing SAN will cause failures in some cases.
  • Using the Wrong Truststore: Java may use a custom truststore (e.g., specified via -Djavax.net.ssl.trustStore). Ensure InstallCert imports the certificate into the truststore your application is using.
  • Bypassing Hostname Verification in Production: This is a critical security risk. Always fix the certificate in production environments.
  • Ignoring Self-Signed Certificates in SAN: Even self-signed certificates must include the correct SAN/CN to pass hostname verification.

Conclusion#

The No name matching error in Java is a hostname verification failure, not a trust issue. While InstallCert.java fixes trust by importing certificates, it won’t resolve mismatched SAN/CN in the certificate itself.

To fix the error:

  1. Inspect the certificate’s SAN/CN to confirm it includes the target domain.
  2. Update the server certificate to include the correct SAN/CN (recommended).
  3. Use temporary workarounds like disabling hostname verification only in development.

By addressing the root cause (invalid certificate identity), you ensure secure and reliable HTTPS communication in your Java applications.

References#