Difference between revisions of "Setting up a Tor hidden service"

From Bitcoin Wiki
Jump to: navigation, search
(note that onion v3 is not supported)
m (added Related Resources)
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
If you use a Bitcoin [[full node]] over Tor, then usually it will only be able to make outgoing connections. Therefore, you will only get a maximum of 8 total connections. This is fine, and is not something you usually need to worry about, but if your computer is often online and you want to be a big help to the network, you can run a Tor hidden service in order to accept incoming connections over Tor.
+
If you use a Bitcoin [[full node]] over Tor, then usually it will only be able to make outgoing connections. Therefore, you will only get a maximum of 10 total connections. This is fine, and is not something you usually need to worry about, but if your computer is often online and you want to be a big help to the network, you can run a Tor hidden service in order to accept incoming connections over Tor.
  
 
Note that there is no need to forward port 8333 when using a Tor hidden service. The hidden service will cause most firewalls and NAT setups to be bypassed. For this reason, running a Tor hidden service is also a good idea if you want incoming connections but are for some reason unable to forward port 8333.
 
Note that there is no need to forward port 8333 when using a Tor hidden service. The hidden service will cause most firewalls and NAT setups to be bypassed. For this reason, running a Tor hidden service is also a good idea if you want incoming connections but are for some reason unable to forward port 8333.
Line 5: Line 5:
 
=== Prerequisites ===
 
=== Prerequisites ===
  
