document appspot method more thoroughly, and rename howtos to be cons…

…istent with the method name.

- also ditch the "url" method since it is not really a separate method from HTTP; both provided by facilitator.cgi

facilitator/Makefile.am

@@ -9,7 +9,7 @@ initscriptdir = /etc/init.d
 exampledir = $(docdir)/examples
 appenginedir = $(pkgdatadir)/appengine
 pkgconfdir = $(sysconfdir)/flashproxy
-appengineconfdir = $(pkgconfdir)/reg-appengine
+appengineconfdir = $(pkgconfdir)/reg-appspot
 
 # automake PLVs
 
@@ -19,7 +19,7 @@ initscript_SCRIPTS = init.d/facilitator init.d/facilitator-email-poller init.d/f
 dist_initconf_DATA = default/facilitator default/facilitator-email-poller default/facilitator-reg-daemon
 endif
 
-dist_doc_DATA = doc/appengine-howto.txt doc/facilitator-design.txt doc/facilitator-howto.txt doc/gmail-howto.txt doc/http-howto.txt README
+dist_doc_DATA = doc/appspot-howto.txt doc/facilitator-design.txt doc/email-howto.txt doc/http-howto.txt doc/server-howto.txt README
 dist_example_DATA = examples/fp-facilitator examples/reg-email.pass
 dist_appengine_DATA = appengine/app.yaml appengine/config.go appengine/fp-reg.go appengine/README
 appengineconf_DATA = appengine/config.go

facilitator/README

@@ -11,12 +11,13 @@ reg-daemon.{pub,key} in your 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.
 
-There are three supported helper rendezvous methods: HTTP, URL, and
-email. Each helper method may require additional manual configuration;
-see the corresponding doc/x-howto.txt for more details.
+There are three supported helper rendezvous methods: HTTP, email, and
+appspot. Each helper method may require additional manual configuration
+and might also depend on other helper methods; see the corresponding
+doc/x-howto.txt for more details.
 
 For suggestions on configuring a dedicated facilitator machine, see
-doc/facilitator-howto.txt.
+doc/server-howto.txt.
 
 For documentation on the design of the facilitator components, see
 doc/facilitator-design.txt.

facilitator/appengine/README

@@ -1,7 +1,7 @@
 This is the server-side code that runs on Google App Engine for the
 "appspot" registration method.
 
-See doc/appengine-howto.txt for information about setting up an
+See doc/appspot-howto.txt for information about setting up an
 application.
 
 To run locally using the development server:

facilitator/doc/appengine-howto.txt → facilitator/doc/appspot-howto.txt

@@ -1,31 +1,31 @@
 These are instructions for how to set up a Google App Engine application
-to run at appspot.com.
+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.
 
 General links:
 https://developers.google.com/appengine/
 https://developers.google.com/appengine/docs/whatisgoogleappengine
 https://developers.google.com/appengine/docs/go/gettingstarted/
 
-You first need to create a Google account. See gmail-howto.txt for how
+You first need to create a Google account. See email-howto.txt for how
 to do that.
 
 Download the SDK:
 https://developers.google.com/appengine/docs/go/gettingstarted/devenvironment
 
-Write your program and app.yaml file:
-https://developers.google.com/appengine/docs/go/gettingstarted/helloworld
+Find your facilitator appengine installation, probably in reg-appspot/
+in your flashproxy config dir. Edit config.go to point to the address of
+the HTTP facilitator.
 
-When you're ready to upload, log in with your Google account and follow
-the directions:
-https://appengine.google.com/
+Follow the directions to register a new application:
 https://developers.google.com/appengine/docs/go/gettingstarted/uploading
-
 Enter an application ID and create the application.
 
 Use the appcfg.py program to upload the program. It should look
 something like this:
 
-$ torify ./google_appengine/appcfg.py update myapp/
+$ torify ./google_appengine/appcfg.py -A <YOUR_APP_ID> update reg-appspot/
 07:25 PM Host: appengine.google.com
 07:25 PM Application: application-id; version: 1
 07:25 PM

facilitator/doc/gmail-howto.txt → facilitator/doc/email-howto.txt

@@ -1,13 +1,17 @@
-These are instructions for setting up a Gmail account for use with the
+These are instructions for setting up an email account for use with the
 email-based rendezvous (facilitator-email-poller / flashproxy-reg-email).
 
-You are strongly advised to use a new Google account dedicated for this
-purpose. For those that need to protect their information even from
-Google, we provide some instructions on how to do this below.
+You are strongly advised to use an email account dedicated for this
+purpose. If your email provider supports it, we advise you to use an
+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.
 
+The following section provides some instructions on how to set up a new
+Google account whilst revealing as little information to Google as is
+feasible.
+
 == Creating a Google account securely
 
 These instructions were current as of May 2013.

facilitator/doc/facilitator-design.txt

@@ -2,10 +2,11 @@ The main facilitator program is 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 three supported helper rendezvous
-methods: HTTP, URL, and email.
+methods: HTTP, email, and appspot.
 
 facilitator-reg is a simple program that forwards its standard input to
-a locally running facilitator-reg-daemon process.
+a locally running facilitator-reg-daemon process. It is not used by the
+other components, but is useful for debugging and test purposes.
 
 facilitator-reg-daemon accepts connections containing encrypted client
 registrations and forwards them to the facilitator. It exists as a
@@ -24,9 +25,11 @@ Clients use the flashproxy-reg-email program to send an encrypted
 message to a Gmail address. The poller constantly checks for new
 messages and forwards them to facilitator-reg.
 
-The URL rendezvous uses the helper program flashproxy-reg-email. The
-helper program doesn't actually make a registration; rather, it prints
-out a URL which, when retrieved, makes the registration.
+The appspot rendezvous uses Google's appengine platform as a proxy for
+the HTTP method, either yours or that of another facilitator. It takes
+advantage of the fact that a censor cannot distinguish between a TLS
+connection to appspot.com or google.com, since the IPs are the same, and
+it is highly unlikely that anyone will try to block the latter.
 
 fac.py is a Python module containing code common to the various
 facilitator programs.

facilitator/examples/reg-email.pass

@@ -3,8 +3,8 @@
 # imap.(<email> domain):993.
 #
 # If your email provider supports it, we advise you to use an app-specific
-# password rather than your account password; see gmail-howto.txt in this
-# package's documentation for details on how to do this for a Google account.
+# password rather than your account password; see email-howto.txt in this
+# package's documentation for details on how to do this.
 #
 #imap.gmail.com:993 flashproxyreg.a@gmail.com topsecret11!one
 #flashproxyreg.a@gmail.com passwords with spaces are ok too