Trouble Shooting

Developing and testing SSL programs could be quite frustrating for beginners. It would seem the program compiles properly, everything is set up the right way and still nothing works. It takes, even for experience programmers, some amount of detective work to figure out what is wrong. Let us look at what goes wrong.

System properties are not set properly. So much behavior of JSSE APIs is governed by system properties is that even a minor mistake, like a typographical error or use of the wrong keystore or truststore file, may cause things go haywire. So, when your program is having trouble, recheck the system property names and their values.

There is no common cipher suite between the client and the server. This is rare when both ends are Java programs, running with the same JSSE implementation. However, with independent client and server programs, this is a real possibility. I spent many frustrating hours trying to figure out why a Java HTTPS server program was not working with a Netscape 7.0 browser. It turned out that the server certificate was using a DSA algorithm and there was just no common cipher suite between the two ends. Changing the key algorithm to RSA solved the problem.

Non-interoperable implementation. The interoperability has significantly improved with SSLv3 and TLSv1, but still, if you are working with less frequently used implementations, it is quite possible to encounter non-interoperable implementations.

There is a firewall between communicating ends. A firewall may disallow communication using certain port numbers. We talked about how to get around Web-proxy based firewalls, but not all firewalls are so friendly. In such cases, if you have a genuine business need to cross the firewall, you should talk to your network administrator. Going by my personal experience, this could be quite frustrating, especially in large companies.

Certificate validation fails. Even if everything is all right, it may happen that the certificate validation itself fails. Maybe the truststore doesn't have the certificate of the CA that signed the certificate under validation. Or perhaps the certificate is expired. Look at error messages carefully to determine the cause of failure.

The JSSE implementation is different from the one that comes with J2SE v1.4. A number of settings we have covered in this chapter are quite specific to the JSSE provider that comes with J2SE v1.4. If you are working with a different implementation, you should consult the relevant documentation for an appropriate configuration.

What trouble-shooting tools are available to a Java programmer to identify the cause of the errant behavior? At the minimum, you can set the system property javax.net.debug to an appropriate value. This generates log messages on the screen that might give important clues to what is going wrong. To get a listing of all the possible values this system property might be set to, run a SSL-aware program with this system property set to help. Here is the output shown by running the ShowCipherSuites program with the javax.net.debug set to help:

C:ch6ex1>java -Djavax.net.debug=help ShowCipherSuites

all            turn on all debugging
ssl            turn on ssl debugging

The following can be used with ssl:
        record       enable per-record tracing
        handshake    print each handshake message
        keygen       print key generation data
        session      print session activity
        defaultctx   print default SSL initialization
        sslctx       print SSLContext tracing
        sessioncache print session cache tracing
        keymanager   print key manager tracing
        trustmanager print trust manager tracing

        handshake debugging can be widened with:
        data         hex dump of each handshake message
        verbose      verbose handshake message printing

        record debugging can be widened with:
        plaintext    hex dump of record plaintext

A good way to get comfortable with these options is to deliberately introduce error conditions and browse the output generated.