These instructions are for Linux. It is possible to do on Windows, but the instructions would be rather different. (If you've done it on Windows, consider adding the instructions to this page.)
+
These instructions are for Linux. It is possible to do on Windows, the instructions are presented at the end.
  
You need Tor (at least version 0.2.7.1). Figure out where your <tt>torrc</tt> file is (<tt>/etc/tor/torrc</tt> is one possibility). This guide assumes default Tor settings. This guide assumes that Tor is running under the user and group <tt>tor</tt>, which will usually be the case if you install Tor using your distro's package manager. Note that Bitcoin '''does not''' support hidden service version 3 (ie. long onion addresses).
+
You need Tor (at least version 0.2.7.1). Figure out where your <tt>torrc</tt> file is (<tt>/etc/tor/torrc</tt> is one possibility). This guide assumes default Tor settings. This guide assumes that Tor is running under the user and group <tt>tor</tt>, which will usually be the case if you install Tor using your distro's package manager. Note that since version 22.0 Bitcoin '''does not''' support Tor hidden service version 2 (ie. short onion addresses), only support Tor version 3 hidden services (Tor v3, ie. long onion addresses).
  
 
You need Bitcoin Core (or similar). For method 1, you need at least version 0.12.0. Find <tt>bitcoin.conf</tt> in your [[data directory]].
 
You need Bitcoin Core (or similar). For method 1, you need at least version 0.12.0. Find <tt>bitcoin.conf</tt> in your [[data directory]].
  
=== Method 1 (recommended) ===
+
=== Linux Method 1 (recommended) ===
  
This sets up an ephemeral hidden service. The hidden service address (xxxx.onion) will change every time Bitcoin Core is restarted.
+
This sets up an automatic hidden service that is initiated by Bitcoin Core. On the first startup of <tt>bitcoind</tt> after configuring Bitcoin Core to use Tor ControlPort as follows, Bitcoin Core will generate a file called <tt>onion_private_key</tt> in the [[data directory]]. The file <tt>onion_private_key</tt> contains the private key needed to generate your unique <tt>XXXXXXX.onion</tt> address. KEEP THIS SAFE. If someone copies this file they can run a server with your .onion address. Also, if you delete this file, the next time bitcoind loads it will generate a new key file and <tt>xxxxxxxx.onion</tt> address. Note that while a malicious party cannot necessarily associate the server with you as a person, as long as your server has the same xxxx.onion address they will know it is run by the same person. For absolute security delete <tt>onion_private_key</tt> at each reboot or some frequent interval.
  
 
Add these lines to your <tt>torrc</tt>:
 
Add these lines to your <tt>torrc</tt>:
Line 28: Line 28:
 
<pre>usermod -a -G tor BITCOIN_USER</pre>
 
<pre>usermod -a -G tor BITCOIN_USER</pre>
  
If you don't modify any other settings, Bitcoin Core will usually connect over the regular Internet, but will also allow connections to and from the hidden service. If you want Bitcoin Core to only connect via Tor (for anonymity), add these lines to bitcoin.conf:
+
At this point your node will work over Tor without further configuartion. Bitcoin Core v0.12 and later automatically tries to connect to Tor via the ControlPort if <tt>listen=1</tt> is set in <tt>bitcoin.conf</tt>. By default Bitcoin Core will usually connect over the regular Internet as well as allow connections to and from the Tor hidden service. This will help other users who wish to submit transactions to the bitcoin network securely and obscurely, but transactions you submit could theoretically be traced back to your ip address. If you want Bitcoin Core to only connect via Tor (for anonymity), add these lines to [[Running_Bitcoin#Bitcoin.conf_Configuration_File|bitcoin.conf]]:
  
 
<pre>proxy=127.0.0.1:9050
 
<pre>proxy=127.0.0.1:9050
Line 37: Line 37:
 
<pre>onlynet=onion</pre>
 
<pre>onlynet=onion</pre>
  
If you're only interested in running a hidden service in order to help the network, then there's no need to modify any bitcoin.conf settings at all. Bitcoin Core will automatically detect Tor and create the hidden service.
+
Doing so will make your specific bitcoind node arguably more secure because it will never have an unencrypted connection to another node, but if everyone used <tt>onlynet=onion</tt> nobody on the onion bitcoin chain would be able to communicate with the clearnet chain. It is essential that some nodes access both clearnet and Tor. If you need to submit bitcoin transactions to the network with the highest level of obscurity, use <tt>onlynet=onion</tt>. If you only wish to give access to your node to other Tor users, do not use it.
  
Now restart Tor, and then Bitcoin Core. You should eventually get incoming connections via the hidden service.
 
  
=== Method 2 ===
+
Now restart Tor, and then Bitcoin Core. At some point during startup in <tt>~/.bitcoin/debug.log</tt> you will see
 +
<pre>tor: Got service ID XXXXXXXXXXX, advertising service XXXXXXXXXXX.onion:8333</pre> This is the .onion address of your server. You should eventually get incoming connections via the hidden service.
  
This sets up a static hidden service. The hidden service address (xxxx.onion) will never change. This is probably even more helpful for the network, and you will probably get more incoming connections than method 1, but ''maybe'' it would be helpful to someone trying to track your transactions.
+
=== Linux Method 2 ===
 +
 
 +
This sets up a manual hidden service controlled by the tor daemon. The hidden service address (xxxx.onion). Note that as in method 1, your xxxxx.onion address will stay the same until you delete your key file. Someone tracking you can't necessarily associate the xxxx.onion with you, but they will know it is run by the same person or entity.
  
 
Add these lines to your <tt>torrc</tt>:
 
Add these lines to your <tt>torrc</tt>:
Line 70: Line 72:
  
 
Now restart Bitcoin Core. You should eventually get incoming connections via your hidden service.
 
Now restart Bitcoin Core. You should eventually get incoming connections via your hidden service.
 +
 +
=== Windows ===
 +
 +
First you need to download Tor, we recommend the Windows Expert Bundle that contains just Tor and nothing else. This version, without the browser, is located [https://www.torproject.org/download/tor/ here on torproject.org].
 +
 +
Then extract the contents on a folder in a place that your user can access, like ''%UserProfile%''.
 +
 +
On your Windows Explorer go to that folder and create a file called ''torrc''. Open it with Notepad, type the content below and save the file:
 +
<pre>ControlPort 9051
 +
CookieAuthentication 1</pre>
 +
 +
Open Windows PowerShell and navigate to the extracted folder (ex.: ''cd C:\Users\MyUserName\torExpertBundle''), and access the folder ''Tor'' (ie.: ''cd Tor''). Type ''dir'' you should see some files and ''tor.exe'' among them. So type the code below (remember to change the folder accordingly to where you extracted)
 +
 +
<pre>tor.exe --service install -options -f "C:\Users\MyUserName\torExpertBundle\Tor\torrc"</pre>
 +
 +
This will create an entry at Windows Services. Access Windows Services by pressing the Windows button and typing ''services'' then enter. You should see ''Tor Win32 Service (Provides an anonymous Internet communication system)'' on the list. Check if the status is ''Running'' and initialization type is ''Automatic''. To verify if it Tor is really working as a service, open Windows PowerShell then type:
 +
<pre>netstat -aon | findstr ":9050"</pre>
 +
 +
You should see '':9050 LISTENING'':
 +
<pre>  TCP    127.0.0.1:9050        0.0.0.0:0              LISTENING      4000</pre>
 +
 +
Then type:
 +
<pre>netstat -aon | findstr ":9051"</pre>
 +
 +
You should see '':9051 LISTENING'':
 +
<pre>  TCP    127.0.0.1:9051        0.0.0.0:0              LISTENING      4000</pre>
 +
 +
If you don't see these then the Tor service is not working properly and this issue may be related to Windows permissions on the folder you extracted. To fix it go to where you extracted the Tor Expert Bundle and check the top folder ''Properties > Security > Advanced'' and verify if in the Permissions tab you have ''SERVICE'' with ''Full Control'', if not click ''Add'', click on the link ''Select a Secure Entity and type ''SERVICE'' (all letters in UPPERCASE) then hit enter and select ''Full Control'' (Try to start the Tor service again in Windows Services, if it doesn't work, try adding ''SYSTEM'' and ''LOCAL SERVICE'' with ''Full Control'' on folder permissions and repeat the tests above).
 +
 +
If you want to see on BitcoinCore ''debug.log'' file what is happening on the communication with the Tor service, edit your ''bitcoin.conf'' file and add this line at the end ''debug=tor'', then restart BitcoinCore. If everything is ok, you should see something like that:
 +
<pre>2022-06-13T21:45:32Z Config file arg: debug="tor"
 +
2022-06-13T21:45:44Z torcontrol thread start
 +
2022-06-13T21:45:44Z tor: Reading cached private key from C:\YourBitcoinFolder\onion_v3_private_key
 +
2022-06-13T21:45:44Z tor: Successfully connected!
 +
2022-06-13T21:45:44Z tor: Connected to Tor version 0.4.x.x
 +
2022-06-13T21:45:44Z tor: Supported authentication method: COOKIE
 +
2022-06-13T21:45:44Z tor: Supported authentication method: SAFECOOKIE
 +
2022-06-13T21:45:44Z tor: Using SAFECOOKIE authentication, reading cookie authentication from C:\Windows\ServiceProfiles\LocalService\AppData\Roaming\tor\control_auth_cookie
 +
2022-06-13T21:45:44Z Leaving InitialBlockDownload (latching to false)
 +
2022-06-13T21:45:44Z tor: SAFECOOKIE authentication challenge successful
 +
2022-06-13T21:45:44Z tor: AUTHCHALLENGE ServerHash xxxxx ServerNonce xxxxx
 +
2022-06-13T21:45:44Z tor: Authentication successful</pre>
 +
 +
== Related Resources ==
 +
 +
* [https://www.keepitsimplebitcoin.com/how-to-install-tor/ KeepItSimpleBitcoin How To Install Tor (Mac OS, Linux, Windows)] - text and video instructions including Bitcoin Core config.
 +
* [https://bitcoincoredocs.com/tor.html Bitcoin Core Docs Tor] - Explanation of the Bitcoin Core configs related to Tor.
  
 
[[Category:Guides]]
 
[[Category:Guides]]
 +
[[Category:Privacy]]

Revision as of 00:24, 21 June 2022

If you use a Bitcoin full node over Tor, then usually it will only be able to make outgoing connections. Therefore, you will only get a maximum of 10 total connections. This is fine, and is not something you usually need to worry about, but if your computer is often online and you want to be a big help to the network, you can run a Tor hidden service in order to accept incoming connections over Tor.

Note that there is no need to forward port 8333 when using a Tor hidden service. The hidden service will cause most firewalls and NAT setups to be bypassed. For this reason, running a Tor hidden service is also a good idea if you want incoming connections but are for some reason unable to forward port 8333.

Prerequisites

These instructions are for Linux. It is possible to do on Windows, the instructions are presented at the end.

You need Tor (at least version 0.2.7.1). Figure out where your torrc file is (/etc/tor/torrc is one possibility). This guide assumes default Tor settings. This guide assumes that Tor is running under the user and group tor, which will usually be the case if you install Tor using your distro's package manager. Note that since version 22.0 Bitcoin does not support Tor hidden service version 2 (ie. short onion addresses), only support Tor version 3 hidden services (Tor v3, ie. long onion addresses).

You need Bitcoin Core (or similar). For method 1, you need at least version 0.12.0. Find bitcoin.conf in your data directory.

Linux Method 1 (recommended)

This sets up an automatic hidden service that is initiated by Bitcoin Core. On the first startup of bitcoind after configuring Bitcoin Core to use Tor ControlPort as follows, Bitcoin Core will generate a file called onion_private_key in the data directory. The file onion_private_key contains the private key needed to generate your unique XXXXXXX.onion address. KEEP THIS SAFE. If someone copies this file they can run a server with your .onion address. Also, if you delete this file, the next time bitcoind loads it will generate a new key file and xxxxxxxx.onion address. Note that while a malicious party cannot necessarily associate the server with you as a person, as long as your server has the same xxxx.onion address they will know it is run by the same person. For absolute security delete onion_private_key at each reboot or some frequent interval.

Add these lines to your torrc:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

You need to figure out what user bitcoind or bitcoin-qt is running as. Run the following command while Bitcoin is running:

ps -eo user,group,comm |egrep 'bitcoind|bitcoin-qt' |awk '{print "Bitcoin user: " $1}'

Write down the reported user.

Run the following command as root, which adds your Bitcoin user to the tor group. Replace BITCOIN_USER with the actual user name found above:

usermod -a -G tor BITCOIN_USER

At this point your node will work over Tor without further configuartion. Bitcoin Core v0.12 and later automatically tries to connect to Tor via the ControlPort if listen=1 is set in bitcoin.conf. By default Bitcoin Core will usually connect over the regular Internet as well as allow connections to and from the Tor hidden service. This will help other users who wish to submit transactions to the bitcoin network securely and obscurely, but transactions you submit could theoretically be traced back to your ip address. If you want Bitcoin Core to only connect via Tor (for anonymity), add these lines to bitcoin.conf:

proxy=127.0.0.1:9050
listen=1
bind=127.0.0.1

If you additionally want Bitcoin Core to only connect out to Tor hidden services, also add this line (not particularly recommended):

onlynet=onion

Doing so will make your specific bitcoind node arguably more secure because it will never have an unencrypted connection to another node, but if everyone used onlynet=onion nobody on the onion bitcoin chain would be able to communicate with the clearnet chain. It is essential that some nodes access both clearnet and Tor. If you need to submit bitcoin transactions to the network with the highest level of obscurity, use onlynet=onion. If you only wish to give access to your node to other Tor users, do not use it.


Now restart Tor, and then Bitcoin Core. At some point during startup in ~/.bitcoin/debug.log you will see

tor: Got service ID XXXXXXXXXXX, advertising service XXXXXXXXXXX.onion:8333
This is the .onion address of your server. You should eventually get incoming connections via the hidden service.

Linux Method 2

This sets up a manual hidden service controlled by the tor daemon. The hidden service address (xxxx.onion). Note that as in method 1, your xxxxx.onion address will stay the same until you delete your key file. Someone tracking you can't necessarily associate the xxxx.onion with you, but they will know it is run by the same person or entity.

Add these lines to your torrc:

HiddenServiceDir /var/lib/tor/bitcoin-service/
HiddenServicePort 8333 127.0.0.1:8333

Restart Tor. As root, run cat /var/lib/tor/bitcoin-service/hostname. Your onion address will be reported. If it didn't work, then probably your distro's version of Tor doesn't actually use /var/lib/tor for this purpose. You should try to figure out the correct HiddenServiceDir location.

In the following steps, replace ONION_ADDR with the onion address reported above.

If you don't care about anonymity and are only looking to help the network, add the following lines to bitcoin.conf:

onion=127.0.0.1:9050
listen=1
externalip=ONION_ADDR
discover=1

This will allow you to accept connections both via your onion address and your IP address (if you have port 8333 forwarded), and Tor will only be used for connections to and from Tor hidden services.

If you care about anonymity, instead of the above, add the following lines to bitcoin.conf to use Tor for everything:

proxy=127.0.0.1:9050
listen=1
bind=127.0.0.1
externalip=ONION_ADDR

If you additionally want Bitcoin Core to only connect out to Tor hidden services, also add this line (not particularly recommended):

onlynet=onion

Now restart Bitcoin Core. You should eventually get incoming connections via your hidden service.

Windows

First you need to download Tor, we recommend the Windows Expert Bundle that contains just Tor and nothing else. This version, without the browser, is located here on torproject.org.

Then extract the contents on a folder in a place that your user can access, like %UserProfile%.

On your Windows Explorer go to that folder and create a file called torrc. Open it with Notepad, type the content below and save the file:

ControlPort 9051
CookieAuthentication 1

Open Windows PowerShell and navigate to the extracted folder (ex.: cd C:\Users\MyUserName\torExpertBundle), and access the folder Tor (ie.: cd Tor). Type dir you should see some files and tor.exe among them. So type the code below (remember to change the folder accordingly to where you extracted)

tor.exe --service install -options -f "C:\Users\MyUserName\torExpertBundle\Tor\torrc"

This will create an entry at Windows Services. Access Windows Services by pressing the Windows button and typing services then enter. You should see Tor Win32 Service (Provides an anonymous Internet communication system) on the list. Check if the status is Running and initialization type is Automatic. To verify if it Tor is really working as a service, open Windows PowerShell then type:

netstat -aon | findstr ":9050"

You should see :9050 LISTENING:

  TCP    127.0.0.1:9050         0.0.0.0:0              LISTENING       4000

Then type:

netstat -aon | findstr ":9051"

You should see :9051 LISTENING:

  TCP    127.0.0.1:9051         0.0.0.0:0              LISTENING       4000

If you don't see these then the Tor service is not working properly and this issue may be related to Windows permissions on the folder you extracted. To fix it go to where you extracted the Tor Expert Bundle and check the top folder Properties > Security > Advanced and verify if in the Permissions tab you have SERVICE with Full Control, if not click Add, click on the link Select a Secure Entity and type SERVICE (all letters in UPPERCASE) then hit enter and select Full Control (Try to start the Tor service again in Windows Services, if it doesn't work, try adding SYSTEM and LOCAL SERVICE with Full Control on folder permissions and repeat the tests above).

If you want to see on BitcoinCore debug.log file what is happening on the communication with the Tor service, edit your bitcoin.conf file and add this line at the end debug=tor, then restart BitcoinCore. If everything is ok, you should see something like that:

2022-06-13T21:45:32Z Config file arg: debug="tor"
2022-06-13T21:45:44Z torcontrol thread start
2022-06-13T21:45:44Z tor: Reading cached private key from C:\YourBitcoinFolder\onion_v3_private_key
2022-06-13T21:45:44Z tor: Successfully connected!
2022-06-13T21:45:44Z tor: Connected to Tor version 0.4.x.x
2022-06-13T21:45:44Z tor: Supported authentication method: COOKIE
2022-06-13T21:45:44Z tor: Supported authentication method: SAFECOOKIE
2022-06-13T21:45:44Z tor: Using SAFECOOKIE authentication, reading cookie authentication from C:\Windows\ServiceProfiles\LocalService\AppData\Roaming\tor\control_auth_cookie
2022-06-13T21:45:44Z Leaving InitialBlockDownload (latching to false)
2022-06-13T21:45:44Z tor: SAFECOOKIE authentication challenge successful
2022-06-13T21:45:44Z tor: AUTHCHALLENGE ServerHash xxxxx ServerNonce xxxxx
2022-06-13T21:45:44Z tor: Authentication successful

Related Resources