TorTA version 0.02 ($Id: README 1401 2005-10-11 20:29:32Z sjm217 $)

TorTA is a set of programs based on those developed for the paper
"Low-cost Traffic Analysis of Tor":
 http://www.cl.cam.ac.uk/users/sjm217/papers/oakland05torta.pdf

There are two pairs of programs:
 "sender" sends probe packets to "receiver" and
   measures the latency
 "evil_server" sends data to "victim" in a pattern, hopefully
   altering the latency of any probe packets on nodes which share a
   path with the target stream.

The sender and receiver pair use a "password" to prevent portscans or
other spurious network traffic from causing problems. This is not
intended to prevent malicious interference and the password is sent
unencrypted, so do not use a password that is in use for other
purposes.

These are at a very early stage of development so there are likely to
be bugs and there is little documentation. If you have any problems or
questions, then please see my contact details here:
  http://www.cl.cam.ac.uk/users/sjm217/#contact

The programs connect to TCP sockets directly and do not use SOCKS. To
interface with Tor, a program to make the SOCKS connection is required,
such as "socat":
 http://www.dest-unreach.org/socat/

The log format is designed to be easy to use with GNU R
(http://www.r-project.org/), however it is simple enough to be easily
converted into different formats.


The programs are distributed under the GPL version 2 or later (see
the included file, COPYING).

If these programs are used in the course of producing a publication, I
would appreciate it if you would cite the associated paper:
  Steven J. Murdoch and George Danezis. 
   "Low-cost traffic analysis of Tor".
    In IEEE Symposium on Security and Privacy. IEEE CS, May 2005.

Here is suitable BibTeX for LaTeX users:
@inproceedings{torta05,
  title = {Low-Cost Traffic Analysis of {Tor}}, 
  author = {Steven J. Murdoch and George Danezis}, 
  booktitle = {Proceedings of the 2005 IEEE Symposium on Security and Privacy}, 
  year = {2005}, 
  month = {May}, 
  publisher = {IEEE CS}, 
}


Compilation
===========

The programs were developed on Redhat Linux 9.0 and should compile on
most Unix-like systems.

To build them, run:
 make all
which should result in the following files:
 victim evil-server receiver sender

There is no installation script; copy them to a location on your PATH
to use them, or invoke them with a full path (e.g. ./victim)


Usage
=====

sender
------

Usage: sender HOSTNAME PORT BLOCKSIZE SLEEP PASSWORD

 Send latency probes to "receiver" running on another host

 HOSTNAME:  Hostname of the machine running "receiver"
 PORT:      Port that "receiver" is listening on
 BLOCKSIZE: Size that timing records should be padded to
 SLEEP:     Time to wait between sending probes (in seconds)
 PASSWORD:  Password to be sent to "receiver"

 The password and blocksize of sender and receiver must be identical.

 sender continually sends blocks with the current time stored in
  them; receiver will then receive each block and log the time stored
  in the block, along with the time that the block was received.
 
 For the latency results to be accurate, sender and receiver must have
  closely synchronised clocks, or more usually, be the same machine.

receiver
--------

Usage: receiver PORT BLOCKSIZE DATAFILE PASSWORD

 Receive latency probes from "sender" and log timings to a file

 PORT:      Port to listen on
 BLOCKSIZE: Size that timing records are padded to
 DATAFILE:  File to write logging information to
 PASSWORD:  Password expected from "sender"

Log file format:

 1st line:        "ssec susec rsec rusec\n"
 Following lines: send_time (sec) send_time(usec) receive_time(sec) \
                   receive_time(usec)\n

Times are split into the integral part (ssec/rsec) and fractional part
(susec,rusec). The fractional part is expressed in microseconds, as
with the data type "struct timeval" used in gettimeofday(), which is
where the time values are taken from. This allows 32 bit integer
arithmetic to be used for further processing.

Latency (in microseconds) can be calculated by the following expression:

 latency = ((rsec-ssec) * 1,000,000) + (rusec-ssec)

evil-server
-----------

Usage: evil-server PORT DATAFILE SEED REPEAT MINTIME MAXTIME SLEEPFACT

 Send patterns of data to a client so as to trace them

 PORT:      Port to listen on
 DATAFILE:  File to write logging information to
 SEED:      Seed for pseudorandom number generator
 REPEAT:    Number of chunks of data to send
 MINTIME:   Minimum duration of a chunk (seconds)
 MAXTIME:   Maximum duration of a chunk (seconds)
 SLEEPFACT: Factor that wait durations are longer than chunk durations
             (on average)

Log file format:

 1st line:        "t\n"
 Following lines: start_time(sec)\n
                  stop_time(sec)\n

victim
------

Usage: victim HOSTNAME PORT BLOCKSIZE FILENAME

 Connect to a server, receive data and log results

 HOSTNAME:  Host to connect to
 PORT:      Port to connect to
 BLOCKSIZE: Size of block to accept at one time
 FILENAME:  File to writing logging information to

Log file format:

 1st line:        "sec usec bytes\n"
 Following lines: "recv_time(sec) recv_time(usec) num_bytes\n"

Times are split into the integral part (sec) and fractional part
(usec). The fractional part is expressed in microseconds, as with the
data type "struct timeval" used in gettimeofday(), which is where the
time values are taken from. This allows 32 bit integer arithmetic to
be used for further processing.

The time (in microseconds since the Epoch) that a block was received
can be calculated by the following expression:

 time = (sec * 1,000,000) + usec

Example
=======

Measure the latency of a circuit from PROBE, through Tor and back to
PROBE.

I am assuming Tor is running on localhost and its SocksPort is 9050

On PROBE
# Set Socat to listen on port 4202 and forward connections to Tor. Tor
#  is requested to connect to PROBE, port 9002
$ socat TCP4-LISTEN:4202,fork,reuseaddr \
   SOCKS4A:localhost:PROBE:9002,socksport=9050

# Run the probe receiver, listening on port 9002, with a blocksize of
# 16, logging results to "probelog.data" and expecting the password
# "geheim"
$ receiver 9002 16 probelog.data geheim

# Run the probe sender, connecting to Socat running on localhost:4202,
# with a blocksize of 16, sending 5 probes per second
$ sender localhost 4202 16 0.2 geheim

---

To send a target stream from EVIL to VICTIM.

I am assuming that VICTIM has Tor running on localhost with SocksPort
9050

On EVIL:
# Run the server, listening on port 9002 and logging results
#  to evillog.data with PRNG seed 42, sending 6 chunks, each between 10
#  and 25 seconds long, sleeping in between on average 3 times as long 
$ evil_server 9002 evillog.data 42 6 10 25 3

On VICTIM:
# Set Socat to listen on port 4202 and forward connections to Tor. Tor
#  is requested to connect to EVIL, port 9002
$ socat TCP4-LISTEN:4202,fork,reuseaddr \
   SOCKS4A:localhost:EVIL:9002,socksport=9050

# Run the client, connecting to Socat on localhost:4202, using a 512
#  byte block and logging results to victimlog.data
$ victim localhost 4202 512 victimlog.data


License
=======

TorTA: Perform traffic analysis experiments on Tor

Copyright (C) 2005 Steven J. Murdoch <http://www.cl.cam.ac.uk/users/sjm217/>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

