[tor-commits] [stem/master] 'To Russia With Love' tutorial

commit ecc5f7bcd7d9669521e3b3b9275b18dff98c4270 Author: Damian Johnson atagar@torproject.org Date: Sun Mar 10 11:28:58 2013 -0700

'To Russia With Love' tutorial

Soviet themed tutorial for programmatically starting tor and reading a site through it. I've been wanting to write this for quite a long time...

https://trac.torproject.org/7505 --- .../label/resources/to_russia_with_love.xcf | Bin 0 -> 5699 bytes docs/_static/label/to_russia_with_love.png | Bin 0 -> 2924 bytes docs/_static/locale_selection_output.png | Bin 0 -> 37229 bytes docs/_static/section/tutorial/soviet.png | Bin 0 -> 4679 bytes docs/contents.rst | 1 + docs/tutorial.rst | 16 +++++ docs/tutorial/to_russia_with_love.rst | 70 ++++++++++++++++++++ 7 files changed, 87 insertions(+), 0 deletions(-)

diff --git a/docs/_static/label/resources/to_russia_with_love.xcf b/docs/_static/label/resources/to_russia_with_love.xcf new file mode 100644 index 0000000..1fa449e Binary files /dev/null and b/docs/_static/label/resources/to_russia_with_love.xcf differ diff --git a/docs/_static/label/to_russia_with_love.png b/docs/_static/label/to_russia_with_love.png new file mode 100644 index 0000000..9a2d1c6 Binary files /dev/null and b/docs/_static/label/to_russia_with_love.png differ diff --git a/docs/_static/locale_selection_output.png b/docs/_static/locale_selection_output.png new file mode 100644 index 0000000..2afbaa7 Binary files /dev/null and b/docs/_static/locale_selection_output.png differ diff --git a/docs/_static/section/tutorial/soviet.png b/docs/_static/section/tutorial/soviet.png new file mode 100644 index 0000000..c54c3d8 Binary files /dev/null and b/docs/_static/section/tutorial/soviet.png differ diff --git a/docs/contents.rst b/docs/contents.rst index fbf2495..d2fee6a 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -6,6 +6,7 @@ Contents

tutorial tutorial/the_little_relay_that_could + tutorial/to_russia_with_love tutorial/mirror_mirror_on_the_wall

download diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 68572fd..967682b 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -9,6 +9,12 @@ Tutorial License: Public Domain Alternate: https://openclipart.org/detail/1128/train-roadsign-by-ryanlerch

+ * To Russia With Love - soviet.png + Source: https://openclipart.org/detail/146017/flag-of-the-soviet-union-by-marxist-le... + Author: Unknown + License: Public Domain (not a subject of copyright according the Russian civil code) + Alternate: https://openclipart.org/detail/85555/communist-sabbatarian-ribbon-by-rones-8... + * Mirror Mirror On The Wall - mirror.png Source: https://openclipart.org/detail/152155/mirror-frame-by-gsagri04 Author: Unknown (gsagri04?) @@ -31,6 +37,16 @@ feet wet by jumping straight in with some tutorials... "Hello World" for talking with Tor. This will step you through configuring Tor and writing your first script to talk with it.

+ * - .. image:: /_static/section/tutorial/soviet.png + :target: tutorial/to_russia_with_love.html + + - .. image:: /_static/label/to_russia_with_love.png + :target: tutorial/to_russia_with_love.html + + Rather than talking to Tor, we'll now talk **through** it. In this + tutorial we'll programmatically start Tor then use it to read a site + through mother Russia! + * - .. image:: /_static/section/tutorial/mirror.png :target: tutorial/mirror_mirror_on_the_wall.html

diff --git a/docs/tutorial/to_russia_with_love.rst b/docs/tutorial/to_russia_with_love.rst new file mode 100644 index 0000000..7fb7c66 --- /dev/null +++ b/docs/tutorial/to_russia_with_love.rst @@ -0,0 +1,70 @@ +To Russia With Love +=================== + +Say it's 1982, the height of the Cold War, and you're a journalist doing a piece on how the Internet looks from behind the Iron Curtain. Ignoring the minor detail that the Internet doesn't yet exist, we'll walk you through how you could do it - no passport required! + +The Internet isn't uniform. Localization, censorship, and selective service based on your IP's geographic location can make the Internet a very different place depending on where you're coming from. + +Tor relays are scattered all over the world and, as such, you can pretend to be from any place running an exit. This can be especially useful to evade pesky geolocational restrictions, such as news sites that refuse to work while you're traveling abroad. + +Tor makes `configuring your exit locale https://www.torproject.org/docs/faq.html.en#ChooseEntryExit`_ easy through the **ExitNodes** torrc option. Note that you don't need a control port (or even stem) to do this, though they can be useful if you later want to do something more elaborate. + +In the following example we're using stem to `start Tor <../api/process.html>`_, then reading a site through it with `PycURL http://pycurl.sourceforge.net/`_. This is not always reliable (some relays are lemons) so you may need to run this more than once. + +**Do not rely on the following not to leak.** Though it seems to work, DNS resolution and other edge cases might expose your real IP. If you have a suggestion for how to improve this example then please `let me know http://www.atagar.com/contact/`_! + +:: + + import StringIO + + import pycurl + import stem.process + + from stem.util import term + + SOCKS_PORT = 7000 + + def curl(url): + """ + Uses pycurl to fetch a site using the proxy on the SOCKS_PORT. + """ + + output = StringIO.StringIO() + + query = pycurl.Curl() + query.setopt(pycurl.URL, url) + query.setopt(pycurl.PROXY, 'localhost') + query.setopt(pycurl.PROXYPORT, SOCKS_PORT) + query.setopt(pycurl.PROXYTYPE, pycurl.PROXYTYPE_SOCKS5) + query.setopt(pycurl.WRITEFUNCTION, output.write) + + try: + query.perform() + return output.getvalue() + except pycurl.error, exc: + return "Unable to reach %s (%s)" % (url, exc) + + # Start an instance of tor configured to only exit through Russia. This prints + # tor's bootstrap information as it starts. + + def print_bootstrap_lines(line): + if "Bootstrapped " in line: + print term.format(line, term.Color.BLUE) + + print term.format("Starting Tor:\n", term.Attr.BOLD) + + tor_process = stem.process.launch_tor_with_config( + config = { + 'SocksPort': str(SOCKS_PORT), + 'ExitNodes': '{ru}', + }, + init_msg_handler = print_bootstrap_lines, + ) + + print term.format("\nChecking our endpoint:\n", term.Attr.BOLD) + print term.format(curl("http://www.atagar.com/echo.php"), term.Color.BLUE) + + tor_process.kill() # stops tor + +.. image:: /_static/locale_selection_output.png +