commit a96be5d44ce37f14d9f6b2be9c2e9b5aeb6f4235 Author: gus gus@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#ClientAuthori...). + +## 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#HiddenServiceAuthori...) 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%%7BREQUEST_URI%7Ds" +``` + +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%%7BREQUEST_U..." + </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$reques...; + } +``` + +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$reques...; + } +} +``` + +**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-...). 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-pract...). +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).