From 9736c73e57816b6f0f778dc44218a08bd5f4b93e Mon Sep 17 00:00:00 2001 From: nyxnor Date: Sat, 2 Sep 2023 20:00:38 +0000 Subject: [PATCH] Whonix doc --- docs/platforms/whonix.md | 191 ++++++++++++++++++++++++--------------- 1 file changed, 117 insertions(+), 74 deletions(-) diff --git a/docs/platforms/whonix.md b/docs/platforms/whonix.md index c9bfc554..89f17dfe 100644 --- a/docs/platforms/whonix.md +++ b/docs/platforms/whonix.md @@ -10,18 +10,116 @@ This functionality may be incomplete and/or dangerous if misused. Please help us ::: -Whonix uses [Onion Grater](https://www.whonix.org/wiki/Onion-grater) to guard access to the control port. We have packaged -an oniongrater configuration `cwtch-whonix.yml` with Cwtch on Linux. +## Configure the Whonix-Gateway -When launching, Cwtch on Whonix should be passed the `CWTCH_TAILS=true` environment variables to automatically configure Cwtch for running in a Whonix-like environment: +The following steps should be done in the Whonix-Gateway. -`exec env CWTCH_TAILS=true LD_LIBRARY_PATH=~/.local/lib/cwtch/:~/.local/lib/cwtch/Tor ~/.local/lib/cwtch/cwtch` +### Onion Grater -Optionally, it may be desirable to pass either or both of two additional flags: +Whonix uses [Onion Grater](https://www.whonix.org/wiki/Onion-grater) to guard access to the control port. We have packaged an onion-grater configuration `cwtch-whonix.yml` with Cwtch on Linux. -- `CWTCH_RESTRICT_PORTS` - forces connectivity to bind to a subset of ports `15000-15378` -- `CWTCH_BIND_EXTERNAL_WHONIX` - forces connectivity to bind to external interfaces (only supported/recommended on certain Whonix-based setups. Please open an issue if you think this should be expanded.) +The onion-grater configuration `cwtch-whonix.yml` is reproduced below. As noted this configuration is can likely be restricted much further. +```yaml +# TODO: This can likely be restricted even further, especially in regards to the ADD_ONION pattern + +--- +- exe-paths: + - '' + users: + - '*' + hosts: + - '*' + commands: + AUTHCHALLENGE: + - 'SAFECOOKIE .*' + SETEVENTS: + - 'CIRC WARN ERR' + - 'CIRC ORCONN INFO NOTICE WARN ERR HS_DESC HS_DESC_CONTENT' + GETINFO: + - 'net/listeners/socks' + - '.*' + GETCONF: + - 'DisableNetwork' + SETCONF: + - 'DisableNetwork.*' + ADD_ONION: + ## {{{ Host: [::], Ports: 15000-15378 + - pattern: 'ED25519-V3:(\S+) Flags=DiscardPK,Detach Port=9878,\[::\]:(15[0-2][0-9][0-9])' + replacement: 'ED25519-V3:{} Flags=DiscardPK,Detach Port=9878,{client-address}:{}' + - pattern: 'ED25519-V3:(\S+) Flags=DiscardPK,Detach Port=9878,\[::\]:(153[0-6][0-9])' + replacement: 'ED25519-V3:{} Flags=DiscardPK,Detach Port=9878,{client-address}:{}' + - pattern: 'ED25519-V3:(\S+) Flags=DiscardPK,Detach Port=9878,\[::\]:(1537[0-8])' + replacement: 'ED25519-V3:{} Flags=DiscardPK,Detach Port=9878,{client-address}:{}' + ## }}} + DEL_ONION: + - '.+' + HSFETCH: + - '.+' + events: + CIRC: + suppress: true + ORCONN: + suppress: true + INFO: + suppress: true + NOTICE: + suppress: true + WARN: + suppress: true + ERR: + suppress: true + HS_DESC: + response: + - pattern: '650 HS_DESC CREATED (\S+) (\S+) (\S+) \S+ (.+)' + replacement: '650 HS_DESC CREATED {} {} {} redacted {}' + - pattern: '650 HS_DESC UPLOAD (\S+) (\S+) .*' + replacement: '650 HS_DESC UPLOAD {} {} redacted redacted' + - pattern: '650 HS_DESC UPLOADED (\S+) (\S+) .+' + replacement: '650 HS_DESC UPLOADED {} {} redacted' + - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH' + replacement: '650 HS_DESC REQUESTED {} NO_AUTH' + - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH \S+ \S+' + replacement: '650 HS_DESC REQUESTED {} NO_AUTH redacted redacted' + - pattern: '650 HS_DESC RECEIVED (\S+) NO_AUTH \S+ \S+' + replacement: '650 HS_DESC RECEIVED {} NO_AUTH redacted redacted' + - pattern: '.*' + replacement: '' + HS_DESC_CONTENT: + suppress: true +``` + +This file needs to be placed in `/usr/share/doc/onion-grater-merger/examples/40_cwtch.yml`. + +To enable the Cwtch onion-grater profile, use: +```shell +sudo onion-grater-add 40_cwtch +``` + +## Configure the Whonix-Workstation + +The following steps should be done in the Whonix-Workstation. + +### Linux Firewall + +The Whonix-Workstation Firewall needs to have the possible Cwtch binding port open. Follow the [upstream firewall guide](https://www.whonix.org/wiki/Whonix-Workstation_Firewall#Open_an_Incoming_Port). + +Use the following configuration in the file `/usr/local/etc/whonix_firewall.d/50_user.conf`: +```shell +EXTERNAL_OPEN_PORTS+=" $(seq 15000 15378) " +``` + +### Running Cwtch + +When launching, Cwtch on Whonix, some environment variables must be set: +- `CWTCH_TAILS=true` - automatically configure Cwtch for running in a Whonix-like environment. +- `CWTCH_RESTRICT_PORTS=true` - forces connectivity to bind to a subset of ports `15000-15378`, easier to manage on the firewall configuration. +- `CWTCH_BIND_EXTERNAL_WHONIX=true` - forces connectivity to bind to external interfaces (only supported/recommended on for Whonix-based setups where the machine (Workstation) which is running Cwtch is firewalled, where the only source of network is through the Gateway. + +```shell +cd ~/.local/lib/cwtch +env LD_LIBRARY_PATH=~/.local/lib/cwtch/:~/.local/lib/cwtch/Tor CWTCH_TAILS=true CWTCH_RESTRICT_PORTS=true CWTCH_BIND_EXTERNAL_WHONIX=true ~/.local/lib/cwtch/cwtch +``` :::info Install Location @@ -29,76 +127,21 @@ The above command, and the below onion grater configuration assume that Cwtch wa ::: -## Onion Grater Configuration +# Removing Cwtch -The oniongrater configuration `cwtch-whonix.yml` is reproduced below. As noted this configuration is can likely be restricted much -further. +## Remove configuration from the Whonix-Gateway -This file needs to be placed in `/usr/share/doc/onion-grater-merger/examples/` on the **Whonix Gateway** portion of he system. +The following steps should be done in the Whonix-Gateway. -You can then use `sudo onion-grater-add cwtch-whonix` to enable the onion grater configuration. - -``` -# TODO: This can likely be restricted even further, especially in regards to the ADD_ONION pattern -- exe-paths: - - '' -users: - - '*' -hosts: - - '*' -commands: - AUTHCHALLENGE: - - 'SAFECOOKIE .*' - SETEVENTS: - - 'CIRC WARN ERR' - - 'CIRC ORCONN INFO NOTICE WARN ERR HS_DESC HS_DESC_CONTENT' - GETINFO: - - 'net/listeners/socks' - - '.*' - GETCONF: - - 'DisableNetwork' - SETCONF: - - 'DisableNetwork.*' - ADD_ONION: - - '.*' - DEL_ONION: - - '.+' - HSFETCH: - - '.+' -events: - CIRC: - suppress: true - ORCONN: - suppress: true - INFO: - suppress: true - NOTICE: - suppress: true - WARN: - suppress: true - ERR: - suppress: true - HS_DESC: - response: - - pattern: '650 HS_DESC CREATED (\S+) (\S+) (\S+) \S+ (.+)' - replacement: '650 HS_DESC CREATED {} {} {} redacted {}' - - pattern: '650 HS_DESC UPLOAD (\S+) (\S+) .*' - replacement: '650 HS_DESC UPLOAD {} {} redacted redacted' - - pattern: '650 HS_DESC UPLOADED (\S+) (\S+) .+' - replacement: '650 HS_DESC UPLOADED {} {} redacted' - - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH' - replacement: '650 HS_DESC REQUESTED {} NO_AUTH' - - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH \S+ \S+' - replacement: '650 HS_DESC REQUESTED {} NO_AUTH redacted redacted' - - pattern: '650 HS_DESC RECEIVED (\S+) NO_AUTH \S+ \S+' - replacement: '650 HS_DESC RECEIVED {} NO_AUTH redacted redacted' - - pattern: '.*' - replacement: '' - HS_DESC_CONTENT: - suppress: true +Disable the Cwtch onion-grater profile: +```shell +sudo onion-grater-remove cwtch-whonix ``` -## Removing Cwtch +## Remove configuration from the Whonix-Workstation -You can use `sudo onion-grater-remove cwtch-whonix` to disable the Cwtch Onion Grater configuration, and then delete the Cwtch -application and the `$HOME/.cwtch` data directory. +The following steps should be done in the Whonix-Workstation. + +Delete the Cwtch application directory `$HOME/.local/lib/cwtch` and Cwtch data directory `$HOME/.cwtch`. + +The firewall ports should also be closed manually by removing the configuration added above and reloading the firewall.