SSL configuration options

General information about SSL/TLS

When establishing connections to HTTPS endpoints through server-side Java components, it must be ensured that the TLS/SSL server certificate of the requested host is accepted and trusted by the Java Virtual Machine (JVM). Otherwise, no HTTPS connection to the server is established and the application responds incorrectly.

The configuration option security.ssl.trustAny controls under which conditions a TLS server certificate is accepted:

security.ssl.trustAny=true

All certificates are accepted.
The certificate does not have to be issued to the requested host or by a trusted authority. This setting should only be active in development environments.

security.ssl.trustAny=false

Only certificates that are considered trustworthy by the JVM are accepted.
It is strongly recommended to keep this setting. This is especially true for productive environments. You must ensure that server certificates from HTTPS endpoints to which connections are made are trusted. Otherwise, an error will occur when establishing a connection.

Trusting Server Certificates

For a server certificate to be considered trustworthy by the JVM, either the specific server certificate or its root certificate must be installed directly in the Java Runtime Environment (JRE). Trusted certificates or root certificates are stored in the JRE by default in a Java keystore under [JRE_HOME]/lib/security/cacerts.

Depending on the operating system or JVM configuration, other sources of trusted certificates may be used.

The following list describes what types of server certificates are commonly used by HTTPS endpoints and what needs to be considered in terms of trustworthiness.

(A) Certificates with root certificate installed in the JRE

Productive web sites that provide services via HTTPS typically have server certificates whose root certificate was issued by a Trusted Certificate Authority (CA). These root certificates are pre-installed in the JRE and are thus automatically classified as trusted.

To allow connection to an endpoint whose server certificate has a root certificate already installed in the JRE, no further steps are required.

(B) Certificates with root certificate not installed in the JRE

Occasionally, organizations use server certificates issued by their own internal CA. The associated root certificate is therefore not part of the pre-installed certificates in the JRE. Connections to HTTPS endpoints with such server certificates then fail, unless the root certificate is automatically added to all JRE installations by corporate processes.

To ensure that all server certificates issued by this organization’s internal CA are trusted, the CA’s root certificate must be added to the keystore [JRE_HOME]/lib/security/cacerts.

(C) Self-signed certificates

Self-signed server certificates, i.e. certificates that reference themselves as issuers, are often used for test purposes and should not be used in production systems. Since a self-signed server certificate is not part of the certificates already installed with the JRE, it is not trustworthy.

To allow HTTPS connections to a host that uses a self-signed server certificate, this certificate must be added to the keystore [JRE_HOME]/lib/security/cacerts.

Typical Error Messages

When establishing server-side HTTPS connections, various error situations can occur in connection with the validation of server certificates. The following sections list typical error messages that may appear in the log file of the server-side application or in the browser interfaces of the applications. In addition, their possible causes are described and solutions proposed. Depending on the concrete infrastructure in which the affected application is operated, other causes and solutions may also need to be considered.

1. "PKIX path building failed"

Complete error message
sun.security.validator.ValidatorException:
 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This error message indicates that the certificate presented by the server for the HTTPS connection is not trusted by the JVM. It may be a self-signed certificate or the root certificate is not installed in the JRE.

Possible solutions:

  • Installing the root certificate in the JRE

  • Installing the server certificate in the JRE

  • If the requested server is controlled by the same organisation as the client: Provision of a new server certificate issued by a trusted CA on the requested server

2. "No name matching [requested.host.name] found"

Complete error message
javax.net.ssl.SSLHandshakeException:
 java.security.cert.CertificateException: No name matching maps.example.com found

This error message indicates that the host name used in the HTTPS request does not match the host name specified in the server certificate. The client (browser, Java application) compares the host name used in the request URL with the "CN" name of the "Subject" field in the server’s X509 certificate, e.g. https://maps.example.com/ with CN = www.example.com, O = Example LLC, L = Mountain Dew, ST = California, C = US.

If both names do not match (upper/lower case is not relevant), the connection will be aborted with the above error message. It is irrelevant whether the certificate would be classified as trustworthy or not. The trustworthiness check does not take place until the host names have been matched.

This problem often occurs when clients can address the same server with different names because several DNS entries exist. Especially if the client is in the same domain as the server, the inconsistent use of unqualified and fully-qualified host names in request URLs or server certificates often leads to this problem. Using the special host name localhost or IP addresses in URLs also causes this problem if the server certificate was issued on the qualified host name.

Possible solutions:

  • Use the host name in request URLs as specified in the server certificate.

  • Create and deposit a new server certificate for the host name desired by the client if, for example, it turns out that it does not make sense to use a host name (or localhost or IP address) that is not fully qualified.

  • Create and deposit a new server certificate with alternative host names ("Subject Alternative DNS Names") if, for example, it turns out that the server must inevitably be accessible under different host names.

3. "No subject alternative DNS name [requested.host.name] found"

Complete error message
javax.net.ssl.SSLHandshakeException:
 java.security.cert.CertificateException: No subject alternative DNS name matching maps.example.com found

This error message is a special case of the error message No name matching [requested.host.name] found, described under point 2 of this list. The only difference is that the server certificate has an additional field with alternative host names, but the host name used by the client does not correspond to the Subject CN of the server certificate, nor is it specified in the list of alternative host names ("Subject Alternative DNS Names").

Possible solutions: Similar to the suggested solutions for the error No name matching [requested.host.name] found.