1Over the River and Through the Wood
2===================================
3
4`Hidden services <https://www.torproject.org/docs/hidden-services.html.en>`_
5give you a way of providing a service without exposing your address. These
6services are only accessible through Tor or `Tor2web <https://tor2web.org/>`_,
7and useful for a surprising number of things...
8
9* **Hosting an anonymized site**. This is usually the first thing that comes to
10  mind, and something we'll demonstrate in a sec.
11
12* Providing an **endpoint Tor users can reach** without exiting the Tor
13  network. This eliminates the risk of an unreliable or malicious exit getting
14  in the way. Great examples of this are `Facebook
15  <http://arstechnica.com/security/2014/10/facebook-offers-hidden-service-to-tor-users/>`_
16  (*facebookcorewwwi.onion*) and `DuckDuckGo
17  <https://lists.torproject.org/pipermail/tor-talk/2010-August/003095.html>`_
18  (*3g2upl4pq6kufc4m.onion*).
19
20* **Personal services**. For instance you can host your home SSH server as a
21  hidden service to prevent eavesdroppers from knowing where you live while
22  traveling abroad.
23
24`Tor2web <https://tor2web.org/>`_ provides a quick and easy way of seeing if
25your hidden service is working. To use it simply replace the **.onion** of
26your address with **.tor2web.org**...
27
28.. image:: /_static/duck_duck_go_hidden_service.png
29   :target: https://3g2upl4pq6kufc4m.tor2web.org/
30
31.. _running-a-hidden-service:
32
33Running a hidden service
34------------------------
35
36Hidden services can be `configured through your torrc
37<https://www.torproject.org/docs/tor-manual.html.en#_hidden_service_options>`_,
38but Stem also provides some methods to easily work with them...
39
40  * :func:`~stem.control.Controller.create_hidden_service`
41  * :func:`~stem.control.Controller.remove_hidden_service`
42  * :func:`~stem.control.Controller.get_hidden_service_conf`
43  * :func:`~stem.control.Controller.set_hidden_service_conf`
44
45The main threat to your anonymity when running a hidden service is the service
46itself. Debug information for instance might leak your real address,
47undermining what Tor provides. This includes the following example, **do not
48rely on it not to leak**.
49
50But with that out of the way lets take a look at a simple `Flask
51<http://flask.pocoo.org/>`_ example based on one by `Jordan Wright
52<https://jordan-wright.github.io/blog/2014/10/06/creating-tor-hidden-services-with-python/>`_...
53
54.. literalinclude:: /_static/example/running_hidden_service.py
55   :language: python
56
57Now if we run this...
58
59::
60
61  % python example.py
62   * Connecting to tor
63   * Creating our hidden service in /home/atagar/.tor/hello_world
64   * Our service is available at uxiuaxejc3sxrb6i.onion, press ctrl+c to quit
65   * Running on http://127.0.0.1:5000/
66  127.0.0.1 - - [15/Dec/2014 13:05:43] "GET / HTTP/1.1" 200 -
67   * Shutting down our hidden service
68
69... we'll have a service we can visit via the `Tor Browser Bundle <https://www.torproject.org/download/download-easy.html.en>`_...
70
71.. image:: /_static/hidden_service.png
72
73.. _hidden-service-authentication:
74
75Hidden service authentication
76-----------------------------
77
78Hidden services you create can restrict their access, requiring in essence a
79password...
80
81::
82
83  >>> from stem.control import Controller
84  >>> controller = Controller.from_port()
85  >>> controller.authenticate()
86  >>> response = controller.create_ephemeral_hidden_service({80: 8080}, await_publication=True, basic_auth={'bob': None, 'alice': None})
87  >>> response.service_id, response.client_auth
88  ('l3lnorirzn7hrjnw', {'alice': 'I6AMKiay+UkM5MfrvdnF2A', 'bob': 'VLsbrSGyrb5JYEvZmQ3tMg'})
89
90To access this service users simply provide this credential to tor via their
91torrc or SETCONF prior to visiting it...
92
93::
94
95  >>> controller.set_conf('HidServAuth', 'l3lnorirzn7hrjnw.onion I6AMKiay+UkM5MfrvdnF2A')
96
97.. _ephemeral-hidden-services:
98
99Ephemeral hidden services
100-------------------------
101
102In the above example you may have noticed the note that said...
103
104::
105
106  # The hostname is only available when we can read the hidden service
107  # directory. This requires us to be running with the same user as tor.
108
109This has been a limitation of hidden services for years. However, as of version
1100.2.7.1 Tor offers another style for making services called **ephemeral hidden
111services**.
112
113Ephemeral services can only be created through the controller, and only exist
114as long as your controller is attached unless you provide the **detached**
115flag. Controllers can only see their own ephemeral services, and ephemeral
116services that are detached. In other words, attached ephemeral services can
117only be managed by their own controller.
118
119Stem provides three methods to work with ephemeral hidden services...
120
121  * :func:`~stem.control.Controller.list_ephemeral_hidden_services`
122  * :func:`~stem.control.Controller.create_ephemeral_hidden_service`
123  * :func:`~stem.control.Controller.remove_ephemeral_hidden_service`
124
125For example, with a ephemeral service our earlier example becomes as simple as...
126
127.. literalinclude:: /_static/example/ephemeral_hidden_services.py
128   :language: python
129
130Ephemeral hidden services do not touch disk, and as such are easier to work
131with but require you to persist your service's private key yourself if you want
132to reuse a '.onion' address...
133
134.. literalinclude:: /_static/example/resuming_ephemeral_hidden_service.py
135   :language: python
136
137.. _hidden-service-descriptors:
138
139Hidden service descriptors
140--------------------------
141
142Like relays, hidden services publish documents about themselves called **hidden
143service descriptors**. These contain low level details for establishing
144connections. Hidden service descriptors are available from the tor process via
145its :func:`~stem.control.Controller.get_hidden_service_descriptor` method...
146
147.. literalinclude:: /_static/example/get_hidden_service_descriptor.py
148   :language: python
149
150::
151
152  % python print_duck_duck_go_descriptor.py
153
154  rendezvous-service-descriptor e5dkwgp6vt7axoozixrbgjymyof7ab6u
155  version 2
156  permanent-key
157  -----BEGIN RSA PUBLIC KEY-----
158  MIGJAoGBAJ/SzzgrXPxTlFrKVhXh3buCWv2QfcNgncUpDpKouLn3AtPH5Ocys0jE
159  aZSKdvaiQ62md2gOwj4x61cFNdi05tdQjS+2thHKEm/KsB9BGLSLBNJYY356bupg
160  I5gQozM65ENelfxYlysBjJ52xSDBd8C4f/p9umdzaaaCmzXG/nhzAgMBAAE=
161  -----END RSA PUBLIC KEY-----
162  secret-id-part bmsctib2pzirgo7cltlxdm5fxqcitt5e
163  publication-time 2015-05-11 20:00:00
164  protocol-versions 2,3
165  introduction-points
166  -----BEGIN MESSAGE-----
167  aW50cm9kdWN0aW9uLXBvaW50IHZzcm4ycGNtdzNvZ21mNGo3dGpxeHptdml1Y2Rr
168  NGtpCmlwLWFkZHJlc3MgMTc2LjkuNTkuMTcxCm9uaW9uLXBvcnQgOTAwMQpvbmlv
169  ... etc...
170
171A hidden service's introduction points are a base64 encoded field that's
172possibly encrypted. These can be decoded (and decrypted if necessary) with the
173descriptor's
174:func:`~stem.descriptor.hidden_service.HiddenServiceDescriptor.introduction_points`
175method.
176
177.. literalinclude:: /_static/example/introduction_points.py
178   :language: python
179
180::
181
182  % python print_duck_duck_go_introduction_points.py
183
184  DuckDuckGo's introduction points are...
185
186    176.9.59.171:9001 => vsrn2pcmw3ogmf4j7tjqxzmviucdk4ki
187    104.131.106.181:9001 => gcl2kpqx5qnkpgxjf6x7ulqncoqj7ghh
188    188.166.58.218:443 => jeymnbhs2d6l2oib7jjvweavg45m6gju
189
190