Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

This page consists of an SSL error message troubleshooting reference followed by a discussion of SSL in Java that puts many of the solutions in context.

Troubleshooting SSL Errors

This section contains the most often-cited SSL errors reported by the CAS server and CAS clients in typical CAS integration scenarios.

PKIX path building failed

PKIX Example Stack Trace
Sep 28, 2009 4:13:26 PM org.jasig.cas.client.validation.AbstractCasProtocolUrlBasedTicketValidator retrieveResponseFromServer
SEVERE: javax.net.ssl.SSLHandshakeException:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
javax.net.ssl.SSLHandshakeException:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
      at com.sun.net.ssl.internal.ssl.Alerts.getSSLException(Unknown Source)
      at com.sun.net.ssl.internal.ssl.SSLSocketImpl.fatal(Unknown Source)
      at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Unknown Source)
      at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Unknown Source)
      at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(Unknown Source)
      at com.sun.net.ssl.internal.ssl.ClientHandshaker.processMessage(Unknown Source)
      at com.sun.net.ssl.internal.ssl.Handshaker.processLoop(Unknown Source)
      at com.sun.net.ssl.internal.ssl.Handshaker.process_record(Unknown Source)
      at com.sun.net.ssl.internal.ssl.SSLSocketImpl.readRecord(Unknown Source)
      at com.sun.net.ssl.internal.ssl.SSLSocketImpl.performInitialHandshake(Unknown Source)
      at com.sun.net.ssl.internal.ssl.SSLSocketImpl.startHandshake(Unknown Source)
      at com.sun.net.ssl.internal.ssl.SSLSocketImpl.startHandshake(Unknown Source)
      at sun.net.www.protocol.https.HttpsClient.afterConnect(Unknown Source)
      at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(Unknown Source)
      at sun.net.www.protocol.http.HttpURLConnection.getInputStream(Unknown Source)
      at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(Unknown Source)
      at org.jasig.cas.client.validation.AbstractCasProtocolUrlBasedTicketValidator.retrieveResponseFromServer(AbstractCasProtocolUrlBasedTicketValidator.java:35)
      at org.jasig.cas.client.validation.AbstractUrlBasedTicketValidator.validate(AbstractUrlBasedTicketValidator.java:178)
      at org.jasig.cas.client.validation.AbstractTicketValidationFilter.doFilter(AbstractTicketValidationFilter.java:132)
      at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)

PKIX path building errors are by far the most common SSL errors reported on the cas-user@lists.jasig.org mailing list. The problem here is that the CAS client does not trust the certificate presented by the CAS server; most often this occurs because of using a self-signed certificate on the CAS server. To resolve this error, import the CAS server certificate into the system truststore of the CAS client. If the certificate is issued by your own PKI, it is better to import the root certificate of your PKI into the CAS client truststore. See #Import Trusted Certificate for examples of importing a trusted certificate into a Java truststore.

No subject alternative names present

Sample Alt Name Stack Trace
javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names present

In most cases this is a hostname/SSL certificate CN mismatch. This commonly happens when a self-signed certificate issued to localhost is placed on a machine that is accessed by IP address. It should be noted that generating a certificate with an IP address for a common name, e.g. CN=192.168.1.1,OU=Middleware,dc=vt,dc=edu, will not work in most cases where the client making the connection is Java. For example the Java CAS client will throw SSL errors on connecting to a CAS server secured with a certificate containing an IP address in the CN.

HTTPS hostname wrong

Sample Wrong Host Name Stack Trace
ava.lang.RuntimeException: java.io.IOException: HTTPS hostname wrong:  should be <eiger.iad.vt.edu>
	org.jasig.cas.client.validation.Saml11TicketValidator.retrieveResponseFromServer(Saml11TicketValidator.java:203)
	org.jasig.cas.client.validation.AbstractUrlBasedTicketValidator.validate(AbstractUrlBasedTicketValidator.java:185)
	org.jasig.cas.client.validation.AbstractTicketValidationFilter.doFilter(AbstractTicketValidationFilter.java:132)
	org.jasig.cas.client.authentication.AuthenticationFilter.doFilter(AuthenticationFilter.java:102)

The above error occurs most commonly when the CAS client ticket validator attempts to contact the CAS server and is presented a certificate whose CN does not match the fully-qualified host name of the CAS server. There are a few common root causes of this mismatch:

  • CAS client misconfiguration (usually a bad serverName init param)
  • Complex multi-tier server environment (e.g. clustered CAS server)
  • Host name too broad for scope of wildcard certificate

Wildcard Certificates

JSSE support for wildcard certificates is limited to hosts strictly in the same domain as the wildcard. For example, a certificate with CN=*.vt.edu matches hosts a.vt.edu and b.vt.edu, but not a.b.vt.edu.

Simplified Java SSL Guide

The following guide attempts to distill the most important aspects of the Java Secure Socket Extension Reference Guide into a series of brief topics for consideration by CAS deployers. The following content should be considered a general guide with practical application to CAS through discussion and examples that are CAS-specific.

TODO: Write this content before or during the Spring Jasig Conference - MSA.

Keystore/TrustStore Reference

Import Trusted Certificate

By default the Java system truststore is at $JAVA_HOME/jre/lib/security/cacerts. The certificate to be imported MUST be a DER-encoded file. If the contents of the certificate file are binary, it's likely DER-encoded; if the file begins with the text -----BEGIN CERTIFICATE-----, it is PEM-encoded and needs to be converted to DER encoding. The following example demonstrates a conversion command using OpenSSL.

Convert PEM-encoded Cert to DER Encoding
openssl x509 -in etc/pki/incommon-root-cert.pem -out tmp/incommon-root-cert.der -outform DER

Once the certificate file is properly in the DER-encoded format, it may be imported using the keytool command.

Keytool Import Command
keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file tmp/incommon-root-cert.der -alias incommon

List Trusted Certificates

keytool -v -list -keystore $JAVA_HOME/jre/lib/security/cacerts

Alternatives to Sun keytool Utility

  • Portecle is a Java GUI tool that can handle all the keystore and certificate formats I've ever encountered. Very easy to use and recommended if you are uncomfortable with CLI tools.
  • keystore is a CLI tool that has a couple notable improvements on keytool:
    • Support for both PEM and DER-encoded files.
    • You can import a certificate/key pair directly into a keystore. (With keytool, keys never leave the keystore; you generate them, then a corresponding CSR, then import the matching certificate once it is issued.)

When All Else Fails

If you have read, understood, and tried all the troubleshooting tips on this page and continue to have problems, please perform an SSL trace and attach it to a posting to the cas-user@lists.jasig.org mailing list. An SSL trace is written to STDOUT when the following system property is set, javax.net.debug=ssl. An example follows of how to do this in the Tomcat servlet container.

Sample setenv.sh Tomcat Script
# Uncomment the next 4 lines for custom SSL keystore
# used by all deployed applications
#KEYSTORE="$HOME/path/to/custom.keystore"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStore=$KEYSTORE"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStoreType=BKS"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.keyStorePassword=changeit"

# Uncomment the next 4 lines to allow custom SSL trust store
# used by all deployed applications
#TRUSTSTORE="$HOME/path/to/custom.truststore"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStore=$TRUSTSTORE"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStoreType=BKS"
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.ssl.trustStorePassword=changeit"

# Uncomment the next line to print SSL debug trace in catalina.out
#CATALINA_OPTS=$CATALINA_OPTS" -Djavax.net.debug=ssl"

export CATALINA_OPTS
  • No labels