==== INFO ====

This is a fork of Perspectives notary server originally written by Dan Wendlandt
(http://www.cs.cmu.edu/~perspectives).

Differences from the original Perspectives server:

- stores whole certificates and CA chain (DER encoded) instead of just md5 sum
- uses PostgreSQL instead of sqlite, so it's suitable for storing millions of records 
  (can function as SSL Observatory to make "global state snapshots" of SSLiverse subsets)
- hard-coded defaults extracted from source and put into config file
- other code cleanup (logging, threaded scanner rewrite, etc.)
- two HTTP URLs exposed, one for fetching server certficates and the other to
  force fresh scan even if service is known

Author: Ondrej Mikle, ondrej.mikle @ {gmail.com, nic.cz}

 ==== PREREQUISITES ====

The implementation relies on python >= 2.5 and the following packages:
* PostgreSQL (>=8.3, tested on 8.4.x and 9.0.x)
* psycopg2
* M2Crypto
* cherrypy3 

On Debian you can install these using: 

apt-get install postgresql postgresql-client python-psycopg2 python-m2crypto python-cherrypy3

On RHEL/CentOS/Scientific Linux install these packages (cherrypy can be found
in rpmforge repository):

yum install postgresql postgresql-server m2crypto python-psycopg2 python-cherrypy

 ===== SETUP ====

1. Basic database setup

Here we assume the database runs on localhost (it should run either on localhost
or LAN, psycopg does not support reconnects). Note that this setup may vary
depending on PostgreSQL version and Linux distribution. The DB setup is probably
the most tedious part.

Start the server:

# chkconfig postgresql on; service postgresql start     ### for RHEL/CentOS/SL
# /etc/init.d/postgresql start                          ### for Debian/other

Create user to run the server, we'll use 'perspectives' user, set the user's
password:

# useradd -m perspectives
# passwd perspectives

As 'postgres' user, run psql prompt:

# su -c 'psql -d template1 -U postgres' - postgres

In psql prompt, set the user's DB privileges:

template1=# CREATE DATABASE perspectives;
template1=# CREATE USER perspectives WITH PASSWORD 'SomePassword';
template1=# GRANT ALL PRIVILEGES ON DATABASE perspectives TO perspectives;
template1=# \q

Change to user 'perspectives' and create DB schema:

# su - perspectives
% cd /the/directory/with/Perspectives_source_code
% psql -U perspectives -h localhost perspectives < sql/00_create.sql

Check 'pg_hba.conf' configuration file of PostgreSQL. The location varies
depending on distribution and PostgreSQL version, e.g.:
    Debian 6: /etc/postgresql/8.4/main/pg_hba.conf
    Scientific Linux 6 (RHEL 6/CentOS 6): /var/lib/pgsql/data/pg_hba.conf
This file (scroll to the end) specifies how local (socket/localhost) connections
are authenticated. You'll most likely want to use 'md5' or 'pam' authentication
instead of 'ident' or 'password'.


2. Create keypair

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

3. Edit config

Copy the 'notary.config.sample' file to 'notary.config', set your DB
user/password there.  Copy 'cherrypy.conf.sample' to 'cherrypy.conf'. You may
wish to edit things such as logfile locations, listen port, etc. but defaults
should be fine for most.
 
 ===== RUNNING ====

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

% python notary_http.py notary.config

To run a scan:  

% python ssl_scan_sock.py www.google.com:443 notary.config

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

% python utilities/simple_client.py www.google.com:443 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

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 list_service_ids.py notary.config all | python threaded_scanner.py notary.config - 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 in 50 threads with 15 second timeout per probe.  It
also contains an entry to restart the server if the machine reboots: 

0 1,13 * * * cd /home/perspectives/Perspectives-Server && python list_service_ids.py notary.config all | python threaded_scanner.py notary.config - 50 15

@reboot cd /home/perspectives/Perspectives-Server && python notary_http.py notary.config

 ==== 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.  

Two new method URLs exposed via HTTPwere added:

- http://localhost:8080/get_certs?host=encrypted.google.com&port=443
  - fetches XML with full leaf certificate data of server (see utilities/cert_client.py)
  - return codes:
    HTTP 200 - we have data
    HTTP 404 - no data, but launching scan in background, try some seconds later
- http://localhost:8080/refresh_scan?host=encrypted.google.com&port=443
  - forces fresh scan of encrypted.google.com unless last scan is less than 10
    minutes old
    - return codes:
      HTTP 202 - scan scheduled for immediate dispatch
      HTTP 200 - not scanning, scanned in recent few minutes
      HTTP 404 - scan not scheduled (queue may be full)