tor.md
1 # TOR SUPPORT IN BITCOIN 2 3 It is possible to run Bitcoin Core as a Tor onion service, and connect to such services. 4 5 The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. 6 ## Compatibility 7 8 - Starting with version 22.0, Bitcoin Core only supports Tor version 3 hidden 9 services (Tor v3). Tor v2 addresses are ignored by Bitcoin Core and neither 10 relayed nor stored. 11 12 - Tor removed v2 support beginning with version 0.4.6. 13 14 ## How to see information about your Tor configuration via Bitcoin Core 15 16 There are several ways to see your local onion address in Bitcoin Core: 17 - in the "Local addresses" output of CLI `-netinfo` 18 - in the "localaddresses" output of RPC `getnetworkinfo` 19 - in the debug log (grep for "AddLocal"; the Tor address ends in `.onion`) 20 21 You may set the `-debug=tor` config logging option to have additional 22 information in the debug log about your Tor configuration. 23 24 CLI `-addrinfo` returns the number of addresses known to your node per 25 network. This can be useful to see how many onion peers your node knows, 26 e.g. for `-onlynet=onion`. 27 28 You can use the `getnodeaddresses` RPC to fetch a number of onion peers known to your node; run `bitcoin-cli help getnodeaddresses` for details. 29 30 `bitcoin rpc` can also be substituted for `bitcoin-cli`. 31 32 ## 1. Run Bitcoin Core behind a Tor proxy 33 34 The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all 35 outgoing connections, but more is possible. 36 37 -proxy=ip[:port] 38 Set the proxy server. It will be used to try to reach .onion addresses 39 as well. You need to use -noonion or -onion=0 to explicitly disable 40 outbound access to onion services. 41 42 -proxy=ip[:port]=tor 43 or 44 -onion=ip[:port] 45 Set the proxy server for reaching .onion addresses. You do not need to 46 set this if it's the same as the generic -proxy. You can use -onion=0 to 47 explicitly disable access to onion services. 48 ------------------------------------------------------------------------ 49 Note: The proxy for DNS requests is taken from 50 -proxy=addr:port or 51 -proxy=addr:port=ipv4 or 52 -proxy=addr:port=ipv6 53 (last one if multiple options are given). It is not taken from 54 -proxy=addr:port=tor or 55 -onion=addr:port. 56 If no proxy for DNS requests is configured, then they will be done using 57 the functions provided by the operating system, most likely resulting in 58 them being done over the clearnet to the DNS servers of the internet 59 service provider. 60 ------------------------------------------------------------------------ 61 62 If -proxy or -onion is specified multiple times, later occurrences override 63 earlier ones and command line overrides the config file. UNIX domain sockets may 64 be used for proxy connections. Set `-onion` or `-proxy` to the local socket path 65 with the prefix `unix:` (e.g. `-onion=unix:/home/me/torsocket`). 66 67 -listen 68 When using -proxy, listening is disabled by default. If you want to 69 manually configure an onion service (see section 3), you'll need to 70 enable it explicitly. 71 72 -connect=X 73 -addnode=X 74 -seednode=X 75 When behind a Tor proxy, you can specify .onion addresses instead of IP 76 addresses or hostnames in these parameters. Such addresses can also be 77 exchanged with other P2P nodes. 78 79 -onlynet=onion 80 Make automatic outbound connections only to .onion addresses. Inbound 81 and manual connections are not affected by this option. It can be 82 specified multiple times to allow multiple networks, e.g. onlynet=onion, 83 onlynet=i2p, onlynet=cjdns. 84 85 In a typical situation, this suffices to run behind a Tor proxy: 86 87 bitcoind -proxy=127.0.0.1:9050 88 89 `bitcoin node` or `bitcoin gui` can also be substituted for `bitcoind`. 90 91 ## 2. Automatically create a Bitcoin Core onion service 92 93 Bitcoin Core makes use of Tor's control socket API to create and destroy 94 ephemeral onion services programmatically. This means that if Tor is running and 95 proper authentication has been configured, Bitcoin Core automatically creates an 96 onion service to listen on. The goal is to increase the number of available 97 onion nodes. 98 99 This feature is enabled by default if Bitcoin Core is listening (`-listen`) and 100 it requires a Tor connection to work. It can be explicitly disabled with 101 `-listenonion=0`. If it is not disabled, it can be configured using the 102 `-torcontrol` and `-torpassword` settings. 103 104 To see verbose Tor information in the bitcoind debug log, pass `-debug=tor`. 105 106 ### Control Port 107 108 You may need to set up the Tor Control Port. On Linux distributions there may be 109 some or all of the following settings in `/etc/tor/torrc`, generally commented 110 out by default (if not, add them): 111 112 ``` 113 ControlPort 9051 114 CookieAuthentication 1 115 CookieAuthFileGroupReadable 1 116 DataDirectoryGroupReadable 1 117 ``` 118 119 Add or uncomment those, save, and restart Tor (usually `systemctl restart tor` 120 or `sudo systemctl restart tor` on most systemd-based systems, including recent 121 Debian and Ubuntu, or just restart the computer). 122 123 ### Authentication 124 125 Connecting to Tor's control socket API requires one of two authentication 126 methods to be configured: cookie authentication or bitcoind's `-torpassword` 127 configuration option. 128 129 #### Cookie authentication 130 131 For cookie authentication, the user running bitcoind must have read access to 132 the `CookieAuthFile` specified in the Tor configuration. In some cases this is 133 preconfigured and the creation of an onion service is automatic. Don't forget to 134 use the `-debug=tor` bitcoind configuration option to enable Tor debug logging. 135 136 If a permissions problem is seen in the debug log, e.g. `tor: Authentication 137 cookie /run/tor/control.authcookie could not be opened (check permissions)`, it 138 can be resolved by adding both the user running Tor and the user running 139 bitcoind to the same Tor group and setting permissions appropriately. 140 141 On Debian-derived systems, the Tor group will likely be `debian-tor` and one way 142 to verify could be to list the groups and grep for a "tor" group name: 143 144 ``` 145 getent group | cut -d: -f1 | grep -i tor 146 ``` 147 148 You can also check the group of the cookie file. On most Linux systems, the Tor 149 auth cookie will usually be `/run/tor/control.authcookie`: 150 151 ``` 152 TORGROUP=$(stat -c '%G' /run/tor/control.authcookie) 153 ``` 154 155 Once you have determined the `${TORGROUP}` and selected the `${USER}` that will 156 run bitcoind, run this as root: 157 158 ``` 159 usermod -a -G ${TORGROUP} ${USER} 160 ``` 161 162 Then restart the computer (or log out) and log in as the `${USER}` that will run 163 bitcoind. 164 165 #### `torpassword` authentication 166 167 For the `-torpassword=password` option, the password is the clear text form that 168 was used when generating the hashed password for the `HashedControlPassword` 169 option in the Tor configuration file. 170 171 The hashed password can be obtained with the command `tor --hash-password 172 password` (refer to the [Tor Dev 173 Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more 174 details). 175 176 177 ## 3. Manually create a Bitcoin Core onion service 178 179 You can also manually configure your node to be reachable from the Tor network. 180 Add these lines to your `/etc/tor/torrc` (or equivalent config file): 181 182 HiddenServiceDir /var/lib/tor/bitcoin-service/ 183 HiddenServicePort 8333 127.0.0.1:8334 184 185 The directory can be different of course, but virtual port numbers should be equal to 186 your bitcoind's P2P listen port (8333 by default), and target addresses and ports 187 should be equal to binding address and port for inbound Tor connections (127.0.0.1:8334 by default). 188 189 -externalip=X You can tell bitcoin about its publicly reachable addresses using 190 this option, and this can be an onion address. Given the above 191 configuration, you can find your onion address in 192 /var/lib/tor/bitcoin-service/hostname. For connections 193 coming from unroutable addresses (such as 127.0.0.1, where the 194 Tor proxy typically runs), onion addresses are given 195 preference for your node to advertise itself with. 196 197 You can set multiple local addresses with -externalip. The 198 one that will be rumoured to a particular peer is the most 199 compatible one and also using heuristics, e.g. the address 200 with the most incoming connections, etc. 201 202 -listen You'll need to enable listening for incoming connections, as this 203 is off by default behind a proxy. 204 205 -discover When -externalip is specified, no attempt is made to discover local 206 IPv4 or IPv6 addresses. If you want to run a dual stack, reachable 207 from both Tor and IPv4 (or IPv6), you'll need to either pass your 208 other addresses using -externalip, or explicitly enable -discover. 209 Note that both addresses of a dual-stack system may be easily 210 linkable using traffic analysis. 211 212 In a typical situation, where you're only reachable via Tor, this should suffice: 213 214 bitcoind -proxy=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -listen 215 216 (obviously, replace the .onion address with your own). It should be noted that you still 217 listen on all devices and another node could establish a clearnet connection, when knowing 218 your address. To mitigate this, additionally bind the address of your Tor proxy: 219 220 bitcoind ... -bind=127.0.0.1:8334=onion 221 222 If you don't care too much about hiding your node, and want to be reachable on IPv4 223 as well, use `discover` instead: 224 225 bitcoind ... -discover 226 227 and open port 8333 on your firewall (or use port mapping, i.e., `-natpmp`). 228 229 If you only want to use Tor to reach .onion addresses, but not use it as a proxy 230 for normal IPv4/IPv6 communication, use: 231 232 bitcoind -onion=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -discover 233 234 ## 4. Privacy recommendations 235 236 - Do not add anything but Bitcoin Core ports to the onion service created in section 3. 237 If you run a web service too, create a new onion service for that. 238 Otherwise it is trivial to link them, which may reduce privacy. Onion 239 services created automatically (as in section 2) always have only one port 240 open. 241 - Operating a node that listens on multiple networks (e.g. IPv4 and Tor) can help 242 strengthen the Bitcoin network, as nodes in this configuration (i.e. bridge nodes) increase 243 the cost and complexity of launching eclipse and partition attacks. However, under certain 244 conditions, an adversary that can connect to your node on multiple networks may be 245 able to correlate those identities by observing shared runtime characteristics. It 246 is not recommended to expose your node over multiple networks if you require 247 unlinkability across those identities.