From 6b567b94f2c5c146df4314a5da08c542df9257ec Mon Sep 17 00:00:00 2001 From: PromptPunksFauxCough <200402670+PromptPunksFauxCough@users.noreply.github.com> Date: Fri, 7 Mar 2025 12:30:58 +0000 Subject: [PATCH] Document external tor usage (#1627) --- docs/external-tor-usage.md | 460 +++++++++++++++++++++++++++++++++++++ 1 file changed, 460 insertions(+) create mode 100644 docs/external-tor-usage.md diff --git a/docs/external-tor-usage.md b/docs/external-tor-usage.md new file mode 100644 index 0000000000..0a2a7300c6 --- /dev/null +++ b/docs/external-tor-usage.md @@ -0,0 +1,460 @@ +# **Using External `tor` with `Haveno`** +## *[How to Install little-t-`tor` for Your Platform?](https://support.torproject.org/little-t-tor/#little-t-tor_install-little-t-tor)* + +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](https://www.torproject.org) 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](https://onionservices.torproject.org/technology/security/pow) (`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`](https://brew.sh) + + and + + [`Macports`](https://www.macports.org) + + (You can use the package manager of your choice) + + + Install [`Homebrew`](https://brew.sh) + + Follow the instructions on [brew.sh](https://brew.sh) + + + Install [`Macports`](https://www.macports.org) + + Follow the instructions on [macports.org](https://www.macports.org) + +#### Package Installation +##### [`Homebrew`](https://brew.sh) + ```shell + # brew update && brew install tor + ``` + +##### [`Macports`](https://www.macports.org) + ```shell + # 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](https://deb.torproject.org/torproject.org) + + Enable the [Official `Tor` Package Repository](https://deb.torproject.org/torproject.org) following these [instructions](https://support.torproject.org/apt/tor-deb-repo/) + +#### Package Installation +```shell +# apt update && apt install tor +``` + +### Fedora + * Configure the [Official `Tor` Package Repository](https://rpm.torproject.org/fedora) + + Enable the [Official `Tor` Package Repository](https://rpm.torproject.org/fedora) by following these [instructions](https://support.torproject.org/rpm/tor-rpm-install) + +#### Package Installation +``` +# dnf update && dnf install tor +``` + +### Arch Linux +#### Package Installation +```shell +# pacman -Fy && pacman -Syu tor +``` + +### Installing `tor` from source +#### Download Latest Release & Dependencies +The latest release of `tor` can be found on the [download](https://www.torproject.org/download/tor) page + +* When building from source: + + *First* install `libevent`,`openssl` & `zlib` + + *(Including the -devel packages when applicable)* + +#### Install `tor` +```shell +$ tar -xzf tor-.tar.gz; cd tor- +``` + +* Replace \ with the latest version of `tor` + + > For example, `tor-0.4.8.14` + +```shell +$ ./configure && make +``` + +* Now you can run `tor` (0.4.3.x and Later) locally like this: + +```shell +$ ./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: + +```shell +$ tor +``` + +### Windows +#### Download +* Download the `Windows Expert Bundle` from the [Official `Tor` Project's Download page](https://www.torproject.org/download/tor) + +#### 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 +```powershell +PS C:\Tor\> tor.exe –-service install +``` + +* v11 +```powershell +PS C:\Tor\> tor.exe –-service install +``` + +#### Create Service +```powershell +PS C:\Tor\> sc create tor start=auto binPath="\Tor\tor.exe -nt-service" +``` + +#### Start Service +```powershell +PS C:\Tor\> sc start tor +``` + +### ***Configuring `tor`via `torrc`*** +#### [I'm supposed to "edit my torrc". What does that mean?](https://support.torproject.org/tbb/tbb-editing-torrc/) +* Per the [Official Tor Project's support page](https://support.torproject.org/tbb/tbb-editing-torrc/): + * **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`](https://gitlab.torproject.org/tpo/core/tor/-/blob/HEAD/src/config/torrc.sample.in) +Users are ***strongly*** encouraged to review both the [Official Tor Project's support page](https://support.torproject.org/tbb/tbb-editing-torrc/) as well as the [sample `torrc`](https://gitlab.torproject.org/tpo/core/tor/-/blob/HEAD/src/config/torrc.sample.in) 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](https://spec.torproject.org/control-spec/implementation-notes.html#authentication) +Per the [Tor Control Protocol - Implementation Notes](https://spec.torproject.org/control-spec/implementation-notes.html): + + * ***"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: +```shell +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: + ```shell + $ tor --hash-password + ``` + +###### Example: +```shell +ControlPort 9051 +HashedControlPassword 16:C01147DC5F4DA2346056668DD23522558D0E0C8B5CC88FE72EEBC51967 +``` + +##### Restart `tor` +`tor` must be restarted for changes to `torrc` to be applied. + +### \* ***Optional*** \* +#### [Set Up Your Onion Service](https://community.torproject.org/onion-services/setup) + +While not a *strict* requirement for use with `Haveno`, some users may wish to configure an [Onion Service](https://community.torproject.org/onion-services) + + * ***Only Required When Using The `Haveno` `--hiddenServiceAddress` Option*** + +Please see the [Official `Tor` Project's Documentation](https://community.torproject.org/onion-services/setup) 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: + + `` + + (`ed25519`) + +* Acceptable Values + + `` + +* Default value: + + `null` + +#### `--socks5ProxyXmrAddress` +* Function: + + A proxy address to be used for `monero` network + +* Expected Input Format: + + `` + +* Acceptable Values + + `` + +* 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: + + `` + +* Acceptable Values + + `` + +* 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: + + `` + +* 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 + + `` + + (`hostname`, `IPv4` or `IPv6`) + +* Acceptable Values + + `` + +* Default Value + + `null` + +#### `--torControlPort` ++ Function + + The control port of an already running `tor` service to be used by `Haveno` + +* Expected Input Format + + `` + +* Acceptable Values + + `` + +* Default Value + + `-1` + +#### `--torControlPassword` ++ Function + + The password for controlling the already running `tor` service + +* Expected Input Format + + `` + +* Acceptable Values + + `` + +* 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 + + `` + +* Acceptable Values + + `` + +* 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 + + `` + +* Acceptable Values + + `` + +* Default Value + + `off` + +#### `--useTorForXmr` ++ Function + + Configure `tor` for `monero` connections with ***either***: + + * after_sync + + **or** + + * off + + **or** + + * on + +* Expected Input Format + + `` + +* Acceptable Values + + `` + +* Default Value + + `AFTER_SYNC` + +#### `--socks5DiscoverMode` ++ Function + + Specify discovery mode for `monero` nodes + +* Expected Input Format + + `` + +* 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` +```shell +$ /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` +```shell +$ /opt/haveno/bin/Haveno --socks5ProxyXmrAddress='127.0.0.1:9050' --useTorForXmr='on' --hiddenServiceAddress='2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion' +```