commit 7ed4f653df3b7b6ec92fef41efd3f2295bd097d8 Author: Ximin Luo <infinity0@gmx.com> Date: Mon Nov 4 22:04:11 2013 +0000 document appspot method more thoroughly, and rename howtos to be consistent 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 | 4 +- facilitator/README | 9 ++-- facilitator/appengine/README | 2 +- facilitator/doc/appengine-howto.txt | 56 ----------------------- facilitator/doc/appspot-howto.txt | 56 +++++++++++++++++++++++ facilitator/doc/email-howto.txt | 76 ++++++++++++++++++++++++++++++++ facilitator/doc/facilitator-design.txt | 13 +++--- facilitator/doc/facilitator-howto.txt | 55 ----------------------- facilitator/doc/gmail-howto.txt | 72 ------------------------------ facilitator/doc/server-howto.txt | 55 +++++++++++++++++++++++ facilitator/examples/reg-email.pass | 4 +- 11 files changed, 205 insertions(+), 197 deletions(-) diff --git a/facilitator/Makefile.am b/facilitator/Makefile.am index 6252596..2a9086b 100644 --- a/facilitator/Makefile.am +++ b/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 diff --git a/facilitator/README b/facilitator/README index f994977..4c50eed 100644 --- a/facilitator/README +++ b/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. diff --git a/facilitator/appengine/README b/facilitator/appengine/README index 2e1e33d..dee3130 100644 --- a/facilitator/appengine/README +++ b/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: diff --git a/facilitator/doc/appengine-howto.txt b/facilitator/doc/appengine-howto.txt deleted file mode 100644 index 44c5324..0000000 --- a/facilitator/doc/appengine-howto.txt +++ /dev/null @@ -1,56 +0,0 @@ -These are instructions for how to set up a Google App Engine application -to run at appspot.com. - -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 -to do that. - -Download the SDK: -https://developers.google.com/appengine/docs/go/gettingstarted/devenvironmen... - -Write your program and app.yaml file: -https://developers.google.com/appengine/docs/go/gettingstarted/helloworld - -When you're ready to upload, log in with your Google account and follow -the directions: -https://appengine.google.com/ -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/ -07:25 PM Host: appengine.google.com -07:25 PM Application: application-id; version: 1 -07:25 PM -Starting update of app: application-id, version: 1 -07:25 PM Getting current resource limits. -Email: xxx@gmail.com -Password for xxx@gmail.com: -07:26 PM Scanning files on local disk. -07:26 PM Cloning 2 application files. -07:26 PM Uploading 1 files and blobs. -07:26 PM Uploaded 1 files and blobs -07:26 PM Compilation starting. -07:26 PM Compilation: 1 files left. -07:26 PM Compilation completed. -07:26 PM Starting deployment. -07:26 PM Checking if deployment succeeded. -07:26 PM Deployment successful. -07:26 PM Checking if updated app version is serving. -07:26 PM Completed update of app: application-id, version: 1 - -Uploading the program in this way seems to create the files -~/.appcfg_nag and ~/.appcfg_cookies. Running the update command again -doesn't require you to enter your password again. - -Once logged in, you can disable logging for the application. Click -"Logs" on the left panel. Under "Total Logs Storage", click "Change -Settings". Enter "0" in the "days of logs" box and click "Save -Settings". diff --git a/facilitator/doc/appspot-howto.txt b/facilitator/doc/appspot-howto.txt new file mode 100644 index 0000000..6485a18 --- /dev/null +++ b/facilitator/doc/appspot-howto.txt @@ -0,0 +1,56 @@ +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. + +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 email-howto.txt for how +to do that. + +Download the SDK: +https://developers.google.com/appengine/docs/go/gettingstarted/devenvironmen... + +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. + +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 -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 +Starting update of app: application-id, version: 1 +07:25 PM Getting current resource limits. +Email: xxx@gmail.com +Password for xxx@gmail.com: +07:26 PM Scanning files on local disk. +07:26 PM Cloning 2 application files. +07:26 PM Uploading 1 files and blobs. +07:26 PM Uploaded 1 files and blobs +07:26 PM Compilation starting. +07:26 PM Compilation: 1 files left. +07:26 PM Compilation completed. +07:26 PM Starting deployment. +07:26 PM Checking if deployment succeeded. +07:26 PM Deployment successful. +07:26 PM Checking if updated app version is serving. +07:26 PM Completed update of app: application-id, version: 1 + +Uploading the program in this way seems to create the files +~/.appcfg_nag and ~/.appcfg_cookies. Running the update command again +doesn't require you to enter your password again. + +Once logged in, you can disable logging for the application. Click +"Logs" on the left panel. Under "Total Logs Storage", click "Change +Settings". Enter "0" in the "days of logs" box and click "Save +Settings". diff --git a/facilitator/doc/email-howto.txt b/facilitator/doc/email-howto.txt new file mode 100644 index 0000000..f7cb934 --- /dev/null +++ b/facilitator/doc/email-howto.txt @@ -0,0 +1,76 @@ +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 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. + +You may have trouble if you are using Tor to create the account, for two +reasons. The first is that exit nodes are a source of abuse and Google +is more suspicious of them. The second is that Gmail is suspicious and +can lock you out of the account when your IP address is changing. While +setting up the account, use a single node in your torrc ExitNodes +configuration. Choose a U.S. exit node, one with low bandwidth. + +Go to https://mail.google.com/. Allow JavaScript to run (even from +youtube.com; it seems to be necessary). Click the "CREATE AN ACCOUNT" +button. + +Enter the account details. You don't need to fill in "Your current email +address". Enter a mobile phone number for later activation of two-factor +authentication. Solve the captcha. Click "Next Step". You may have to do +a phone SMS verification here. + +At this point the Gmail account is created. If you are pushed into +joining Google+, close everything out and go back to +https://mail.google.com/. + +Log out of the account and then back in again. There will be new text in +the lower right reading "Last account activity". Click "Details" and +turn off the unusual activity alerts. This will keep you from getting +locked out when you come from different IP addresses. At this point you +should remove the temporary ExitNodes configuration from torrc. + +Add a filter to prevent registrations from being marked as spam. Click +on the gear icon and select "Settings". Select "Filters" then "Create a +new filter". For "Has the words" type "in:spam", then "Create filter +with this search". There will be a warning that filters using "in:" will +never match incoming mail; this appears to be false and you can just +click OK. Check "Never send it to Spam" and click "Create filter". + +Enable IMAP. Click the gear icon, then "Settings", then "Forwarding and +POP/IMAP". + * Disable POP + * Enable IMAP + * Auto-Expunge on +Click "Save Changes". + +Enable two-factor authentication. We do this not so much for the +two-factor, but because it allows creating an independent password that +is used only for IMAP and does not have access to the web interface of +Gmail. Click the email address in the upper right, then "Account". Click +"Security". By "2-step verification" click "Edit". Click through until +it lets you set up. The phone number you provided when the account was +created will be automatically filled in. Choose "Text message (SMS)" +then click "Send code". Get your text message, type it in, and hit +"Verify". Uncheck "Trust this computer" on the next screen. Finally +"Confirm". On the following summary page, click "Show backup codes" and +save the codes to encrypted storage. Future codes can be generated at +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. diff --git a/facilitator/doc/facilitator-design.txt b/facilitator/doc/facilitator-design.txt index f26acc2..8917d0d 100644 --- a/facilitator/doc/facilitator-design.txt +++ b/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. diff --git a/facilitator/doc/facilitator-howto.txt b/facilitator/doc/facilitator-howto.txt deleted file mode 100644 index 6f71772..0000000 --- a/facilitator/doc/facilitator-howto.txt +++ /dev/null @@ -1,55 +0,0 @@ -This document describes how to configure a server running the facilitator on -Debian 7. It is not necessary to make things work, but gives you some added -security, and is a good reference if you want to create a dedicated VM for a -facilitator from scratch. - -We will use the domain name fp-facilitator.example.com. - -== Basic and security setup - -Install some essential packages and configure a firewall. - - # cat >/etc/apt/apt.conf.d/90suggests<<EOF -APT::Install-Recommends "0"; -APT::Install-Suggests "0"; -EOF - # apt-get remove portmap - # apt-get update - # apt-get upgrade - # apt-get install shorewall shorewall6 - -Away from the facilitator, generate an SSH key for authentication: - - $ ssh-keygen -f ~/.ssh/fp-facilitator - $ ssh-copy-id -i ~/.ssh/fp-facilitator.pub root@fp-facilitator.example.com - -Then log in and edit /etc/ssh/sshd_config to disable password -authentication: - - PasswordAuthentication no - -Configure the firewall to allow only SSH and HTTPS. - - # cd /etc/shorewall - # cp /usr/share/doc/shorewall/examples/Universal/{interfaces,policy,rules,zones} . - Edit /etc/shorewall/rules: -SECTION NEW -SSH(ACCEPT) net $FW -HTTPS(ACCEPT) net $FW - - # cd /etc/shorewall6 - # cp /usr/share/doc/shorewall6/examples/Universal/{interfaces,policy,rules,zones} . - Edit /etc/shorewall6/rules: -SECTION NEW -SSH(ACCEPT) all $FW -HTTPS(ACCEPT) all $FW - -Edit /etc/default/shorewall and /etc/default/shorewall6 and set - - startup=1 - -Restart servers. - - # /etc/init.d/ssh restart - # /etc/init.d/shorewall start - # /etc/init.d/shorewall6 start diff --git a/facilitator/doc/gmail-howto.txt b/facilitator/doc/gmail-howto.txt deleted file mode 100644 index 426d52c..0000000 --- a/facilitator/doc/gmail-howto.txt +++ /dev/null @@ -1,72 +0,0 @@ -These are instructions for setting up a Gmail 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. - -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. - -== Creating a Google account securely - -These instructions were current as of May 2013. - -You may have trouble if you are using Tor to create the account, for two -reasons. The first is that exit nodes are a source of abuse and Google -is more suspicious of them. The second is that Gmail is suspicious and -can lock you out of the account when your IP address is changing. While -setting up the account, use a single node in your torrc ExitNodes -configuration. Choose a U.S. exit node, one with low bandwidth. - -Go to https://mail.google.com/. Allow JavaScript to run (even from -youtube.com; it seems to be necessary). Click the "CREATE AN ACCOUNT" -button. - -Enter the account details. You don't need to fill in "Your current email -address". Enter a mobile phone number for later activation of two-factor -authentication. Solve the captcha. Click "Next Step". You may have to do -a phone SMS verification here. - -At this point the Gmail account is created. If you are pushed into -joining Google+, close everything out and go back to -https://mail.google.com/. - -Log out of the account and then back in again. There will be new text in -the lower right reading "Last account activity". Click "Details" and -turn off the unusual activity alerts. This will keep you from getting -locked out when you come from different IP addresses. At this point you -should remove the temporary ExitNodes configuration from torrc. - -Add a filter to prevent registrations from being marked as spam. Click -on the gear icon and select "Settings". Select "Filters" then "Create a -new filter". For "Has the words" type "in:spam", then "Create filter -with this search". There will be a warning that filters using "in:" will -never match incoming mail; this appears to be false and you can just -click OK. Check "Never send it to Spam" and click "Create filter". - -Enable IMAP. Click the gear icon, then "Settings", then "Forwarding and -POP/IMAP". - * Disable POP - * Enable IMAP - * Auto-Expunge on -Click "Save Changes". - -Enable two-factor authentication. We do this not so much for the -two-factor, but because it allows creating an independent password that -is used only for IMAP and does not have access to the web interface of -Gmail. Click the email address in the upper right, then "Account". Click -"Security". By "2-step verification" click "Edit". Click through until -it lets you set up. The phone number you provided when the account was -created will be automatically filled in. Choose "Text message (SMS)" -then click "Send code". Get your text message, type it in, and hit -"Verify". Uncheck "Trust this computer" on the next screen. Finally -"Confirm". On the following summary page, click "Show backup codes" and -save the codes to encrypted storage. Future codes can be generated at -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. diff --git a/facilitator/doc/server-howto.txt b/facilitator/doc/server-howto.txt new file mode 100644 index 0000000..6f71772 --- /dev/null +++ b/facilitator/doc/server-howto.txt @@ -0,0 +1,55 @@ +This document describes how to configure a server running the facilitator on +Debian 7. It is not necessary to make things work, but gives you some added +security, and is a good reference if you want to create a dedicated VM for a +facilitator from scratch. + +We will use the domain name fp-facilitator.example.com. + +== Basic and security setup + +Install some essential packages and configure a firewall. + + # cat >/etc/apt/apt.conf.d/90suggests<<EOF +APT::Install-Recommends "0"; +APT::Install-Suggests "0"; +EOF + # apt-get remove portmap + # apt-get update + # apt-get upgrade + # apt-get install shorewall shorewall6 + +Away from the facilitator, generate an SSH key for authentication: + + $ ssh-keygen -f ~/.ssh/fp-facilitator + $ ssh-copy-id -i ~/.ssh/fp-facilitator.pub root@fp-facilitator.example.com + +Then log in and edit /etc/ssh/sshd_config to disable password +authentication: + + PasswordAuthentication no + +Configure the firewall to allow only SSH and HTTPS. + + # cd /etc/shorewall + # cp /usr/share/doc/shorewall/examples/Universal/{interfaces,policy,rules,zones} . + Edit /etc/shorewall/rules: +SECTION NEW +SSH(ACCEPT) net $FW +HTTPS(ACCEPT) net $FW + + # cd /etc/shorewall6 + # cp /usr/share/doc/shorewall6/examples/Universal/{interfaces,policy,rules,zones} . + Edit /etc/shorewall6/rules: +SECTION NEW +SSH(ACCEPT) all $FW +HTTPS(ACCEPT) all $FW + +Edit /etc/default/shorewall and /etc/default/shorewall6 and set + + startup=1 + +Restart servers. + + # /etc/init.d/ssh restart + # /etc/init.d/shorewall start + # /etc/init.d/shorewall6 start diff --git a/facilitator/examples/reg-email.pass b/facilitator/examples/reg-email.pass index 6f34e06..75b6aa4 100644 --- a/facilitator/examples/reg-email.pass +++ b/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