  TempCov: Toolkit for investigating temperature covert channels
           
  Version: 0.01; 25 Dec 2006

  Author: Steven J. Murdoch <http://www.cl.cam.ac.uk/~sjm217/#contact>

For background to this code, see the paper

 "Hot or not: revealing hidden services by their clock skew":

  <http://www.cl.cam.ac.uk/~sjm217/papers/ccs06hotornot.pdf>

$Id: README 1401 2005-10-11 20:29:32Z sjm217$

Usage
=====

Example data for two runs is included: run4b and run6b. The rule
"make all" will draw the default graph from this data.

To generate your own data, edit the variables above the exampleXs0.pdf
rule and invoke "make run". To stop the monitoring process, invoke
"make stop". This will produce _icmp_ and _tcp_ files which can be
graphed by the exampleXs0.pdf rule.

See the comments for more details. A good place to start is the
Makefile since this shows how all the components fit together.

Contents
========
README.txt .......... This file
COPYING ............. Copy of the GPL

Makefile ............ Makefile showing how everything fits

plot_offset_skew.R .. Generate graphs from clockskew data
example.R ........... Shows how plot_offset_skew.R should be invoked
common.R ............ Common functions for clockskew estimation
util.R .............. General purpose utilities

dpkt-1.6 ............ dpkt library, needed for probe-receiver.py
pypcap-1.1 .......... Modified pypcap library, needed for probe-receiver.py
pypcap.patch ........ Modifications which were applied to pypcap
scapy.py ............ Scapy library, needed for probe-sender.py

probe-receiver.py ... Send ICMP and TCP probes
probe-sender.py ..... Record probe response and receipt time

run*_burn.data ...... Times when load on the target was induced
                      S; <start time> \n E; <end time>
run*_icmp_*.data .... ICMP timestamp data
                      Send time (sec, usec), Receive time (sec, usec), Timestamp
run*_tcp_*.data ..... TCP timestamp data
                      Send time (sec, usec), Receive time (sec, usec), Timestamp, ISN
run*_temp_*.data .... Temperature data
                      Date, Unit, Temperature

Performance
===========

On a 1.6GHz P4 it takes about 1m30s to process 65500 samples and should scale
approximately linearly with the number of samples.

The performance critical section of code is in CalcSlope() (common.R), which
accounts for 68% of the running time. If this were to be written in C, then the
performance would be significantly better, but at the cost of reducing
portability.

License
=======

With the exception of the scapy.py, pypcap.patch and the contents of
pypcap-1.1 and dpkt-1.6, this software is 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.
    "Hot or not: revealing hidden services by their clock skew"
     In CCS '06: Proceedings of the 13th ACM conference on Computer
     and communications security. ACM Press, October 2006.

Here is suitable BibTeX for LaTeX users:
@inproceedings{hotornot06,
 author = {Steven J. Murdoch},
 title = {Hot or not: revealing hidden services by their clock skew},
 booktitle = {CCS '06: Proceedings of the 13th ACM conference on Computer and Communications Security},
 year = {2006},
 isbn = {1-59593-518},
 pages = {27--36},
 location = {Alexandria, Virginia, USA},
 doi = {http://doi.acm.org/10.1145/1180405.1180410},
 publisher = {ACM Press},
 address = {New York, NY, USA},
 }

The contents of pypcap-1.1 and dpkt-1.6 are Copyright (C) 2004 Dug
Song <dugsong@monkey.org> and distributed under a separate license
(see pypcap-1.1/LICENSE). My changes to pypcap are shown in pcap.patch
and are distributed under the same license as pypcap itself.

The file scapy.py (unmodified) is Copyright (C) 2003 Philippe Biondi
<phil@secdev.org> and is distributed under the GPL v2.


