SunJSSE frequently asked questions

How can I debug the error `Exception in thread "main" javax.net.ssl.SSLHandshakeException: handshake failure`?

This error can be caused by attempting to use RACF® certificates with JSSE2 and specifying a null password when you load the RACFInputStream and the key manager factory. If this is the case, specify a password for the RACFInputStream and key manager factory then restart your application. If this action does not resolve your issue, determine the possible cause of the handshake failure by getting trace data for the SSL handshake. To capture the trace for the SSL handshake, specify the javax.net.debug=all option when you run your application. This option causes trace data to be printed to stdout. To capture the data, redirect the output to a trace file, as shown in the following example:

java -Djavax.net.debug=all MyTest >MyTest_trace.log 2>&1

How can I debug a RACF certificate problem on z/OS?

When you debug a RACF problem, the first step is usually to list the Java™ keystore that represents the RACF key ring in Java code. The following examples show a single command spread over multiple lines for readability; you should enter each as a single command.

The following example shows how to list the keystore if you are accessing the RACF key ring as a JCERACFKS keystore and redirecting the output to a file (keystore_list.log):
```
keytool -debug -list -storetype JCERACFKS 
-keystore safkeyring://OwningUserID/KeyringName 
-J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider
>keystore_list.log 2>&1
```

The following example shows how to list the keystore if you are accessing the RACF key ring as a JCECCARACFKS keystore and redirecting the output to a file (keystore_list.log):

hwkeytool -debug -list -storetype JCECCARACFKS 
-keystore safkeyring://OwningUserID/KeyringName 
-J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider
>keystore_list.log 2>&1

If you suspect a RACF key ring setup problem, list the key ring then list each entry in the key ring by using the RACF command-line utility RACDCERT. The following example shows how to list the key ring:

RACDCERT LISTRING('OwningUserID.KeyringName')

The following example shows how to list the entry with the MyCert label :

RACDCERT LIST(LABEL('MyCert'))

If more information is needed to diagnose the problem, you can turn on tracing in the Java code that handles the RACF key ring. The following example shows how to get this trace and redirect the output to a file (MyTest_trace.log):

java -Djavax.net.debug=all -Djava.security.auth.debug=ibmjceracf MyTest >MyTest_trace.log 2>&1

How can I debug a hardware problem?

If you suspect a problem that is related to the hardware, the trace data that you provide for the IBM service team should include tracing for both the IBMJCECCA provider and for SSL. The following example shows how to get this trace and redirect the output to a file (MyTest_trace.log):

java -Djavax.net.debug=all -Djava.security.auth.debug=all MyTest >MyTest_trace.log 2>&1

What does the `javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: End user tried to act as a CA` error mean?

This error occurs when a handshake is done and the CA certificate that is used for authentication does not have the basicConstraints extension turned on in the CA certificate. In general, when you create certificates you must turn on the CA basicConstraints extension. In RACF, create the CA certificate with the syntax RACDCERT CERTAUTH .... so that the basicConstraints extension is included with the CA parameter set to true and the PathLen parameter set to a nonzero value that is appropriate for the certificate chain.

What does it mean when I get an EOF error after the client hello is sent on the client side?

This problem was seen in WebSphere® when JSSE2 was communicating with a System SSL server and the System SSL server did not have a key ring that contained a private key.

What does it mean when I get `certificate verify message error` on one side and a `bad_certificate` error on the other side?

This error usually means that the unrestricted policy files are needed for the operation that is being attempted. For more information about security policy files, see SDK Security policy files.

What information should I collect before I contact the IBM service team with a problem that is related to SunJSSE?

You might reduce the time that is taken to resolve your problem if you include the results of the following command in your case:

java -version

If the service team cannot resolve your issue from your description of the failing scenario and the symptoms of the failure, get trace data for the failure. To capture the trace for the SSL failure, specify the javax.net.debug=all option when you run your application. This option causes trace data to be printed to stdout. To capture the trace data, redirect the output to a trace file. The following example shows how to get an SSL trace:

java -Djavax.net.debug=all MyTest >MyTest_trace.log 2>&1

If the trace is needed, the service team will give you instructions on how to transmit it.