This HOWTO describes the steps required to view and analyze Tor traffic in Wireshark.
It should be useful for researchers analyzing the behaviour of various versions of
the Tor client. This patchset will not allow you to decrypt the traffic of an Onion
Router (i.e. a relay node on the Tor network), only the traffic coming to and from
the Tor client on your machine (i.e. an Onion Proxy). Doing the former would require
a different patch to Tor and apart from being unethical might even be illegal in your
jurisdiction! (You would be snooping on the traffic of other Tor users.)
This README and all required files can be found at:
http://roberthogan.net/stuff/dissector/
If you find that any of the files referenced below do not exist anymore you should
inspect the URL above for the updated reference.
Contact details: robert at roberthogan.net
BUILD THE NECESSARY TOOLS
-------------------------
1. Patch Wireshark
This patch is very much a work in progress. The date stamp on the patch will likely
change over time so please be sure to check the parent directory if the link below
no longer works for you. Please let me know about any bugs you find.
- Download the wireshark patch:
http://roberthogan.net/stuff/dissector/patches/wireshark-tordissector-250710.diff
- Download wireshark svn:
svn checkout http://anonsvn.wireshark.org/wireshark/trunk wireshark
- Apply the patch:
cd /location/of/wireshark
patch -p0 < /location/of/wireshark-tordissector-250710.diff
- Build wireshark:
./autogen.sh
./configure
make
sudo makeinstall
2. Patch Tor
This is a modified version of a patch by Steven Murdoch. The patch logs the TLS
master keys used to TLS-encrypt traffic between your copy of Tor and other routers,
it also logs the AES keys used to encrypt relay cells passed along the circuits
created by your copy of Tor. Wireshark will use these logs to decrypt the TLS and
circuit streams it finds in the traffic captures you create later.
- Download the tor patch:
http://roberthogan.net/stuff/dissector/patches/0001-Add-compile-time-option-enable-highly-insecure-key-d.patch
- Download tor source:
git clone git://git.torproject.org/git/tor
- Apply the patch:
cd /location/of/tor
patch -p0 < /location/of/tor-dissector.diff
- Build tor (NOTE CONFIGURE PARAMETER BELOW!):
./autogen.sh
./configure --enable-highly-insecure-key-debugging
make
sudo makeinstall
CAPTURE AND DISSECT TOR TRAFFIC
-------------------------------
1. If you are impatient you can view the sample log and traffic capture at
http://roberthogan.net/stuff/dissector/examples/sampledump/
and skip to step 4.
2. Start The Traffic Capture
- sudo /location/of/svnwireshark/tshark -i eth0 -w /location/of/dump/test.dump
3. Start Tor
- /location/of/svntor/src/or/tor --SafeLogging 0 --Log info > /location/of/dump/torkeys.txt
4. Configure Wireshark.
- Open wireshark.
- Click Edit->Preferences.
- Expand the 'Protocols' line on the left hand side of the preferences dialog.
- Scroll down or type 'SSL' to go to the SSL preferences section.
- Paste the full path of the torkeys.txt file mentioned in step 2 above to
'SSL master keys list'.
e.g. /location/of/dump/torkeys.txt
See also:
http://roberthogan.net/stuff/dissector/examples/wireshark-ssl-config.png
- Click 'Apply'
- Scroll down or type 'Tor' to go to the Tor preferences section.
- Paste the full path of the torkeys.txt file mentioned in step 2 above to
'Tor cell keys list'.
e.g. /location/of/dump/torkeys.txt
See also:
http://roberthogan.net/stuff/dissector/examples/wireshark-tor-config.png
- Click 'OK' to save the settings and close the dialog.
5. View the capture.
- Open /location/of/dump/test.dump in wireshark.
- To view Tor data only, type 'tor' in the 'Filter' edit box on the top left and
click 'Apply'.
- You can now view the Tor traffic in your capture. For an idea of what you should
see, take a look at:
http://roberthogan.net/stuff/dissector/examples/wireshark-tor-dissector-1.png
- You can filter the view using most of the Tor protocol items. For example,
to view the destruction of circuits because of Tor protocol violations you can
type 'tor.destroyreason==0x04' in the 'Filter' edit box. The item name you should
use for each protocol item is visible on the bottom-left of the status bar when
you select that item. For example:
http://roberthogan.net/stuff/dissector/examples/wireshark-tor-dissector-destroyreason.png
ACKNOWLEDGEMENTS
----------------
Steven Murdoch for pointing out to me what I needed to do to get the AES-CTR decryption working.
Nick Mathewson for pointing out a number of flaws with my initial adaptation of Tor's AES-CTR
implementation.
Any remaining errors are very much my own.
from http://roberthogan.net/stuff/dissector/tordissector-README.txt
