README

 ==== INFO ====

This is a simple python-only implementation of a Perspectives network notary server. 

Contact: perspectives-project@cs.cmu.edu  
Website: http://www.cs.cmu.edu/~perspectives 
Primary Author: Dan Wendlandt (danwent@gmail.com) 

 ==== PREREQUISITES ====

The implementation relies on python >= 2.5 and the following third-party python libraries:
* sqlite3
* M2Crypto
* cherrypy3 

On debian you can install these using: 

apt-get install python-sqlite python-m2crypto python-cherrypy3

 ===== SETUP ====

First, create a database: 

% python utilities/create_tables.py notary.sqlite

Then create the notary server key pair (private key is needed by the server, and 
the public key should be used by the notary client): 

% bash utilities/create_key_pair.sh notary.priv notary.pub
 
 ===== RUNNING ====

Run the webserver in its own window (or in the background): 

% python notary_http.py notary.sqlite notary.priv 

To run a scan:  

% python ssl_scan_sock.py www.google.com:443,2 notary.sqlite

To test, run a query for a service-id you have scanned:

% python utilities/simple_client.py www.google.com:443,2 localhost 8080 notary.pub

You could also fetch the results with a webbrowser, though you will need to 'view source'
to see the XML:  http://localhost:8080/?host=www.google.com&port=443&service_type=2
(Note the first time you query for a particular service, it's normal to get a 404 error,
see Notes section following for an explanation.)

Commonly, you do not run scans explicitly using these tools, but rather set a cron job to 
periodically run a scan of all service-ids in the database, then pass this list 
to threaded_scanner.py: 

% python utilities/list_service_ids.py notary.sqlite all | python threaded_scanner.py notary.sqlite - 10 10

Running a scan can take a long time, depending on the size of your database and the rate you
specify to threaded_scanner.py .  

Here is an example crontab file to run scans twice a day (1 am and 1 pm) on all services in the database
that have been seen in the past 5 days, with a rate of 20 simultaneous probes and a timeout of 20 seconds
per probe.  It also contains an entry to restart the server if the machine reboots: 

0 1,13 * * * cd /root/Perspectives-Server && python utilities/list_service_ids.py notary.sqlite all | python threaded_scanner.py notary.sqlite - 10 10

@reboot cd /root/Perspectives-Server && python notary_http.py notary.sqlite notary.priv

 ==== Notes ====

The server implements "on-demand probing", so if you query for a service-id that is not
in the database, the notary will automatically kick-off a probe for that service.  The 
notary will respond with an HTTP 404, and the client should requery to get the results.
The Perspectives Firefox client will requery appropriately.  

Unlike the original C implementation of the notary server, this implementation performs
signatures in the webserver portion of the code.  This makes scanning lighter weight, at the 
cost of making reuests heavy-weight and subject to DoS.  We could implement a caching scheme
for the signatures if it proves valuable.  

The only service-type that is currently fully supported is SSL (service-type 2).  There is 
still code for SSH (service-type 1) but since we no longer maintain any notary clients of
this type, we do not regularly test it.  Currently, the threaded_scanner.py will only scan
for SSL services, though work to have it scan for SSH services is pretty minor.  

This code still needs some clean-up and less hard-coded configuration, but its good enough 
for use.  Please visit the github page to submit changes and suggest improvments: 

https://github.com/danwent/Perspectives-Server