howto

How to use JSSLTrace

What is this thing for ?

As you could have already guessed from the name, jssltrace is a tool, which intercepts and traces the ssl traffic between a client and a server. Of course before it do it't job, it decrypts the traffic, so the user can see the "plain-text" contents of the conversation. It can be very useful if you have a ssl-using client/server software, which refuses to work and you need to look into the communication of both parts in order to find out what is missing.

How it works ?

Before you read this, please make youself familiar with ssl basics.

Jssltrace acts as the famous man in the middle - it sits between the client and the server, intercepts their traffic, decrypts it, and prints it to a text file, so you are able to see the decrypted content. Here is an example of how it works:
Let's assume, you would like to intercerpt the communication between your web browser and a webserver which uses ssl. Let's say the DNS name of the server is www.yourserver.com.
The first thing is, of course, to configure and start the jssl trace, so that it now listens on the port 443 (ssl port) ready to accept requests from your browser and forward the data to www.yourserver.com and back. After having done it, start jssltrace.
Now manipulate your computer so that when the webbrowser asks for the ip address of www.yourserver.com it will get not it's real address but 127.0.0.1, that is, your own computer. The best way to do it is to put the corresponding entry into the hosts.txt file on your computer. This way, when your call up the URL https://www.yourserver.com in your browser, the browser will connect to jssltrace instead of the original server. Unfortunately, if you try it just now, your browser will show you an error page saying that the server you have called up, uses an invalid certificate. This is absolutely correct too, jssl trace does indeed use an invalid certificate or rather a certificate signed by a certificate authority (CA in ssl parlance), which is unknown to your browser. So the last step is to take the CA's certificate used by jssltrace and install it in your browser so that the browser accepts it as a valid CA. Which CA you use is free configurable with jssltrace, but usually you will use the one from the security folder in the jssltrace's installation directory (ca_certificate.crt). After you have installed the certificate, the browser will accept all server certificates signed by this CA as valid.
That was all you had to do. Call the URL https://www.yourserver.com again, and this time the browser will not complain. Browse a bit and then look into the traces directory, which is, again, free configurable configurable with jssltrace but usually will be the trc folder in the jssltrace's installation directory. You wil find there some .txt files (one for every ssl connection between your browser and www.yourserver.com via jssltrace), which will contain the encrypted ssl data.

What happens "under the hood"

The last section and the Installation and configuration contain between them enough infos to get jssltrace up and running. But if you would like to know how jssltrace achieves it's "magic", here follows the detailed explanation, based on the example from the last section:
Let's assume, you have followed the instructions from the the last section, jssltrace is waiting for the connection from your browser and you are just about to invoke the start url https://www.yourserver.com. After you have invoked it, following things happen (stylized decription):

• You browser establisches a tcp connection to jssltrace (remember, you have manipulated the hosts.txt, that is why).
• It starts the ssl handshake and asks jssltrace for the valid server certificate for the host name www.yourserver.com.
• Jssltrace in turn establishes a tcp connection to the original server and starts the ssl handshake asking the server for his certificate.
• Jssltrace receives the server's certificate and completes the handshake with the server. Now it has established a ssl connection with the server.
• Jssltrace takes the certificate received in the last step from the server and generates a new certificate with the same attribute values but signed by his own, configured, certificate authority. This new certificate it sends to the browser.
• The browser accepts the certificate, because you have installed jssltrace's CA as valid CA, and completes the handshake. Now there is a ssl connection between the browser and jssltrace too.
• The browser sends his first http request through the just established ssl connection to jssltrace which forwards it to the server. The server responses and jssltace sends the response data to the browser. The same happens with the following requests/responses and in the process jssltrace writes their contents to a trace file.
• Usually your browser will establish multiple ssl connections with jssltrace, which in turn will create for each of them a corresponding connection with the original server. For each of these "conversations" the will be an extra trace file.

Additional Features

There are, apart from the basic functionality described above, additional features, which can be useful in some usage scenarios. Here follows the list, which will be updated with every new version of JSSLTrace.

• Client authentication
• Support for HTTP proxies
• Plain TCP on the client side
• Web Console