commit 8b405f90d5f8905ea08794dbf569f1bc8faf5b3c Author: David Fifield david@bamsoftware.com Date: Wed Sep 19 17:17:43 2012 -0700

Add email poller to facilitator setup docs. --- doc/facilitator-howto.txt | 64 +++++++++++++++++++++++++++------- facilitator/facilitator-email-poller | 4 ++ flashproxy-reg-email | 4 +- 3 files changed, 57 insertions(+), 15 deletions(-)

diff --git a/doc/facilitator-howto.txt b/doc/facilitator-howto.txt index 560eeaf..5157659 100644 --- a/doc/facilitator-howto.txt +++ b/doc/facilitator-howto.txt @@ -3,16 +3,27 @@ We will use the domain name tor-facilitator.example.com.

== Overview

-The facilitator consists of three parts: an HTTP server, a CGI program, -and a backend. The HTTP server is responsible for speaking TLS and -invoking the CGI program. The CGI program receives client registrations -and proxy requests for clients, parses them, and forwards them to the -backend. The backend is stateful and is responsible for assigning -clients to proxies and remembering client registrations. - -We use Apache 2 as the HTTP server. The CGI script is facilitator.cgi. -The backend is facilitator. fac.py is a Python module containing code -common to facilitator.cgi and facilitator. +The facilitator consists of a backend server that is essentially a +dynamic database of client addresses, as well as helper programs that +receive client registrations from the Internet over various means and +pass them to the backend. There are two supported helper rendezvous +methods: HTTP and email. + +The HTTP rendezvous uses an HTTP server and a CGI program. The HTTP +server is responsible for speaking TLS and invoking the CGI program. The +CGI program receives client registrations and proxy requests for +clients, parses them, and forwards them to the backend. We use Apache 2 +as the HTTP server. The CGI script is facilitator.cgi. The backend is +facilitator. + +The email rendezvous uses the helper program facilitator-email-poller. +Clients use the flashproxy-reg-email program to send an encrypted +message to a Gmail address. The poller constantly checks for new +messages, decrypts and deletes them, and forwards the registrations to +the facilitator. + +fac.py is a Python module containing code common to the various +facilitator programs.

== Basic and security setup

@@ -88,12 +99,14 @@ Restart servers. # cd flashproxy/facilitator # make install

-This installs facilitator.cgi, facilitator, and fac.py to -/usr/local/bin. It also installs a System V init file to -/etc/init.d/facilitator. +This installs facilitator.cgi, facilitator, facilitator-email-poller, +and fac.py to /usr/local/bin. It also installs System V init files to +/etc/init.d/.

# update-rc.d facilitator defaults # /etc/init.d/facilitator start + # update-rc.d facilitator-email-poller defaults + # /etc/init.d/facilitator-email-poller start

== HTTP server setup

@@ -149,3 +162,28 @@ Copy the new tor-facilitator.pem to the facilitator server as /etc/apache2/tor-facilitator.pem.

# /etc/init.d/apache2 restart + +=== Email poller setup + +The facilitator-email-poller program requires a private RSA key (used to +decrypt encrypted client registrations), and a password that is used to +log in to the designated Gmail account. See the file gmail-setup.txt for +instructions on setting up a Gmail account. After you've set up the +account and have the password, save it to a file reg-email.pass and make +it not readable or writable by anyone but its owner. + + # chmod 600 /etc/flashproxy/reg-email.pass + +You need an RSA keypair because all client registrations over email are +encrypted. + + # openssl genrsa /etc/flashproxy/reg-email.key 2048 + # chmod 600 /etc/flashproxy/reg-email.key + # openssl rsa -pubout < /etc/flashproxy/reg-email.key > reg-email.pub + +You will have to edit flashproxy-reg-email and copy the contents of +reg-email.pub into the appropriate place. + +Install reg-email.key and reg-email.pass to /etc/flashproxy to match +what the init scritp expects, or else use the --key and --pass options +if you have them stored in another place. diff --git a/facilitator/facilitator-email-poller b/facilitator/facilitator-email-poller index 42bf2dc..77f81e0 100755 --- a/facilitator/facilitator-email-poller +++ b/facilitator/facilitator-email-poller @@ -58,6 +58,10 @@ A4GBAFjOKer89961zgK5F7WF0bnj4JXMJTENAKaSbn+2kmOeUJXRmm/kEd5jhW6Y # hashing the public key, not the entire certificate. PUBKEY_SHA1 = "5d97e1ec007e48c1f36e736e652eeaf2184697c3".decode("hex")

+# Generating an RSA keypair for use by this program: +# openssl genrsa reg-email 2048 +# chmod 600 reg-email + LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"

class options(object): diff --git a/flashproxy-reg-email b/flashproxy-reg-email index d919de5..cdac964 100755 --- a/flashproxy-reg-email +++ b/flashproxy-reg-email @@ -62,8 +62,8 @@ A4GBAFjOKer89961zgK5F7WF0bnj4JXMJTENAKaSbn+2kmOeUJXRmm/kEd5jhW6Y PUBKEY_SHA1 = "e341556ff3fd18e155ce30971fc93e740aa4b185".decode("hex")

# Registrations are encrypted with this public key before being emailed. Only -# the facilitator operators should have the corresponding private key. -# openssl genrsa reg-email 2048 +# the facilitator operators should have the corresponding private key. Given a +# private key in reg-email, get the public key like this: # openssl rsa -pubout < reg-email > reg-email.pub FACILITATOR_PUBKEY_PEM = """\ -----BEGIN PUBLIC KEY-----