Post on 03-Apr-2018
transcript
7/29/2019 Wa Tomcat PDF
1/16
Copyright IBM Corporation 2009 Trademarks
Configuring Tomcat and Wireshark to capture and
decode SSL communications
Page 1 of 16
Configuring Tomcat and Wireshark to capture
and decode SSL communications
Debugging secure communications
Dominic Tulley (dominic.tulley@uk.ibm.com)
Leading Architect, DOORS Development Lab
IBM
Skill Level: Introductory
Date: 03 Nov 2009
Investigating client-server communication issues is troublesome at the best of
times, and when the communication is secured with SSL, it becomes much more
difficult. This tutorial takes you through the steps involved in configuring Tomcat
and Wireshark so that the SSL Dissector in Wireshark can decrypt the captured
communication. This allows your investigation to proceed as if SSL was not
involved.
Section 1. Before you start
Developing a system that involves network communication is extremely common in
todays distributed world. During the development of such a system, a communication
problem may arise that is difficult to investigate by instrumenting or debugging your
software. At times like this, you can turn to a tool like Wireshark, which captures
all the network traffic in your system and lets you read it. This often provides
the insight required to resolve your problem. If your system uses SSL to secure
communications, then you can capture the network traffic, but it is all encrypted,
preventing you, the developer, from gaining any useful information. Fortunately,
Wireshark comes with an SSL Dissector that, given the right set of conditions, can
decrypt this captured traffic. This tutorial provides a step-by-step guide to setting up
those conditions using Tomcat as the server and a Web browser as the client.
Objectives
By the end of this tutorial you will have an understanding of the various conditions
that must be met before the Wireshark SSL Dissector can be used. Furthermore, you
will be able to arrange for those conditions to be met in a Tomcat installation.
http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlmailto:dominic.tulley@uk.ibm.comhttp://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtml7/29/2019 Wa Tomcat PDF
2/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 2 of 16
Prerequisites
It is assumed that you have a basic understanding of network communication
mechanisms. You dont need to have experience with Tomcat or Wireshark, although
both would be advantageous. In particular, this tutorial does not go into any depth
about how to use Wireshark once it has been configured correctly.
Please note: This tutorial is not intended to provide any significant insight into why
this set of commands works, nor to give any consideration to the many possible
variations on these commands. It is intended to enable you to record and decode
network traffic in a development environment. It is important to note that the
procedures followed here and some of the cryptographic artifacts generated here are
very insecure and should never be applied to a production environment.
System requirements
This tutorial assumes you are using Windows. To follow this tutorial you will need toinstall the following (see Resources for download sites):
Tomcat 5.5
A suitable JVM for Tomcat
Wireshark Version 1.2.2 was used in the development of this tutorial. The
Wireshark download mustbe compiled with GnuTLS and Gcrypt. This can be
checked in the "About" window of Wireshark.
Cygwin including openssl Version 0.9.8i of openssl was used in the
development of this tutorial.
Jetty Version 6.1.21 was used in the development of this tutorial. Otherversions (newer and older) may work, but the location of the required class file
within it may have changed.
In addition, you will need a second machine on which you will use a Web browser to
access your Tomcat server.
Overview
The following key conditions must be met to allow Wireshark to decrypt a secure
connection:
Tomcat must be configured with a server certificate.
The specific cryptographic cipher used between client and server (browser and
tomcat) must be amenable to Wiresharks method of decrypting.
Wireshark must have access to the private key associated with the server
certificate.
This tutorial will work through these steps in this order and then, using a browser
connecting to the Tomcat server, we will capture a request and response and
examine it in Wireshark.
7/29/2019 Wa Tomcat PDF
3/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 3 of 16
A note on passwords
Through this tutorial you will be asked to define three separate passwords. Each
password is carefully named and referred to in the tutorial, but to make life easier,
you might like to consider using the same password in all three places.
Section 2. Create a private key and certificate
First I will show you how to create a new private key using openssl. Start Cygwin and
execute the following command:
openssl genrsa -des3 -out ./serverkey.pem 2048
You will be asked to provide a pass phrase for the generated pem file. I will refer to
this pass phrase as later in this tutorial. After providing
and verifying this pass phrase, the command will complete and a new private key will
have been generated and stored in the file serverkey.pem.
Now execute the following command (note the command should all be on one line;
it's not on one line here due to tutorial template restrictions):
openssl req -new -x509 -key ./serverkey.pem -out ./servercert.pem -subj
'/C=GB/ST=XX/O="My Org"/CN="Wireshark dissectable Cert"'
You will be prompted to supply a pass phrase at this point, and you should enter the you selected earlier. This results in a server certificate
stored in servercert.pem which corresponds to the private key you previously
generated.
Convert certificate to JKS keystore
The server certificate that you generated in the previous step is unfortunately not in
the format that Tomcat requires, so you must convert it to be in a JKS keystore. The
first step is to change it to the PKCS12 format with the following command (to be run
in Cygwin):
openssl pkcs12 -export -in ./servercert.pem -inkey ./serverkey.pem
-certfile ./servercert.pem -out ./servercert.p12 -name "cert-name"
This will again prompt for a pass phrase, and you should provide the . It will then prompt for a newpass phrase which I will refer to as the
later in this tutorial. After entering and verifying this new
pass phrase, the command should complete and a new file, servercert.p12, will
have been created.
7/29/2019 Wa Tomcat PDF
4/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 4 of 16
Next, we make use of a utility included in the Jetty distribution to convert this
certificate into a JKS keystore. Different versions of Jetty may have this class in
different jar files, or even under different packages in the distribution. In the Jetty
6.1.21 distribution the required class is present in the main jetty-6.1.21 jar in the
org.mortbay.jetty.security package. The command to execute (assuming this jar
file is in the current directory) is:
java -classpath ./jetty-6.1.21.jar org.mortbay.jetty.security.PKCS12Import
./server.p12 ./dissectable.keystore
This will first prompt for the input keystore pass phrase. This is the you selected earlier. You will then be asked to select a new pass phrase
for the new keystore. I will refer to this later as the . Note
that you are not asked to confirm this pass phrase so you must be careful to type
correctly.
Note: If you are not using precisely the same version of Jetty, you may find that thePKCS12Import class is in a different jar file or even under a different package.
Unprotecting the private key
The final piece of work with openssl is to remove the pass phrase being used to
protect your private key. This is necessary so that Wireshark can read the key file
correctly. In cygwin, the following command will remove the pass phrase protection
from the key file:
openssl rsa in ./serverkey.pem out ./open-private-key.pem
This command will prompt you for a pass phrase. You should enter the you selected earlier. This command will result in a new file, open-
private-key.pem, which contains an unprotected copy of your private key.
Section 3. Configure Tomcat
Now that you have the cryptographic artifacts that you need, you can configureTomcat to use them. There are three configuration steps you must complete:
Copy the dissectable.keystore into the Tomcat root directory.
Tell Tomcat to use the server certificate you have constructed.
Restrict the set of ciphers to those that Wireshark can cope with.
The last two actions are achieved by editing the same file. Within the Tomcat
installation, navigate to the conf directory and edit the server.xml file. Locate the
section of the file that defines the SSL connector, as shown in Listing 1:
7/29/2019 Wa Tomcat PDF
5/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 5 of 16
Listing 1. Default SSL connector definition
Remove the second line and the last line so that the xml looks like the code in Listing
2.
Listing 2. Uncommented SSL connector definition
Then modify the connector element to include the text in bold below. This assumes
that you copy your dissectable.keystore file to the Tomcat installation root directory
(the same place as the LICENSE and NOTICE files). Where it says "password
here" in the example below, you should enter the you
selected earlier.
Listing 3. Modified SSL connector definition
7/29/2019 Wa Tomcat PDF
6/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 6 of 16
keystoreFile="dissectable.keystore"
keystorePass="password here"
ciphers="SSL_RSA_WITH_RC4_128_SHA,
TLS_RSA_WITH_AES_128_CBC_SHA,
SSL_RSA_WITH_3DES_EDE_CBC_SHA"
/>
Verify the Tomcat configuration
At this point it is worth verifying that Tomcat has been configured correctly. To do this,
simply run the startup.bat script in the bin directory. If you have configured everything
correctly and copied the dissectable.keystore file to the correct location, then Tomcat
will start up with no errors.
If Tomcat does not start correctly, either with errors on the screen or with it simply
failing, then you should double check that the xml edits you have made do not have
any typos and that the keystore file is in the correct location.
Once Tomcat has started you can verify that the SSL connection is functioning by
starting a Web browser and navigating to https://localhost:8443/. This will initially
complain about the server certificate and ask you if you wish to trust the server. (The
precise terminology varies depending on which browser you use.) This is caused by
the self-signed certificate you created earlier, and you should respond that you do
trust the server. You should then see the Tomcat welcome page, which means that
you have correctly configured Tomcat to support secure connections.
Section 4. Configure Wireshark
Now that you have Tomcat configured, you need to configure Wireshark. To do this,
start up Wireshark on the machine that you run Tomcat on and in the menus, select
Edit --> Preferences (Ctrl-Shift P).
7/29/2019 Wa Tomcat PDF
7/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 7 of 16
Figure 1. Wireshark preferences screen
Expand the Protocols entry on the left side and select SSL from the list that
appears.
Figure 2. Wireshark SSL configuration dialog
Options boxes
You should check both of the options boxes.
RSA keys list
The RSA key list field tells Wireshark which private key to use to decode
conversations depending on which IP address and port the conversation is with. The
format is:
7/29/2019 Wa Tomcat PDF
8/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 8 of 16
IPAddress,Port,Protocol,PrivateKey
Multiple entries can be provided in a semicolon-separated list as shown here, but for
this tutorial we only require one entry.
IPAddress1,Port1,Protocol1,PrivateKey1; IPAddress2,Port2,Protocol2,PrivateKey2
For the purposes of this tutorial I assume the IP address I am running Tomcat on is
192.168.45.22, and it is listening on port 8443 for SSL traffic. The traffic will be HTTP
traffic, and the open-private-key.pem file that we generated earlier has been copied
to the root of the C drive. For this, the string to enter in the RSA keys list field is:
192.168.45.22,8443,http,c:\open-private-key.pem
You will need to identify the IP address of your own machine. In Cygwin you can do
this by running:
ipconfig /all
Note: If your machine has multiple network adapters, you may have more than one
IP address for the machine. You must choose the address with which your second
machine can connect to this machines Tomcat server.
SSL debug file
You should provide a filename where Wireshark can produce debug output. This will
be very useful in troubleshooting your Wireshark configuration.
Complete the configuration
Press OK to complete the configuration.
Verify the configuration
You should now open the SSL debug log file that you selected earlier. If your
configuration was successful you will see some text indicating that Wireshark
successfully loaded the private key. See an example below in Listing 4.
Listing 4. SSL debug log contents
ssl_association_remove removing TCP 9443 - http handle 040820A0ssl_init keys string:
9.175.228.55,8443,http,C:\temp\open-private-key.pem
ssl_init found host entry 9.175.228.55,8443,http,C:\temp\open-private-key.pem
ssl_init addr '9.175.228.55' port '8443' filename 'C:\temp\open-private-key.pem'
password(only for p12 file) '(null)'
Private key imported: KeyID 0E:BA:EA:08:5D:FA:FB:85:59:4A:7B:A9:B2:56:C3:16:...
ssl_init private key file C:\temp\open-private-key.pem successfully loaded
association_add TCP port 8443 protocol http handle 040820A0
This confirms that you have carried out all the cryptographic manipulation steps and
Wireshark configuration steps correctly. If you dont see this message you need to
7/29/2019 Wa Tomcat PDF
9/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 9 of 16
revisit the steps involved. The mostly likely problems have to do with the path to the
key file in the RSA keys list or the actual generation of the private key file.
Capture a conversation
Once you have Wireshark configured correctly, you are ready to record aconversation. In Wireshark, select Capture --> Interfaces (Ctrl I -- upper case i) from
the menu. This should present a dialog similar to the following:
Figure 3. Wireshark interface listing dialog
You need to decide which of the listed network interfaces is the one that your second
machine will connect to Tomcat through. This should already be clear since you
needed to know the right IP address for the Wireshark configuration step. If you are
unsure, you can use the Web browser on the second machine to access the Tomcat
server and see which interface shows an increased packet count.
Once you have selected the interface you want to listen on, click options and you
should be presented with another dialog:
7/29/2019 Wa Tomcat PDF
10/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 10 of 16
Figure 4. Wireshark capture options dialog
You should enter the following in the Capture Filter to reduce the amount of noise in
the captured conversation:
tcp port 8443
Now click Start to begin capturing traffic. At this point you should not see any packets
being captured. You should go to your second machine and access Tomcat with
it using a url such as https://192.168.45.22:8443/, but putting in the IP address or
hostname of the machine that has Tomcat on it. When you do this, you will be told
that there is a certificate problem and asked if you trust the server. As before, youshould confirm that you do trust the server. After this, the Tomcat welcome page
should appear in the browser and lots of rows of data should appear in Wireshark.
You can now stop the capture by selecting Capture --> Stop from the menu.
If you have done this correctly, you will see a screen with some green rows, showing
that they have been decrypted, like this:
7/29/2019 Wa Tomcat PDF
11/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 11 of 16
Figure 5. Successful capture output
You are then free to use Wireshark as you normally would to analyse the HTTP
conversation and proceed with your problem investigation.
One final thing to observe here is that if you would normally use follow tcp stream tosee an HTTP conversation, you should now use follow ssl stream instead. This will
show your HTTP conversation in plain text:
7/29/2019 Wa Tomcat PDF
12/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 12 of 16
Figure 6. Following an SSL stream
Out of order packets
It is possible that you can encounter Out of Order packets as part of your capture, as
shown here:
7/29/2019 Wa Tomcat PDF
13/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 13 of 16
Figure 7. Out of order packets in Wireshark
These can cause the SSL Dissector to partially fail. Observe that there is a green
row near the bottom but the response to that GET has not been decrypted. To fix this
problem you need to save this capture using File --> Save As. Then, in Cygwin you
need to run editcap d capture.pcap fixed.pcap , where editcap is included inthe Wireshark installation, capture.pcap is the saved capture file, and fixed.pcap will
contain the fixed capture after the command has run. After running this command you
can load the fixed packet capture file back in to Wireshark and then you should see
the decrypted packets as expected.
No green rows at all
Wireshark relies on capturing the entire SSL conversation. If you make multiple
requests from your browser over the course of this tutorial it can be that some parts
of the negotiated secure connection are cached and then the captured conversation
does not contain the full negotiation. This will prevent the SSL Dissector from doingits job. Look at the start of the capture for an entry with "Server Hello, Certificate,
Server Hello Done" in the info line. If you cannot find this, then your browser is
reusing part of a previous negotiation. Restarting the browser and trying again should
fix this.
Section 5. Conclusion
7/29/2019 Wa Tomcat PDF
14/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 14 of 16
In this tutorial you have learned how to capture and read a secure HTTP
communication between two systems. You have seen how to generate the required
cryptographic artifacts and then how to configure Tomcat and Wireshark to use them
correctly. The steps involved are not complex, and, with some familiarity, can be
performed very easily. This is a very powerful tool in todays world of secured and
distributed systems, although hopefully one that is not required very often.
This mechanism has been demonstrated in the context of a Web browser connecting
to a Tomcat server, but it can easily be applied to any system communicating with
Tomcat over SSL. With some further investigation, the procedure here should be
applicable to other servers with relative ease.
7/29/2019 Wa Tomcat PDF
15/16
ibm.com/developerWorks/ developerWorks
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 15 of 16
Resources
Download Tomcat 5.5 from the project Web site.
Download a suitable JVM for Tomcat.
Download Wireshark from the project Web site.
Download Cygwin from the project Web site.
Download Jetty from the project Web site.
The Wireshark Web site has online documentation and a very helpful set of
mailing lists that can quickly help you improve your ability to analyze packet
captures.
This documentation includes more details on configuring the SSL Dissector
within Wireshark.
Check out My developerWorks: Find or create groups, blogs, and activities
about Web development or anything else that interests you.
https://www.ibm.com/developerworks/mydeveloperworks/http://wiki.wireshark.org/SSLhttp://wiki.wireshark.org/SSLhttp://www.wireshark.org/lists/http://www.wireshark.org/http://docs.codehaus.org/display/JETTY/Downloading+Jettyhttp://www.cygwin.com/http://www.wireshark.org/download.htmlhttp://www.ibm.com/developerworks/java/jdk/http://tomcat.apache.org/download-55.cgi7/29/2019 Wa Tomcat PDF
16/16
developerWorks ibm.com/developerWorks/
Configuring Tomcat and Wireshark to capture anddecode SSL communications Page 16 of 16
About the author
Dominic Tulley
Dominic Tulley has more than ten years experience working in server-side Java development, including the intricacies of client-server
communication. He is a leading software architect within the IBM
DOORS Development lab.
Copyright IBM Corporation 2009
(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)
http://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtml