haveno/docs/external-tor-usage.md

Using External tor with Haveno

How to Install little-t-tor for Your Platform?

The following tor installation instructions have are presented here for convenience.

• For the most complete, up-to-date & authoritative steps, readers are encouraged to refer the Tor Project's Official Homepage linked in the header

• Notes:

  For optimum compatibility with Haveno the running tor version should match that of the internal Haveno tor version

  For best results, use a version of tor which supports the Onion Service Proof of Work (PoW) mechanism

  • (IE: GNU build of tor)

---

• Note Regarding Admin Access:

  To install tor you need root privileges. Below all commands that need to be run as root user like apt and dpkg are prepended with #, while commands to be run as user with $ resembling the standard prompt in a terminal.

macOS

Install a Package Manager

Two of the most popular package managers for macOS are:

Homebrew

and

Macports

(You can use the package manager of your choice)

• Install Homebrew

  Follow the instructions on brew.sh

• Install Macports

  Follow the instructions on macports.org

Package Installation

Homebrew

# brew update && brew install tor

Macports

# port sync && port install tor

Debian / Ubuntu

• Do not use the packages in Ubuntu's universe. In the past they have not reliably been updated. That means you could be missing stability and security fixes.

• Configure the Official Tor Package Repository

  Enable the Official Tor Package Repository following these instructions

Package Installation

# apt update && apt install tor

Fedora

• Configure the Official Tor Package Repository

  Enable the Official Tor Package Repository by following these instructions

Package Installation

# dnf update && dnf install tor

Arch Linux

Package Installation

# pacman -Fy && pacman -Syu tor

Installing tor from source

Download Latest Release & Dependencies

The latest release of tor can be found on the download page

• When building from source:

  First install libevent,openssl & zlib

  (Including the -devel packages when applicable)

Install tor

$ tar -xzf tor-<version>.tar.gz; cd tor-<version>

• Replace <version> with the latest version of tor

  For example, tor-0.4.8.14

$ ./configure && make

• Now you can run tor (0.4.3.x and Later) locally like this:

$ ./src/app/tor

Or, you can run make install (as root if necessary) to install it globally into /usr/local/

• Now you can run tor directly without absolute path like this:

$ tor

Windows

Download

• Download the Windows Expert Bundle from the Official Tor Project's Download page

Extract

• Extract Archive to Disk

Open Terminal

• Open PowerShell with Admin Privileges

Change to Location of Extracted Archive

• Navigate to Tor Directory

Package Installation

• v10

PS C:\Tor\> tor.exe –-service install

• v11

PS C:\Tor\> tor.exe –-service install

Create Service

PS C:\Tor\> sc create tor start=auto binPath="<PATH TO>\Tor\tor.exe -nt-service"

Start Service

PS C:\Tor\> sc start tor

Configuring torvia torrc

I'm supposed to "edit my torrc". What does that mean?

• Per the Official Tor Project's support page:

  • WARNING: Do NOT follow random advice instructing you to edit your torrc! Doing so can allow an attacker to compromise your security and anonymity through malicious configuration of your torrc.

    Note:

    The torrc location will not match those stated in the documentation linked above and will vary across each platform.

Sample torrc

Users are strongly encouraged to review both the Official Tor Project's support page as well as the sample torrc before proceeding.

Enable torControlPort in torrc

In order for Haveno to use the --torControlPort option, it must be enabled and accessible. The most common way to do so is to edit the torrc fiel with a text editor to ensure that an entry for ControlPort followed by port number to listen on is present in the torrc file.

Authentication

Per the Tor Control Protocol - Implementation Notes:

• "If the control port is open and no authentication operation is enabled, tor trusts any local user that connects to the control port. This is generally a poor idea."

CookieAuthentication

If the CookieAuthentication option is true, tor writes a "magic cookie" file named control_auth_cookie into its data directory (or to another file specified in the CookieAuthFile option).

Example:

ControlPort 9051
CookieAuthentication 1

HashedControlPassword

If the HashedControlPassword option is set, it must contain the salted hash of a secret password. The salted hash is computed according to the S2K algorithm in RFC 2440 of OpenPGP, and prefixed with the s2k specifier. This is then encoded in hexadecimal, prefixed by the indicator sequence "16:".

• HashedControlPassword can be generated like so:

  $ tor --hash-password <password>
  

Example:

ControlPort 9051
HashedControlPassword 16:C01147DC5F4DA2346056668DD23522558D0E0C8B5CC88FE72EEBC51967

Restart tor

tor must be restarted for changes to torrc to be applied.

* Optional *

Set Up Your Onion Service

While not a strict requirement for use with Haveno, some users may wish to configure an Onion Service

• Only Required When Using The Haveno --hiddenServiceAddress Option

Please see the Official Tor Project's Documentation for more information about configuration and usage of these services

---

Haveno's tor Aware Options

Haveno is a natively tor aware application and offers many flexible configuration options for use by privacy conscious users.

While some are mutually exclusive, many are cross-applicable.

Users are encouraged to experiment with options before use to determine which options best fit their personal threat profile.

Options

--hiddenServiceAddress

• Function:

  This option configures a static Hidden Service Address to listen on

• Expected Input Format:

  <String>

  (ed25519)

• Acceptable Values

  <v3 Onion Address Value>

• Default value:

  null

--socks5ProxyXmrAddress

• Function:

  A proxy address to be used for monero network

• Expected Input Format:

  <String>

• Acceptable Values

  <Host:Port Value>

• Default value:

  null

--torrcFile

• Function:

  An existing torrc-file to be sourced for tor

  Note:

  torrc-entries which are critical to Haveno's flawless operation (torrc options line, torrc option, ...) can not be overwritten

• Expected Input Format:

  <String>

• Acceptable Values

  <Local File Location Value>

• Default value:

  null

--torrcOptions

• Function:

  A list of torrc-entries to amend to Haveno's torrc

  Note:

  torrc-entries which are critical to Haveno's flawless operation (torrc options line, torrc option, ...) can not be overwritten

• Expected Input Format:

  <String>

• Acceptable Values

  <^([^\s,]+\s[^,]+,?\s*)+$>

• Default value:

  null

--torControlHost

• Function

  The control hostname or IP of an already running tor service to be used by Haveno

• Expected Input Format

  <String>

  (hostname, IPv4 or IPv6)

• Acceptable Values

  <TorControl Host Value>

• Default Value

  null

--torControlPort

• Function

  The control port of an already running tor service to be used by Haveno

• Expected Input Format

  <Numeric String>

• Acceptable Values

  <TorControlPort Value>

• Default Value

  -1

--torControlPassword

• Function

  The password for controlling the already running tor service

• Expected Input Format

  <Alpha-Numeric-Special String>

• Acceptable Values

  <Passphrase Value>

• Default Value

  null

--torControlCookieFile

• Function

  The cookie file for authenticating against the already running tor service

  • Used in conjunction with --torControlUseSafeCookieAuth option

• Expected Input Format

  <Alpha-Numeric-Special String>

• Acceptable Values

  <Local File Location>

• Default Value

  null

--torControlUseSafeCookieAuth

• Function

  Use the SafeCookie method when authenticating to the already running tor service

• Expected Input Format

  null

• Acceptable Values

  none

• Default Value

  off

--torStreamIsolation

• Function

  Use stream isolation for Tor

  • This option is currently considered experimental

• Expected Input Format

  <Alpha String>

• Acceptable Values

  <on|off>

• Default Value

  off

--useTorForXmr

• Function

  Configure tor for monero connections with either:

  • after_sync

    or

  • off

    or

  • on

• Expected Input Format

  <Alpha String>

• Acceptable Values

  <AFTER_SYNC|OFF|ON>

• Default Value

  AFTER_SYNC

--socks5DiscoverMode

• Function

  Specify discovery mode for monero nodes

• Expected Input Format

  <mode[,...]>

• Acceptable Values

  ADDR, DNS, ONION, ALL

  One or more comma separated.

  (Will be OR'd together)

• Default Value

  ALL

---

Starting Haveno Using Externally Available tor

Dynamic Onion Assignment via --torControlPort

$ /opt/haveno/bin/Haveno --torControlPort='9051' --torControlCookieFile='/var/run/tor/control.authcookie' --torControlUseSafeCookieAuth --useTorForXmr='on' --socks5ProxyXmrAddress='127.0.0.1:9050'

Static Onion Assignment via --hiddenServiceAddress

$ /opt/haveno/bin/Haveno --socks5ProxyXmrAddress='127.0.0.1:9050' --useTorForXmr='on' --hiddenServiceAddress='2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion'