[tor-commits] [gettor/master] Improved README

[ilv at torproject.org]

commit dee89596a3df5faf0d2042352f577a2248966b35
Author: ilv <ilv at users.noreply.github.com>
Date:   Wed Nov 5 21:25:07 2014 -0300

    Improved README
---
 README.md |  130 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 126 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e194589..cf1c5f7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,128 @@
-GetTor
-======
+GetTor Revamp
+=============
 
-GetTor development. Project started at the Google Summer of Code 2014, under the
-Tor Project organization.
+GetTor Revamp done during the Google Summer of Code 2014 for the Tor Project.
+This repository continues to being used for improvements and further
+development.
+
+What is GetTor?
+===============
+
+GetTor was created as a program for serving Tor and related files over SMTP,
+thus avoiding direct and indirect censorship of Tor's software, in particular,
+the Tor Browser Bundle (TBB). Users interacted with GetTor by sending emails
+to a specific email address. After the user specified his OS and language,
+GetTor would send him an email with an attachment containing the requested
+package. This worked well for a while, but the bundles started to get too
+large for being sent as attachments in most email providers. In order to fix
+this, GetTor started to send (Dropbox) links instead of attachments.
+
+What are the goals of the new GetTor?
+=====================================
+
+Here is a list of the main goals the new GetTor should accomplish:
+
+ * Safe. Remember we are serving people under heavy censorship.
+ * Easy to use. The fewer user interactions, the better.
+ * Clean code. It should be clear to other developers/contributors how GetTor
+ works and how can it be improved.
+ * Automated. We should try to automate things as much as possible.
+ * Language and provider friendly. It should be easy to support new languages
+ and to add new providers for storing packages and generate links.
+
+ How does the new GetTor works?
+ ==============================
+
+Links files: Currently links are saved in files with the '.links' extension,
+using the ConfigParser format (RFC 882). A sample link file should look like
+this:
+
+  --- BEGIN FILE ---
+  [provider]
+  name = CoolCloudProvider
+
+  [key]
+  fingerprint = AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH IIII JJJJ
+
+  [linux]
+  en = Package (64-bit): https://cool.cloud.link64
+	ASC signature (64-bit): https://cool.cloud.link64.asc
+	Package SHA256 checksum (64-bit): superhash64,
+	Package (32-bit): https://cool.cloud.link32
+	ASC signature (32-bit): https://cool.cloud.link32.asc
+	Package SHA256 checksum (32-bit): superhash32
+
+  [windows]
+  ...
+
+  [osx]
+  ...
+  --- END FILE ---
+
+You can also check providers/dropbox.links for a better example.
+
+Core: the heart of GetTor. Receives requests for links for a certain OS and
+language and respond accordingly. It also presents an easy way for scripts
+to create links file.
+
+SMTP: Receives requests via email, process them, contact the core module if
+necessary and respond to the user in the specified language. People can send
+blank or dummy emails to it to receive a help message describing how to ask
+for links. Email forwarding is used to redirect the emails to GetTor.
+
+XMPP: Same as above, but via XMPP (account needed). It has been tested with
+dukgo.com, jabber.ccc.de, riseup.net. It doesn't seem to be able to interact
+with gtalk users.
+
+Twitter: Receive requests via Twitter direct messages, contact the core module
+if necessary and respond to the user in the specified language. Unfinished.
+
+DB: Store anonymous info about the people that interact with GetTor in order
+to keep count of the number of requests per person and avoid malicious users
+that try to collapse the service. It also keeps count of how many requests
+GetTor has received during its lifetime. A lot of other data was being saved
+in the original gsoc project, but it was changed to save the minimum. 
+
+Blacklist: Provide a mechanism to avoid flood and deny interaction to
+malicious users.
+
+Providers scripts: every supported provider should have a script to
+automatically upload packages to 'the cloud' and create the corresponding
+links files. The script should consider the following steps:
+
+  1) Upload the packages.
+  2) Get the sha256 checksum of the files uploaded.
+  3) Get the PGP key fingerprint that signed the files.
+  4) Check for .asc file for every package uploaded.
+  5) Put all together in a '.link' file (using the core module).
+
+
+What is the current status of the new GetTor?
+=============================================
+
+Tested internally, and currently waiting to be deployed.
+
+
+How can I help?
+================
+
+If you have ideas to improve GetTor and/or add new providers, please tell us!
+I'm currently the lead developer on this, so if you comments/doubts on the code
+you can send me an e-mail to ilv _at_ riseup _dot_ net. For openning tickets
+you should use the trac[0] and select the GetTor component. Some neat ideas we
+could use are the following:
+
+0) Report bugs!
+1) Create script for new providers, namely: Google Drive, Github. Check 
+providers.txt
+2) Create a new module for distributing links. Check distribution_methods.txt
+3) Finish the Twitter module.
+5) Propose code/behaviour improvements.
+4) Update the specs.
+
+
+References
+===========
+
+[0] https://trac.torproject.org/projects/tor/query?status=accepted&status=assigned&status=needs_information&status=needs_review&status=needs_revision&status=new&status=reopened&component=GetTor&col=id&col=summary&col=component&col=status&col=type&col=priority&col=milestone&order=priority