[tor-commits] [community/master] Create Advanced settings section: Onion-Location, Client authorization and Opsec tips
gus at torproject.org
gus at torproject.org
Mon Jun 1 18:58:07 UTC 2020
commit a96be5d44ce37f14d9f6b2be9c2e9b5aeb6f4235
Author: gus <gus at torproject.org>
Date: Wed May 27 23:37:27 2020 -0400
Create Advanced settings section: Onion-Location, Client authorization and Opsec tips
---
.../advanced/client-auth/contents.lr | 125 ++++++++++++++++++
content/onion-services/advanced/contents.lr | 19 +++
.../advanced/onion-location/contents.lr | 147 +++++++++++++++++++++
content/onion-services/advanced/opsec/contents.lr | 32 +++++
4 files changed, 323 insertions(+)
diff --git a/content/onion-services/advanced/client-auth/contents.lr b/content/onion-services/advanced/client-auth/contents.lr
new file mode 100644
index 0000000..071a8e7
--- /dev/null
+++ b/content/onion-services/advanced/client-auth/contents.lr
@@ -0,0 +1,125 @@
+_section: Advanced settings
+---
+section_id: onion-services
+---
+color: primary
+---
+_template: layout.html
+---
+title: Client Authorization
+---
+subtitle: Learn how to set up client authorization for your onion services.
+---
+key: 2
+---
+html: two-columns-page.html
+---
+body:
+
+Client authorization is a method to make an onion service private and authenticated.
+It requires Tor clients to provide an authentication credential in order to connect to the onion service.
+In version 3 Onion services, this method works with a pair of keys (a public and a private).
+The service side will be configured with a public key and the client can only access with a private key.
+
+**Note:** Once you've configured client authorization, anyone else with the address won't be able to access it from this point on.
+If no authorization is configured, the service will be accessible to anyone with the onion address.
+
+## Configuring version 3 Onion service
+
+### Service side
+
+To configure client authorization on the service side, the `<HiddenServiceDir>/authorized_clients/` directory needs to exist. Following the instructions described in the section [Setup](https://community.torproject.org/onion-services/setup/) will automatically create this directory.
+Client authorization will only be enabled for the service if tor successfully loads at least one authorization file.
+
+At the moment you need to create the keys yourself with a script (like these written in [Bash](https://gist.github.com/mtigas/9c2386adf65345be34045dace134140b), [Rust](https://github.com/haxxpop/torkeygen) or [Python](https://github.com/pastly/python-snippits/blob/master/src/tor/x25519-gen.py)) or manually.
+
+To manually generate the keys, you need to install `openssl` version 1.1+ and `basez`.
+
+**Step 1.** Generate a key using the algorithm x25519:
+
+ $ openssl genpkey -algorithm x25519 -out /tmp/k1.prv.pem
+
+If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.
+
+**Step 2.** Format the keys into base32:
+
+**Private key**
+
+```
+$ cat /tmp/k1.prv.pem | grep -v " PRIVATE KEY" | base64pem -d | tail --bytes=32 | base32 | sed 's/=//g' > /tmp/k1.prv.key
+```
+
+**Public key**
+
+```
+$ openssl pkey -in /tmp/k1.prv.pem -pubout | grep -v " PUBLIC KEY" | base64pem -d | tail --bytes=32 | base32 | sed 's/=//g' > /tmp/k1.pub.key
+```
+
+**Step 3.** Copy the public key:
+
+ $ cat /tmp/k1.pub.key
+
+**Step 4.** Create an authorized client file
+
+Format the client authentication and create a new file in `<HiddenServiceDir>/authorized_clients/` directory.
+Each file in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the file name is irrelevant) and its content format must be:
+
+ <auth-type>:<key-type>:<base32-encoded-public-key>
+
+The supported `<auth-type>` are: "descriptor".
+
+The supported `<key-type>` are:"x25519".
+
+The `<base32-encoded-public-key>` is the base32 representation of the raw key bytes only (32 bytes for x25519).
+
+For example, the file `/var/lib/tor/hidden_service/authorized_clients/alice.auth` should look like:
+
+ descriptor:x25519:N2NU7BSRL6YODZCYPN4CREB54TYLKGIE2KYOQWLFYC23ZJVCE5DQ
+
+If you're planning to have more authenticated clients, each file must contain one line only. Any malformed file will be ignored.
+
+**Step 5.** Restart the tor service
+
+ $ sudo systemctl reload tor
+
+If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.
+
+**Important:** Revoking a client can be done by removing their ".auth" file, however the revocation will be in effect only after the tor process gets restarted.
+
+### Client side
+
+To access a version 3 onion service with client authorization as a client, make sure you have `ClientOnionAuthDir` set in your torrc.
+For example, add this line to `/etc/tor/torrc`:
+
+ ClientOnionAuthDir /var/lib/tor/onion_auth
+
+Then, in the `<ClientOnionAuthDir>` directory, create an `.auth_private` file for the onion service corresponding to this key (i.e. 'bob_onion.auth_private').
+The contents of the `<ClientOnionAuthDir>/<user>.auth_private` file should look like:
+
+ <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>
+
+For example:
+
+ rh5d6reakhpvuxe2t3next6um6iiq4jf43m7gmdrphfhopfpnoglzcyd:descriptor:x25519:ZDUVQQ7IKBXSGR2WWOBNM3VP5ELNOYSSINDK7CAUN2WD7A3EKZWQ
+
+If you manually generated the key pair following the instructions in this page, you can copy and use the private key created in **Step 2**.
+Then restart `tor` and you should be able to connect to the onion service address.
+
+If you're generating a private key for an onionsite, the user doesn't necessarily need to edit Tor Browser's torrc. It's possible to enter the private key directly in [Tor Browser](https://tb-manual.torproject.org/onion-services/) interface.
+
+For more information about client authentication, please see [Tor manual](https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization).
+
+## Configuring version 2 Onion service
+
+To set up Cookie Authentication for **v2** services see the entries for the [HidServAuth](https://2019.www.torproject.org/docs/tor-manual.html.en#HidServAuth) and [HiddenServiceAuthorizeClient](https://2019.www.torproject.org/docs/tor-manual.html.en#HiddenServiceAuthorizeClient) options in the tor manual.
+First add the following line to the [torrc](https://2019.www.torproject.org/docs/faq.html.en#torrc) file of your onion service:
+
+ HiddenServiceAuthorizeClient [auth-type] [service-name]
+
+Restart tor and read the cookie from the hostname file of your onion service, for example in
+`/var/lib/tor/hidden_service_path/hostname`.
+To access it with a tor client add following line to torrc and restart tor:
+
+ HidServAuth [onion-address] [auth-cookie] [service-name]
+
+You are now able to connect to the onion service address.
diff --git a/content/onion-services/advanced/contents.lr b/content/onion-services/advanced/contents.lr
new file mode 100644
index 0000000..a17e990
--- /dev/null
+++ b/content/onion-services/advanced/contents.lr
@@ -0,0 +1,19 @@
+_section: onion services
+---
+section_id: onion-services
+---
+color: primary
+---
+_template: layout.html
+---
+title: Advanced settings
+---
+subtitle: Learn more about how to configure client authentication, Onion-Location and more tips to secure your onion service.
+---
+key: 3
+---
+html: two-columns-page.html
+---
+body:
+
+In this section you will find how to configure your onion service to enable client authorization, Onion-Location and tips to make your onion service more secure.
diff --git a/content/onion-services/advanced/onion-location/contents.lr b/content/onion-services/advanced/onion-location/contents.lr
new file mode 100644
index 0000000..caf7d5f
--- /dev/null
+++ b/content/onion-services/advanced/onion-location/contents.lr
@@ -0,0 +1,147 @@
+_section: advanced configuration
+---
+section_id: onion-services
+---
+color: primary
+---
+_template: layout.html
+---
+title: Onion-Location
+---
+subtitle: Learn how to set up Onion-Location for your onionsite.
+---
+key: 1
+---
+html: two-columns-page.html
+---
+body:
+
+Onion-Location is an easy way to advertise an onionsite to the users.
+You can either configure a web server to show an Onion-Location Header or add an HTML meta attibute in the website.
+
+For the header to be valid the following conditions need to be fulfilled:
+
+ * The Onion-Location value must be a valid URL with http: or https: protocol and a .onion hostname.
+ * The webpage defining the Onion-Location header must be served over HTTPS.
+ * The webpage defining the Onion-Location header must not be an onionsite.
+
+In this page, the commands to restart the web server are based on Debian-like operating systems and may differ on other systems.
+Check your web server and operating system documentation.
+
+### Apache
+
+To configure this header in Apache 2.2 or above, you will need to enable a few modules and edit the website Virtual Host file.
+
+**Step 1.** Enable headers and rewrite modules and restart Apache2
+
+ $ sudo a2enmod headers rewrite
+
+ $ sudo systemctl restart apache2
+
+If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.
+
+**Step 2.** Add the Onion-Location header to your Virtual Host configuration file
+
+```
+Header set Onion-Location "http://your-onion-address.onion%{REQUEST_URI}s"
+```
+
+Where `your-onion-address.onion` is the onion service address you want to redirect and `{REQUEST_URI}` is the [path component of the requested URI](https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html), such as "/index.html".
+
+Virtual Host example:
+
+```
+ <VirtualHost *:443>
+ ServerName your-website.tld
+ DocumentRoot /var/www/html
+ Header set Onion-Location "http://rh5d6reakhpvuxe2t3next6um6iiq4jf43m7gmdrphfhopfpnoglzcyd%{REQUEST_URI}s"
+ </VirtualHost>
+```
+
+**Step 3.** Reload Apache
+
+Reload the apache2 service so your configuration changes take effect:
+
+ $ sudo systemctl reload apache2
+
+If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.
+
+**Step 4.** Testing your Onion-Location
+
+To test if Onion-Location is working, fetch the website HTTP headers, for example:
+
+ $ wget --server-response --spider your-website.tld
+
+Look for the `onion-location` entry and the onion service address.
+
+Or open the website in Tor Browser and a purple pill will appear in the address bar.
+
+### Nginx
+
+To configure Onion-Location header, you will need to edit Nginx website configuration file.
+
+**Step 1.** Edit website configuration file
+
+In `/etc/nginx/conf.d/<your-website.conf` add the new Onion-Location header and the onion service address.
+For example:
+
+```
+ location / {
+ add_header Onion-Location http://rh5d6reakhpvuxe2t3next6um6iiq4jf43m7gmdrphfhopfpnoglzcyd.onion$request_uri;
+ }
+```
+
+The configuration file with Onion-Location should look like:
+
+```
+server {
+ listen 443;
+
+ root /var/www/your-website/html;
+ index index.html index.htm;
+
+ server_name your-website.tld;
+
+ location / {
+ try_files $uri $uri/ =404;
+ add_header Onion-Location http://rh5d6reakhpvuxe2t3next6um6iiq4jf43m7gmdrphfhopfpnoglzcyd.onion$request_uri;
+ }
+}
+```
+
+**Step 2.** Test website configuration
+
+ $ sudo nginx -t
+
+The web server should confirm that the new syntax is working:
+
+```
+nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
+nginx: configuration file /etc/nginx/nginx.conf test is successful
+```
+
+**Step 3.** Restart nginx
+
+ $ sudo nginx -s reload
+
+If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.
+
+**Step 4.** Testing your Onion-Location
+
+To test if Onion-Location is working, fetch the website HTTP headers, for example:
+
+ $ wget --server-response --spider your-website.tld
+
+Look for the `onion-location` entry and the onion service address.
+
+Or open the website in Tor Browser and a purple pill will appear in the address bar.
+
+### Using an HTML `<meta>` attribute
+
+The identical behaviour of Onion-Location and a Refresh header (with 0 seconds timeout) includes the option of defining it as a HTML `<meta>` http-equiv attribute.
+This may be used by websites that prefer (or need) to define Onion-Location by modifying the served HTML content instead of adding a new HTTP header.
+The Onion-Location header would be equivalent to a `<meta http-equiv="onion-location" content="http://<your-onion-service-address>.onion" />` added in the HTML head element of the webpage. Replace `<your-onion-service-address.onion>` with the onion service that you want to redirect.
+
+### More information
+
+Read the [Onion-Location spec](https://gitweb.torproject.org/tor-browser-spec.git/tree/proposals/100-onion-location-header.txt).
diff --git a/content/onion-services/advanced/opsec/contents.lr b/content/onion-services/advanced/opsec/contents.lr
new file mode 100644
index 0000000..6debce0
--- /dev/null
+++ b/content/onion-services/advanced/opsec/contents.lr
@@ -0,0 +1,32 @@
+_section: onion services
+---
+section_id: onion-services
+---
+color: primary
+---
+_template: layout.html
+---
+title: Operational Security
+---
+subtitle: Learn more tips to secure your Onion Services.
+---
+key: 3
+---
+html: two-columns-page.html
+---
+body:
+
+Onion services operators need to practice proper [operational security](https://trac.torproject.org/projects/tor/wiki/doc/OperationalSecurity) and system administration to maintain security.
+For some security suggestions please make sure you read over Riseup's ["Tor Hidden (Onion) Services Best Practices" document](https://riseup.net/en/security/network-security/tor/onionservices-best-practices).
+Also, here are some more anonymity issues you should keep in mind:
+
+ - As mentioned [here](https://community.torproject.org/onion-services/setup/), be careful of letting your web server reveal identifying information about you, your computer, or your location.
+For example, readers can probably determine whether it's thttpd or Apache, and learn something about your operating system.
+ - If your computer isn't online all the time, your onion service won't be either.
+This leaks information to an observant adversary.
+ - It is generally a better idea to host onion services on a Tor client rather than a Tor relay, since relay uptime and other properties are publicly visible.
+ - The longer an onion service is online, the higher the risk that its location is discovered.
+The most prominent attacks are building a profile of the onion service's availability and matching induced traffic patterns.
+ - Another common issue is whether to use HTTPS on your onionsite or not.
+Have a look at [this post](https://blog.torproject.org/blog/facebook-hidden-services-and-https-certs) on the Tor Blog to learn more about these issues.
+ - To protect your onion service from advanced attacks you should use [Vanguards addon](https://github.com/mikeperry-tor/vanguards), read [Tor blog about Vanguards](https://blog.torproject.org/announcing-vanguards-add-onion-services) and [Vanguards' Security README](https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md).
More information about the tor-commits
mailing list