github.com/decred/dcrlnd@v0.7.6/docs/configuring_tor.md (about)

     1  # Table of Contents
     2  1. [Overview](#overview)
     3  2. [Getting Started](#getting-started)
     4  3. [Tor Stream Isolation](#tor-stream-isolation)
     5  4. [Authentication](#authentication)
     6  5. [Listening for Inbound Connections](#listening-for-inbound-connections)
     7  
     8  ## Overview
     9  
    10  `dcrlnd` currently has complete support for using Lightning over
    11  [Tor](https://www.torproject.org/). Usage of Lightning over Tor is valuable as
    12  routing nodes no longer need to potentially expose their location via their
    13  advertised IP address. Additionally, leaf nodes can also protect their location
    14  by using Tor for anonymous networking to establish connections.
    15  
    16  With widespread usage of Onion Services within the network, concerns about the
    17  difficulty of proper NAT traversal are alleviated, as usage of onion services
    18  allows nodes to accept inbound connections even if they're behind a NAT. At the
    19  time of writing this documentation, `dcrlnd` supports both types of onion services:
    20  v2 and v3.
    21  
    22  Before following the remainder of this documentation, you should ensure that you
    23  already have Tor installed locally. **If you want to run v3 Onion Services, make
    24  sure that you run at least version 0.3.3.6.**
    25  Official instructions to install the latest release of Tor can be found
    26  [here](https://www.torproject.org/docs/tor-doc-unix.html.en).
    27  
    28  **NOTE**: This documentation covers how to ensure that `dcrlnd`'s _Lightning
    29  protocol traffic_ is tunneled over Tor. Users must ensure that when also running
    30  a Decred full-node, that it is also proxying all traffic over Tor. 
    31  ## Getting Started
    32  
    33  First, you'll want to run `tor` locally before starting up `dcrlnd`. Depending on
    34  how you installed Tor, you'll find the configuration file at
    35  `/usr/local/etc/tor/torrc`. Here's an example configuration file that we'll be
    36  using for the remainder of the tutorial:
    37  ```
    38  SOCKSPort 9050
    39  Log notice stdout
    40  ControlPort 9051
    41  CookieAuthentication 1
    42  ```
    43  
    44  With the configuration file created, you'll then want to start the Tor daemon:
    45  ```
    46  ⛰  tor
    47  Feb 05 17:02:06.501 [notice] Tor 0.3.1.8 (git-ad5027f7dc790624) running on Darwin with Libevent 2.1.8-stable, OpenSSL 1.0.2l, Zlib 1.2.8, Liblzma N/A, and Libzstd N/A.
    48  Feb 05 17:02:06.502 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://www.torproject.org/download/download#warning
    49  Feb 05 17:02:06.502 [notice] Read configuration file "/usr/local/etc/tor/torrc".
    50  Feb 05 17:02:06.506 [notice] Opening Socks listener on 127.0.0.1:9050
    51  Feb 05 17:02:06.506 [notice] Opening Control listener on 127.0.0.1:9051
    52  ```
    53  
    54  Once the `tor` daemon has started and it has finished bootstrapping, you'll see this in the logs:
    55  ```
    56  Feb 05 17:02:06.000 [notice] Bootstrapped 0%: Starting
    57  Feb 05 17:02:07.000 [notice] Starting with guard context "default"
    58  Feb 05 17:02:07.000 [notice] Bootstrapped 80%: Connecting to the Tor network
    59  Feb 05 17:02:07.000 [notice] Bootstrapped 85%: Finishing handshake with first hop
    60  Feb 05 17:02:08.000 [notice] Bootstrapped 90%: Establishing a Tor circuit
    61  Feb 05 17:02:11.000 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
    62  Feb 05 17:02:11.000 [notice] Bootstrapped 100%: Done
    63  ```
    64  
    65  This indicates the daemon is fully bootstrapped and ready to proxy connections.
    66  At this point, we can now start `dcrlnd` with the relevant arguments:
    67  
    68  ```
    69  ⛰  ./dcrlnd -h
    70  
    71  <snip>
    72  
    73  Tor:
    74        --tor.active                                            Allow outbound and inbound connections to be routed through Tor
    75        --tor.socks=                                            The host:port that Tor's exposed SOCKS5 proxy is listening on (default: localhost:9050)
    76        --tor.dns=                                              The DNS server as host:port that Tor will use for SRV queries - NOTE must have TCP resolution enabled (default: soa.nodes.lightning.directory:53)
    77        --tor.streamisolation                                   Enable Tor stream isolation by randomizing user credentials for each connection.
    78        --tor.control=                                          The host:port that Tor is listening on for Tor control connections (default: localhost:9051)
    79        --tor.targetipaddress=                                  IP address that Tor should use as the target of the hidden service
    80        --tor.password=                                         The password used to arrive at the HashedControlPassword for the control port. If provided, the HASHEDPASSWORD authentication method will be used instead of the SAFECOOKIE one.
    81        --tor.v2                                                Automatically set up a v2 onion service to listen for inbound connections
    82        --tor.v3                                                Automatically set up a v3 onion service to listen for inbound connections
    83        --tor.privatekeypath=                                   The path to the private key of the onion service being created
    84  ```
    85  
    86  There are a couple things here, so let's dissect them. The `--tor.active` flag
    87  allows `dcrlnd` to route all outbound and inbound connections through Tor.
    88  
    89  Outbound connections are possible with the use of the `--tor.socks` and
    90  `--tor.dns` arguments. The `--tor.socks` argument should point to the interface
    91  that the `Tor` daemon is listening on to proxy connections. The `--tor.dns` flag
    92  is required in order to be able to properly automatically bootstrap a set of
    93  peer connections. The `tor` daemon doesn't currently support proxying `SRV`
    94  queries over Tor. So instead, we need to connect directly to the authoritative
    95  DNS server over TCP, in order query for `SRV` records that we can use to
    96  bootstrap our connections.
    97  
    98  Inbound connections are possible due to `dcrlnd` automatically creating an onion
    99  service. A path to save the onion service's private key can be specified with
   100  the `--tor.privatekeypath` flag.
   101  
   102  Most of these arguments have defaults, so as long as they apply to you, routing
   103  all outbound and inbound connections through Tor can simply be done with either
   104  v2 or v3 onion services:
   105  ```shell
   106  ⛰  ./dcrlnd --tor.active --tor.v2
   107  ```
   108  ```shell
   109  ⛰  ./dcrlnd --tor.active --tor.v3
   110  ```
   111  
   112  Outbound support only can also be used with:
   113  ```shell
   114  ⛰  ./dcrlnd --tor.active
   115  ```
   116  
   117  This will allow you to make all outgoing connections over Tor. Listening is
   118  disabled to prevent inadvertent leaks.
   119  
   120  ## Tor Stream Isolation
   121  
   122  Our support for Tor also has an additional privacy enhancing modified: stream
   123  isolation. Usage of this mode means that Tor will always use  _new circuit_ for
   124  each connection. This added features means that it's harder to correlate
   125  connections. As otherwise, several applications using Tor might share the same
   126  circuit.
   127  
   128  Activating stream isolation is very straightforward, we only require the
   129  specification of an additional argument:
   130  ```
   131  ⛰  ./dcrlnd --tor.active --tor.streamisolation
   132  ```
   133  
   134  ## Authentication
   135  
   136  In order for `lnd` to communicate with the Tor daemon securely, it must first
   137  establish an authenticated connection. `lnd` supports the following Tor control
   138  authentication methods (arguably, from most to least secure):
   139  
   140  * `SAFECOOKIE`: This authentication method relies on a cookie created and
   141    stored by the Tor daemon and is the default assuming the Tor daemon supports
   142    it by specifying `CookieAuthentication 1` in its configuration file.
   143  * `HASHEDPASSWORD`: This authentication method is stateless as it relies on a
   144    password hash scheme and may be useful if the Tor daemon is operating under a
   145    separate host from the `lnd` node. The password hash can be obtained through
   146    the Tor daemon with `tor --hash-password PASSWORD`, which should then be
   147    specified in Tor's configuration file with `HashedControlPassword
   148    PASSWORD_HASH`. Finally, to use it within `lnd`, the `--tor.password` flag
   149    should be provided with the corresponding password.
   150  * `NULL`: To bypass any authentication at all, this scheme can be used instead.
   151    It doesn't require any additional flags to `lnd` or configuration options to
   152    the Tor daemon.
   153  
   154  ## Listening for Inbound Connections
   155  
   156  In order to listen for inbound connections through Tor, an onion service must be
   157  created. There are two types of onion services: v2 and v3. v3 onion services
   158  are the latest generation of onion services and they provide a number of
   159  advantages over the legacy v2 onion services. To learn more about these
   160  benefits, see [Intro to Next Gen Onion Services](https://trac.torproject.org/projects/tor/wiki/doc/NextGenOnions).
   161  
   162  Both types can be created and used automatically by `dcrlnd`. Specifying which type
   163  should be used can easily be done by either using the `tor.v2` or `tor.v3` flag.
   164  To prevent unintentional leaking of identifying information, it is also necessary
   165  to add the flag `listen=localhost`.  
   166  
   167  For example, v3 onion services can be used with the following flags:
   168  ```
   169  ⛰  ./dcrlnd --tor.active --tor.v3 --listen=localhost
   170  ```
   171  
   172  This will automatically create a hidden service for your node to use to listen
   173  for inbound connections and advertise itself to the network. The onion service's
   174  private key is saved to a file named `v2_onion_private_key` or
   175  `v3_onion_private_key` depending on the type of onion service used in `dcrlnd`'s
   176  base directory. This will allow `dcrlnd` to recreate the same hidden service upon
   177  restart. If you wish to generate a new onion service, you can simply delete this
   178  file. The path to this private key file can also be modified with the
   179  `--tor.privatekeypath` argument.