[tor-commits] [flashproxy/master] some more doc tweaks
infinity0 at torproject.org
infinity0 at torproject.org
Thu Nov 21 13:18:46 UTC 2013
commit b318c3e51e881e61d8912959b08c15b79c6a961a
Author: Ximin Luo <infinity0 at gmx.com>
Date: Tue Nov 5 00:08:09 2013 +0000
some more doc tweaks
- more precise autotools dependencies
- note more config locations in README
- fix appengine README relative path
- note about public key when running appspot against a foreign facilitator
- note about secure storage for reg-email.pass
- note about plain vs end-to-end encrypted HTTP registrations, and when to use each
- copy-then-edit apache config, rather than edit-then-copy
---
facilitator/INSTALL | 2 +-
facilitator/README | 13 +++++++++++--
facilitator/appengine/README | 4 ++--
facilitator/doc/appspot-howto.txt | 4 +++-
facilitator/doc/email-howto.txt | 5 ++---
facilitator/doc/facilitator-design.txt | 7 +++++--
facilitator/examples/fp-facilitator | 6 +++---
7 files changed, 27 insertions(+), 14 deletions(-)
diff --git a/facilitator/INSTALL b/facilitator/INSTALL
index 5a89f6f..8e66a81 100644
--- a/facilitator/INSTALL
+++ b/facilitator/INSTALL
@@ -1,7 +1,7 @@
Install the dependencies.
$ apt-get install make openssl python-m2crypto
- $ apt-get install gnulib # if running from git
+ $ apt-get install automake autoconf # if running from git
Configure and install.
diff --git a/facilitator/README b/facilitator/README
index 4c50eed..737d1b3 100644
--- a/facilitator/README
+++ b/facilitator/README
@@ -6,8 +6,17 @@ For instructions on building/installing this package from source, see
INSTALL. (This should only be necessary if your distro does not already
integrate this package into its repositories.)
-Each installation has its own public-private keypair, typically in
-reg-daemon.{pub,key} in your flashproxy config directory. You will need
+The flashproxy config directory is installation-dependant, usually at
+/etc/flashproxy or /usr/local/etc/flashproxy. You are strongly
+recommended to keep this on encrypted storage.
+
+The main backends, facilitator and facilitator-reg-daemon, are installed
+as system services, and you should be able to configure them in the
+appropriate place for your system (e.g. /etc/default/facilitator for a
+Debian-based system using initscripts).
+
+At a minimum, each installation has its own public-private keypair at
+reg-daemon.{pub,key} in the flashproxy config directory. You will need
to securely distribute the public part (.pub) to your users - e.g. by
publishing it somewhere, signed by your own PGP key.
diff --git a/facilitator/appengine/README b/facilitator/appengine/README
index dee3130..95215d3 100644
--- a/facilitator/appengine/README
+++ b/facilitator/appengine/README
@@ -5,7 +5,7 @@ See doc/appspot-howto.txt for information about setting up an
application.
To run locally using the development server:
-$ ~/google_appengine/dev_appserver.py appengine/
+$ ~/google_appengine/dev_appserver.py .
To upload a new version:
-$ torify ~/google_appengine/appcfg.py -A $YOUR_APP_ID update appengine/
+$ torify ~/google_appengine/appcfg.py -A $YOUR_APP_ID update .
diff --git a/facilitator/doc/appspot-howto.txt b/facilitator/doc/appspot-howto.txt
index 6485a18..9202417 100644
--- a/facilitator/doc/appspot-howto.txt
+++ b/facilitator/doc/appspot-howto.txt
@@ -1,7 +1,9 @@
These are instructions for how to set up a Google App Engine application
for the appspot rendezvous method (flashproxy-reg-appspot). It requires
the HTTP rendezvous to be available, so you should set that up first and
-ensure it is working correctly, or find someone else's to use.
+ensure it is working correctly, or find someone else's to use. If you
+choose the latter, note that it is *their* reg-daemon.pub that your users
+must give to flashproxy-reg-appspot.
General links:
https://developers.google.com/appengine/
diff --git a/facilitator/doc/email-howto.txt b/facilitator/doc/email-howto.txt
index f7cb934..9cbfdb6 100644
--- a/facilitator/doc/email-howto.txt
+++ b/facilitator/doc/email-howto.txt
@@ -7,6 +7,7 @@ app-specific password rather than your account password.
Once you have an email address and the password for it, you should add
this information to reg-email.pass in your flashproxy config directory.
+For your security, this file should be on encrypted storage.
The following section provides some instructions on how to set up a new
Google account whilst revealing as little information to Google as is
@@ -71,6 +72,4 @@ https://www.google.com/accounts/SmsAuthConfig.
Still on the 2-step summary page, click "Manage application-specific
passwords". Enter "IMAP" for the name and click "Generate password".
-Save the password to encrypted storage. You should save this password
-into /etc/flashproxy/reg-email.pass (or wherever you installed it), so
-that facilitator-email-poller can pick it up.
+Now store this in reg-email.pass, as mentioned in the introduction.
diff --git a/facilitator/doc/facilitator-design.txt b/facilitator/doc/facilitator-design.txt
index 8917d0d..3f4f801 100644
--- a/facilitator/doc/facilitator-design.txt
+++ b/facilitator/doc/facilitator-design.txt
@@ -17,8 +17,11 @@ 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.
+as the HTTP server. The CGI script is facilitator.cgi. There are two
+formats - plain vs. (end-to-end) encrypted. Direct client registrations
+(e.g. flashproxy-reg-http) can use the plain format over HTTPS, which
+provides transport encryption; but if you proxy registrations through
+another service (e.g. reg-appspot), you must use the end-to-end format.
The email rendezvous uses the helper program facilitator-email-poller.
Clients use the flashproxy-reg-email program to send an encrypted
diff --git a/facilitator/examples/fp-facilitator b/facilitator/examples/fp-facilitator
index 500521d..c979ea6 100644
--- a/facilitator/examples/fp-facilitator
+++ b/facilitator/examples/fp-facilitator
@@ -1,8 +1,8 @@
# This is an example apache2 config for serving the facilitator.
#
-# You can edit this file according to the instructions below, then copy it to
-# /etc/apache2/sites-available/fp-facilitator, or wherever is appropriate. Then
-# you can run `a2ensite fp-facilitator` to enable it.
+# To use this file, copy it to /etc/apache2/sites-available/fp-facilitator, or
+# wherever is appropriate. Then edit it according to the instructions below.
+# Finally, run `a2ensite fp-facilitator` to enable it.
#
# You should also run `a2enmod ssl headers` to enable SSL and HSTS.
#
More information about the tor-commits
mailing list