onion-grater, a Tor Control Port Filter Proxy

From Whonix
< Dev
(Redirected from Dev/CPFP)
Jump to navigation Jump to search

onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands - Design Documentation

Introduction[edit]

Onion-grater is a filtering proxy for the Tor Controller listening on Whonix-Gateway™ internal network interface, which is the interface that the Whonix-Workstation™ connects when sending controller commands. It acts based on whitelists, denying everything by default and only allowing explicitly specified commands (and their arguments) and events.

According to upstream Tails OS documentationarchive.org, onion-grater is defined as: This filter proxy allows fine-grained access whitelists of commands (and their arguments) and events on a per-application basis.

Contrary to Tails, the fields user and per-application (AppArmor profile) are ignored with the wildcard '*' to include everything, that due to Whonix design of user space and tor daemon separation, these methods are not possible. Instead of that, what provides greater security to further separate applications and their requests to Tor's Control Protocol is using Multiple_Whonix-Workstation, and you can control per Whonix-Workstation hosts directive for the onion-grater profile to match the Whonix-Workstation LAN IP. As using Multiple Whonix-Workstation requires more work as the Whonix-Gateway does not know all the Whonix-Workstation LAN IPs, the hosts defaults to hosts: '*' and if you want to minimize the attack surface of Whonix-Workstation to the Whonix-Gateway Tor Controller, you could set the hosts directive to match your chosen Whonix-Workstation LAN IP.

Tor's control port has in context of Whonix, dangerous features. The answer to the Tor control command GETINFO address will be the real external IP of the Tor client. Other dangerous commands include SETCONF, LOADCONF, GETCONF, GETINFO ns/id/<relay-fingerprint>.

The dangerous commands can only be limited with a proxy, since the feature request Option to limit information Tor's control port disclosesarchive.org against Tor has not been implemented. By the way, this Tor control port feature makes also a Bridge Firewallarchive.org impossible.

Tor Browser by default performs its own control port verificationarchive.org. It checks using Tor's control port(!), that the socks port Tor reports, is the same one as Tor Browser is configured to use. If it fails, and it would fail in Whonix 0.5.6, Tor Button would look like disabled and show a failure message. (To see how this would look like, see this screenshotarchive.org.) (To see how this generates user confusion, see this forum threadarchive.org.) Since Whonix 6 this check is disabled using environment variable to skip TorButton control port verificationarchive.org (export TOR_SKIP_CONTROLPORTTEST=1) by package anon-ws-disable-stacked-torarchive.org. [1]

With Whonix-Workstation having no way of finding its own external IP address, joining Tor Browser's fingerprint for Whonix users, having no access for Whonix-Workstation to Tor's control port with Tor Buttons new requirement to have access to Tor's control port contradicted itself.

onion-grater has been implemented as a solution. It gives Whonix-Workstation access to a limited selection of Tor's control port commands, using whitelisting (not blacklisting). For example, it allows SIGNAL NEWNYM to make Tor Buttons New Identity feature available for users who use Tor Browser in Whonix-Workstation.

onion-grater limits maximum accepted command string length to 128 (configurable) (credits: [2] [3]) for better security.

Advanced users who do not wish to use onion-grater can disable it, see deactivate onion-grater.

Directory of choice[edit]

  • Using /usr/local/etc/onion-grater-merger.d/ because that onion-grater settings folder is persistent in Qubes-Whonix™ TemplateBased ProxyVMs i.e. Whonix-Gateway (commonly called sys-whonix).
  • Non-Qubes-Whonix users could also utilize /etc/onion-grater-merger.d/.
  • Qubes-Whonix users could also utilize /etc/onion-grater-merger.d/ but then /etc/onion-grater-merger.d/ must be made persistent, which means doing this procedure inside the Whonix-Gateway Template (commonly called whonix-gateway-17) and then restarting the Whonix-Gateway ProxyVM or using bind-dirsarchive.org.

Both techniques are more complicated than simply using /usr/local/etc/onion-grater-merger.d/, since it is persistent either way. Further, it even allows multiple Whonix-Gateway ProxyVMs based on the same Whonix-Gateway Template; for example, one Whonix-Gateway ProxyVM extending and relaxing onion-grater's whitelist and the other Whonix-Gateway ProxyVM having the default onion-grater whitelist which is more restrictive.

Onion-grater will only evaluate *.yml files.

Whonix connection[edit]

Whonix-Gateway[edit]

onion-grater listens on Whonix internal network interface [4], port 9051, filters (whitelist) incoming control port messages and forwards them to the real Tor Control Port listening on ControlSocket /run/tor/control. onion-grater itself uses cookies authentication to authenticate Tor's control port. The latter is not important, since Whonix-Gateway only purpose is running Tor, its not a multi user operating system, and if it were compromised, cookie authentication wouldn't be of help anymore either.

Whonix-Workstation[edit]

Whonix sets appropriate environment variables for the controller via unix domain socket TOR_CONTROL_IPC_PATH=/run/anon-ws-disable-stacked-tor/127.0.0.1_9151.sock, which is the socket Tor Browser uses.

This functionality is implemented by the anon-ws-disable-stacked-torarchive.org package. See also Dev/anon-ws-disable-stacked-tor.

Attack Scenarios[edit]

Once Whonix-Workstation has been compromised, the adversary could continuously and/or using a pattern, send whitelisted commands to Tor. At the moment, only NEWNYM would be of interest. When the adversary is also an ISP level adversary, the adversary might be able to see the pattern being produced.

However thinking that an attacker requires access to Tor's Controller to try to deanonymize you is wrong, there are numerous attacks that are possible without needing to extract information and manipulate tor configuration. The attacker can simply download code from any website including his own and begin to run his code. He could also make very unique patterns on the network and through traffic analysis to learn more about the paths the tor client is using.

More worrying is the extended attack surface that allowing commands to be sent from a compromised Whonix-Workstation to a Whonix-Gateway, such as an unsafe parsing of commands, daemon C code memory leaks etc.

Information from this kinda of attacks were asked upstream but had no manifestation of interestarchive.org (web archivearchive.org).

Imitating real Tor Control Connection[edit]

Should Tor close the connection, onion-grater will also close client connection. (Same for a real Tor control connection.)

Both real Tor control connection and onion-grater close the connection if commands are sent when the client is not yet authenticated. (With the exception of authenticate, authchallenge and protocolinfo so there is parity.)

Should Tor authentication fail, this is logged and onion-grater closes client connection.

Talking to the real Tor Controller[edit]

If instead of connecting to onion-grater, you want to talk directly with the Tor Controller, it should be done on the Whonix-Gateway and using the host 127.0.0.1, see Talking to the real Tor Controller for more information.

How to do onion-grater profiles[edit]

As an exercise, try building a profile for an application already supported by Whonix, if you have trouble, you can always learn from the examples available at /usr/share/doc/onion-grater-merger/examples in your Whonix-Gateway.

For third-party projects with Tor friendly applications[edit]

Please document the controller commands, give hints to the scripts that send Tor commands, this can greatly increase the chance of your application being included to Whonix and used by real users.

Make your application handle unexpected replies such as 510 Command filtered without crashing, onion-grater is a whitelist filter, not a blacklist, this means that there is a great change the necessary commands your application requires may be filtered if not whitelisted. If your program crashes, that would lead to bad usability.

Profile format[edit]

There is no need to explain every directive in details as it is better to read the code commentsarchive.org for more up to date information. The following sections only mentions about differences in directive usage on Whonix in comparison with Tails OS.

A filter is matched if for each of the relevant qualifiers at least one of the elements match the client, the qualifiers being apparmor-profiles, users and hosts. It is very common for multiple qualifiers to match on Whonix, as apparmor-profiles and users can't be set and setting hosts requires user intervention.

How onion-grater parses files[edit]

Parsing stops at the first match, this means that it is not possible to override files by user a name with higher precedence such as 50_user.yml over 30_whonix-default.yml, what onion-grater does is sort the files in reverse lexical order, so if 50_user.yml matches, it will stop there, else continue to 30_whonix-default.yml.

name[edit]

We are not using the name directive because it is optional and the script names are already making the names unique.

apparmor-profiles[edit]

For local (loopback) clients.

We can't use the apparmor-profiles directive because as per Whonix design, the user programs are run on the Whonix-Workstation and the controller is on the Whonix-Gateway.

Because of this, we default to: 

  apparmor-profiles:
    - '*'

users[edit]

For local (loopback) clients.

We can't use the users directive because as per Whonix design, the user programs are run on the Whonix-Workstation and the controller is on the Whonix-Gateway.

Because of this, we default to: 

  users:
    - '*'

hosts[edit]

For remote (non-local) clients.

We can use the hosts directive, but the Whonix-Gateway doesn't know which of your Multiple Whonix-Workstation requires the whitelist.

Because of this, we default to: 

  hosts:
    - '*'

You can optionally change that directive to allow only the IP of your chosen Whonix-Workstation, therefore you can choose per host the rules you want to be whitelisted.

Application Support[edit]

Some applications that uses the commands and events whitelisted by default don't need to worry about setting profiles. Some applications might already have profiles for other applications that already cover their usage.

Tor Browser[edit]

OnionShare[edit]

Bitcoin Core[edit]

Bisq[edit]

Wahay[edit]

ZeroNet[edit]

Systemcheck[edit]

  • Page: systemcheckarchive.org
  • Profile: asks onion-grater status/bootstrap-phase [5] as well as status/circuit-established [6] in Tor Bootstrap Status Check [7] (usability feature).

TorLauncher[edit]

To get a list of Tor ControlPort commands, that TorLauncher uses, get into TorLauncher source code, extract TorLauncher, then run.

grep -r -i getconf

TorButton[edit]

TorButton commands[edit]

To get a list of Tor ControlPort commands, that TorButton uses, get into TorButton source code, extract TorButton, then run.

grep -r -i torbutton_send_ctrl_cmd *

grep -r -i sendCommand *

TorButton Network Settings[edit]

TorButton &rarr; Open Network Settings...

Is using.

"GETCONF Socks4Proxy" "GETCONF Socks5Proxy" "GETCONF HTTPSProxy" "GETCONF ReachableAddresses" "GETCONF ReachableAddresses" "GETCONF UseBridges" "GETCONF Bridge"

As the next logical step by the way, they are likely going to add.

"GETCONF HTTPProxy"

We are settingarchive.org environment variable export TOR_NO_DISPLAY_NETWORK_SETTINGS=1archive.org to disable the "TorButton" → "Open Network Settings..." menu item. It is not useful and confusing to have on a workstation, because Tor must be configured on the gateway, which is for security reasons forbidden from the workstation.

TorButton issues[edit]

Looking for contributor!

Clock skew[edit]

In the future, Tor Button will likely also use something like GETINFO clockskewarchive.org. Tor Browser developer rejectedarchive.org the idea of not adding the statement require no access to Tor's control port to Tor Browser's design.

Therefore when onion-grater gets asked GETINFO net/listeners/socks, it lies, and answers 250-net/listeners/socks="127.0.0.1:9150". This makes Tor Button happy and therefore it shows a "Congratulations!" (success) welcome page on its default homepage about:tor and not the failure page, which would confuse users. Since bug TorButton about:tor fails when using additional socks listenersarchive.org has been fixed by Tor Tor Project, that lie wouldn't be necessary anymore. We're keeping it, because it is not necessary for Tor Button get a full list of all ports Tor is listening on. If an attacker compromised Whonix-Workstation, hiding that list has an advantage. The attacker can probe what ports are available to that Whonix-Workstation, but if the user added extra ports not available to the compromised Whonix-Workstation (only available to another Whonix-Workstation listening on another IP), at least those remain secret. (This is a bit theoretical, because a compromised Whonix-Workstation can spoof its LAN IP and most likely very few users are using ARP spoofing defenses. Should we add ARP spoofing defenses by default at some point, we at least don't have to worry about this point.)

For further eventual Tor control port access requirements by Tor Button, the configuration file of accepted commands has to be extended. If Tor Button would ever ask for anything which violates Whonix design (Whonix-Workstation has no way of finding out its own external IP address in particular), such as GETINFO address, for example if Tor Button wanted to ensure, that the user is not using its own external IP address, a new lie would have to be added to the onion-grater script. In case many more lies are required, lies should go into the config file as well, for now, hard coding is sufficient.

Circuit View[edit]

TODO: Make Tor Circuit View screenshot with redacted IPs, fingerprints, locations work with Tor Browser in Whonix through filtered Tor control port access (onion-grater). Purpose: do not confuse Tor Browser to fix onion authentication through Tor Browser.

Regular Expression RegEx

Required for onion-grater.

rewrite source 

    650 STREAM 547 SUCCEEDED 210 99.84.158.73:80 SOCKS_USERNAME="--unknown--" SOCKS_PASSWORD="f0358c6d18973a9dc667f5dcd75c131e" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=20 SESSION_GROUP=-59 ISO_FIELDS=SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH

to 

    650 STREAM 547 SUCCEEDED 210 127.0.0.1:443 SOCKS_USERNAME="--unknown--" SOCKS_PASSWORD="redacted" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=00 SESSION_GROUP=-00 ISO_FIELDS=SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH

rewrite source 

    650 STREAM 487 SENTCONNECT 174 abcdefghz2352sf.onion:80 CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=19 SESSION_GROUP=-41 ISO_FIELDS=DESTPORT,DESTADDR,SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH

to 

    650 STREAM 487 SENTCONNECT 000 redacted.onion:80 CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=19 SESSION_GROUP=-00 ISO_FIELDS=DESTPORT,DESTADDR,SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH

rewrite source 

    81 BUILT $89FD4FB2A5FD73B50F2E5D85C4707883F8CD5130~VisitFrance,$9EB3FD84065E5622A57EFEF14E41A01B5B99A022~whatconfig,$E7EF73B4722CFAF0E8AA2151D3AA78701DE5F19B~Silverwing,$9B1BE5D20FB9069523EF4889027325CE89B42460~scha1k BUILD_FLAGS=IS_INTERNAL,NEED_CAPACITY,NEED_UPTIME PURPOSE=HS_CLIENT_REND HS_STATE=HSCR_JOINED REND_QUERY=crypty22ijtotell TIME_CREATED=2020-06-05T18:00:41.170815

to 

    81 BUILT $redacted~redacted,$redacted~redacted,$redacted~redacted,$redacted~redacted BUILD_FLAGS=NEED_CAPACITY PURPOSE=HS_CLIENT_REND HS_STATE=HSCR_JOINED REND_QUERY=redacted TIME_CREATED=2020-00-00T00:00:00.000000

rewrite source 

250+ns/id/24A17A4C1FA8C2108ACDE3BE681B0731384BF3A5=
r dragonhoard JKF6TB+owhCKzeO+aBsHMThL86U hrPrav+cqzyxUd0uNuXEA1U56xk 2020-06-05 09:21:43 159.69.21.196 8080 8008
a [2a01:4f8:1c1c:2e49::1]:8080
s Fast Guard Running Stable V2Dir Valid
w Bandwidth=13000
.
250 OK

to 

250+ns/id/24A17A4C1FA8C2108ACDE3BE681B0731384BF3A5=
r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008
a [0000:0000:0000:0000::1]:8080
s Fast Guard Running Stable V2Dir Valid
w Bandwidth=00
.
250 OK

Syntax example 

    HS_DESC:
      response:
        - pattern:     '650 HS_DESC CREATED (\S+) (\S+) (\S+) \S+ (.+)'
          replacement: '650 HS_DESC CREATED {} {} {} redacted {}'
  • Curent state:

For the Tor Circuit View to appear, it requires valid credentials replied from the SENTCONNECT eventarchive.org and if they are not the same credentials the Tor Browser sent by that tab, the circuits will not be shownarchive.org. Tor Browser wants to get the same SOCKS_USERNAME and SOCKS_PASSWORD it send for that tab in the first place, if it doesn,t the whole tab is not shown, you can check the reply with the Browser Console (Ctrl+Shift+J): Torbutton NOTE: no SOCKS credentials found for current document.

The interest is not showing the circuits per se, but at least showing literally Hop1, Hop2 and Hop2 to not confuse users why the tab is not shown. Another side effect is that it also hides the button New circuit for this site, but still available in the supermenu, but less convenient and not expected by the user to be this way.

If someone with JavaScript knowledge could patch upstream, at least showing the New circuit for this site even if the credentials don't match would be a start, but it currently is not shown because either the Tor Button shows completely or doesn't show at all. A more difficult task would be to instead of not showing the circuit view, if the browser fails to get the correct credentials, it could show a helpful text that it can't show the circuits because it could not determine the stream. There is a lower chance of rewriting the countries and IPs of the circuits to fake data if it can't establish the link because upstream could consider this a workaround. Anyway, a better user experience is expected from the Tor Circuit View, even if an error message, so at least it is understood by non-developers or for people not familiarized with the Tor Button and Tor Browser source code.

Trials with onion-grater: 

---
- hosts:
    - '*'
  commands:
    SETEVENTS:
      - 'STREAM'
    SIGNAL:
      - 'NEWNYM'
    GETCONF:
      - pattern: 'bridge'
        response:
        - pattern: '250 Bridge.*'
          replacement: '250 Bridge'
    GETINFO:
      - 'status/circuit-established'
      - 'version'
      - 'consensus/valid-after'
      - 'consensus/valid-until'
      - 'consensus/fresh-until'
      - pattern: 'net/listeners/socks'
        response:
        - pattern:     '250-net/listeners/socks=".*"'
          replacement: '250-net/listeners/socks="127.0.0.1:9150"'
      - pattern: 'circuit-status'
        response:
        - pattern: '.*,.*'
          replacement: '10 BUILT $1~a,$2~b,$3~c BUILD_FLAGS=NEED_CAPACITY PURPOSE=redacted REND_QUERY=redacted TIME_CREATED=2020-00-00T00:00:00.000000'
      - pattern: 'ns/id/1'
        response:
        - pattern:     '551 .*'
          replacement: "250+ns/id/1=

r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008

a 127.0.0.1:8080

s Fast Guard Running Stable V2Dir Valid

w Bandwidth=00

."
      - pattern: 'ns/id/2'
        response:
        - pattern:     '551 .*'
          replacement: "250+ns/id/2=

r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008

a 127.0.0.2:8080

s Fast Guard Running Stable V2Dir Valid

w Bandwidth=00

."
      - pattern: 'ns/id/3'
        response:
        - pattern:     '551 .*'
          replacement: "250+ns/id/3=

r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008

a 127.0.0.3:8080

s Fast Guard Running Stable V2Dir Valid

w Bandwidth=00

."
      - pattern: 'ip-to-country/127.0.0.1'
        response:
        - pattern: '250-ip-to-country/.*'
          replacement: '250-ip-to-country/127.0.0.1=us'
      - pattern: 'ip-to-country/127.0.0.2'
        response:
        - pattern: '250-ip-to-country/.*'
          replacement: '250-ip-to-country/127.0.0.2=us'
      - pattern: 'ip-to-country/127.0.0.3'
        response:
        - pattern: '250-ip-to-country/.*'
          replacement: '250-ip-to-country/127.0.0.3=us'
  confs:
    __owningcontrollerprocess:
  events:
    STREAM:
      response:
        - pattern: '650 STREAM (\S+) SENTCONNECT .*'
          replacement: '650 STREAM 10 SENTCONNECT 10 127.0.0.1:443 SOCKS_USERNAME="unknown.org" SOCKS_PASSWORD="unknownhash" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=0 SESSION_GROUP=-13 ISO_FIELDS=DESTPORT,DESTADDR,SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH'
        - pattern: '650 STREAM .*'
          replacement: '650 STREAM 10 REDACTED 10 127.0.0.1:443 SOCKS_USERNAME="unknown.org" SOCKS_PASSWORD="unknownhash" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=0 SESSION_GROUP=-13 ISO_FIELDS=DESTPORT,DESTADDR,SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH'
    SIGNAL:
      suppress: true
    CONF_CHANGED:
      suppress: true
    STATUS_SERVER:
      suppress: true
    restrict-stream-events: true

Onion-grater logs: 

(filter: /usr/local/etc/onion-grater-merger.d/50_user): rewrote received event:
    650 STREAM 97825 SENTCONNECT 82470 content-signature-2.cdn.mozilla.net:443 SOCKS_USERNAME="--unknown--" SOCKS_PASSWORD="fa8348e1f2c300cad85b6052285edbe4" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=1 SESSION_GROUP=-47 ISO_FIELDS=SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH
to:
    650 STREAM 10 SENTCONNECT 10 127.0.0.1:443 SOCKS_USERNAME="unknown.org" SOCKS_PASSWORD="unknownhash" CLIENT_PROTOCOL=SOCKS5 NYM_EPOCH=0 SESSION_GROUP=-13 ISO_FIELDS=DESTPORT,DESTADDR,SOCKS_USERNAME,SOCKS_PASSWORD,CLIENTADDR,SESSION_GROUP,NYM_EPOCH
(filter: /usr/local/etc/onion-grater-merger.d/50_user): -> getconf bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): <- 250 Bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): -> getconf bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): <- 250 Bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): -> getconf bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): <- 250 Bridge
(filter: /usr/local/etc/onion-grater-merger.d/50_user): -> getinfo ns/id/1
(filter: /usr/local/etc/onion-grater-merger.d/50_user): rewrote response:
    551 Data not decodeable as hex
to:
    250+ns/id/1=
    r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008
    a 127.0.0.1:8080
    s Fast Guard Running Stable V2Dir Valid
    w Bandwidth=00
    .
10.138.31.44:57912 (filter: /usr/local/etc/onion-grater-merger.d/50_user): <- (multi-line)
    250+ns/id/1=
    r redacted redacted redacted 2020-00-00 00:00:00 00.00.00.00 8080 8008
    a 127.0.0.1:8080
    s Fast Guard Running Stable V2Dir Valid
    w Bandwidth=00
    .

After the first query of the relay info, it doesn't query the other nodes for unknown reasons. Note that the command getinfo ip-to-country was never issued, unknown reason. After that, only redacted streams were replied.

Folder with other examples already using this type of regex:

https://github.com/Whonix/onion-grater/blob/master/usr/share/doc/onion-grater-merger/examplesarchive.org

Direct links to profiles using similar regex:

Functionality support[edit]

Indicator for current Circuit Status and Exit IP[edit]

---
- apparmor-profiles:
    - '*'
  users:
    - '*'
  hosts:
    - '*'
  commands:
    SIGNAL:
      - 'NEWNYM'
    GETINFO:
      - pattern: 'circuit-status'
        response:
        - pattern: '250(.+)circuit-status=(\S+) (\S+) (.+) (\S+) (\S+)'
        - replacement: '250+circuit-status='
    GETCONF:
      - pattern: 'bridge'
        response:
        - pattern:     '250-Bridge=(.+) (\S+) (\S+) (\S+) (\S+)'
          replacement: '250-Bridge='
        - pattern:     '250 Bridge=(.+) (\S+) (\S+) (\S+) (\S+)'
          replacement: '250 Bridge='
  events:
    STREAM:
  restrict-stream-events: true

onion_client_auth_add[edit]

Example command for Tor control protocol: onion_client_auth_add m5bmcnsk64naezc26scz2xb3l3n2nd5xobsljljrpvf77tclmykn7wid x25519:uBKh6DGrkcFxB1adYuyKQltUDDUT9IZrOsne3nfHbHI=

Test key that can be entered into browser. XAJKD2BRVOI4C4IHK2OWF3EKIJNVIDBVCP2IM2Z2ZHPN456HNRZA

UI for ExitNode country selection in tor-launcher[edit]

https://gitlab.torproject.org/legacy/trac/-/issues/11406archive.org

Feedback mechanism for clock-skew and other bad problems[edit]

https://gitlab.torproject.org/legacy/trac/-/issues/9675archive.org

Debugging Inspiration[edit]

onion-grater debug mode[edit]

On Whonix-Gateway.

Open file /lib/systemd/system/onion-grater.service.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix™

This box uses sudoedit for better security.

sudoedit /lib/systemd/system/onion-grater.service.d/50_user.conf

Qubes-Whonix™

NOTES:

  • When using Qubes-Whonix, this needs to be done inside the Template.

sudoedit /lib/systemd/system/onion-grater.service.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix™.

Others and Alternatives

  • This is just an example. Other tools could achieve the same goal.
  • If this example does not work for you or if you are not using Whonix, please refer to this link.

sudoedit /lib/systemd/system/onion-grater.service.d/50_user.conf

Add.

[Service] ## Clear onion-grater default file '/lib/systemd/system/onion-grater.service'. ExecStart= ## Same as above but enable debug mode. ExecStart=/usr/lib/onion-grater --listen-interface eth1 --listen-port 9051 --debug ## Same as above but enable complain mode which permits everything (insecure in production). #ExecStart=/usr/lib/onion-grater --listen-interface eth1 --listen-port 9051 --complain

Save.

Reload systemd daemon:

sudo systemctl daemon-reload

Restart onion-grater service:

sudo systemctl restart onion-grater

Done, debug mode is now enabled.

Watch onion-grater's logs while using it in a separate terminal tab: sudo journalctl -f -u onion-grater

onion-grater passthrough mode[edit]

This disables filtering (allows all commands) and should be used during development only. Because this mode allows everything, we will not be running as a service, but as a command on the terminal, this means that if the program receives and interrupt signal of the machine reboots, it will enable the standard onion-grater service.

On Whonix-Gateway.

sudo systemctl stop onion-grater

sudo /usr/lib/onion-grater-merger

sudo -u onion-grater /usr/lib/onion-grater --listen-interface eth1 --listen-port 9051 --complain

On Whonix-Workstation.

tor-ctrl GETINFO status/bootstrap-phase

Press Enter.

AppArmor issues[edit]

Watch kern.log for eventual iptables log messages, run this on Whonix-Gateway.

sudo apparmor-info

Connect to onion-grater from Whonix-Gateway[edit]

To connect to onion-grater from a Non-Qubes-Whonix-Gateway: tor-ctrl -s 10.152.152.10:9051 GETINFO config-file

To connect to onion-grater from a Qubes-Whonix-Gateway: tor-ctrl -s $(qubesdb-read /qubes-ip):9051 GETINFO config-file

Connect to onion-grater from Whonix-Workstation[edit]

On the Whonix-Workstation you should be able to run without setting the interface:

tor-ctrl GETINFO address

Type GETINFO address. Enter. Should reply 510 Command filtered.

tcpdump - Less Important[edit]

Only in case of suspected fundamental issues with low level networking.

To see what's being send to onion-grater's port, run this on Whonix-Gateway.

Non-Qubes-Whonix-Gateway:

sudo tcpdump -i eth1 -l -s0 -w - tcp dst port 9051

Qubes-Whonix-Gateway: (Note: replace vif18.0 with the device found with the command ip route.)

sudo tcpdump -i vif18.0 -l -s0 -w - tcp dst port 9051

Comparison of Control Port Filters[edit]

onion-grater by Tails[edit]

onion-graterarchive.org by Tails (config folderarchive.org)

  • Written in python3.
  • All dependencies already inside Debian.
  • Wildcard / regex support.
  • Supports rewriting client requests.
  • Supports rewriting Tor replies.
  • Parallel connections support.
  • Can reply to getinfo net/listeners/socks with the lie '250-net/listeners/socks="127.0.0.1:9150"'.
  • Logs to journal.
  • Honors signals sigterm, sigint.
  • Supports subscribing Tor ControlPort events (setevent).

onion-grater by Tails forked by Whonix[edit]

onion-graterarchive.org (config folderarchive.org) (additional onion-grater-merger example profilesarchive.org) (issue trackerarchive.org)

  • mostly same as #onion-grater by Tails
  • different config parsing mechanism
  • Debian packaging
  • systemd unit file
  • systemd-notify support - https://mailman.boum.org/pipermail/tails-dev/2017-March/011327.html submitted patch upstream
  • systemd seccomp hardening [9]
  • AppArmor profile

roflcoptor by subgraph os[edit]

roflcoptorarchive.org by subgraph os

  • Many golang dependencies that are not packaged for Debian.
  • Event support.
  • Wildcard support.
  • TODO: expand

surrogate.go by Yawning Angel[edit]

surrogate.go (tor project gitweb)archive.org by Yawning Angel

  • golang (build dep, not run dep)
  • AGPL (Achtung!)
  • Part of new/upcoming Sandboxed Tor Browserarchive.org
  • "Tor control/socks port surrogates." (quoting top comment) Intended to proxy/filter both ControlPort and SOCKSPort of tor process in one bubblewrapped sandbox, while actual Tor Browser runs in another bubblewrapped sandbox.
  • Observed version: 6ff4802archive.org
  • So, official TPO Tor Browser variant also has this problem. Oops!

legacy control-port-filter-python by Whonix[edit]

legacy [https://github.com/{{project_name_short}}/control-port-filter-python control-port-filter-python] ([https://github.com/{{project_name_short}}/control-port-filter-python/blob/master/usr/sbin/cpfpd main script]) [{{project_name_short}} 10 to {{project_name_short}} 13 ([https://github.com/{{project_name_short}}/control-port-filter-python/releases/tag/1.7-1 version 1.7-1]] (last git commit [https://github.com/{{project_name_short}}/control-port-filter-python/commit/99e8395fbafcb7789c7d1b5cbf7410ed65192e9a up to 99e8395fbafcb7789c7d1b5cbf7410ed65192e9a]) ([https://phabricator.whonix.org/tag/control-port-filter-python/ issue tracker]) [deprecated]

  • A fork of (very early) [https://gitlab.tails.boum.org/tails/tails/-/blob/master/config/chroot_local-includes/usr/local/sbin/tor-controlport-filter tor-controlport-filter] by Tails. (See above.)
  • Written in python2.7.
  • Configurable by dropping .d-style[10] configuration snippets into /etc/cpfpy.d.
  • Support to answer getinfo net/listeners/socks with the lie '250-net/listeners/socks="127.0.0.1:9150"'.
  • Supports logging.
  • Honors signals sigterm, sigint, keyboard interrupt.
  • Supports parallel connections.
  • Supports wildcards, which is for tools such as onionshare that are using add_onion *.
  • Injects workstation IP into add_onion. For example will transform from / to:
    • add_onion new:best port=80,17600
    • add_onion new:best port=80,10.137.6.41:17600
  • Support subscribing Tor ControlPort events (setevent). (Whonix 14 and above.) [11]
  • Complete systemd unit file.
  • Lintian clean /debian packaging folder.
  • Will be deprecated when Whonix 14 get released.

legacy2 control-port-filter by Whonix[edit]

legacy^2 control-port-filter [up to Whonix 9.x] [deprecated]

  • Supports parallel connections.
  • Written in bash. (githubarchive.org) (archive only)
  • White lists multiple useful Tor ControlPort commandsarchive.org.
  • Configurable using /etc/controlportfilt.d drop-in files.
  • Support to answer getinfo net/listeners/socks with the lie '250-net/listeners/socks="127.0.0.1:9150"'.
  • Supports logging.
  • Honors signals sigterm, sigint.
  • Does not support wildcards.
  • Does not support subscribing Tor ControlPort events (setevent).
  • Complete sysvinit script.
  • Lintian clean /debian packaging folder.
  • Deprecated since the release of Whonix 10.

Old method to manage profiles[edit]

Previously manual instructions. No longer needed. onion-grater-add automates that.

Add profile[edit]

1. Create folder /usr/local/etc/onion-grater-merger.d.

sudo mkdir -p /usr/local/etc/onion-grater-merger.d

2. Symlink the onion-grater profile to the onion-grater settings folder.

sudo ln -s 40_onion_authentication.yml /usr/local/etc/onion-grater-merger.d/

3. Restart onion-grater. sudo service onion-grater restart

Remove profile[edit]

1. Remove symlink from the onion-grater profile

sudo unlink /usr/local/etc/onion-grater-merger.d/40_onion_authentication.yml

2. Restart onion-grater. sudo service onion-grater restart

Whonix Forum Discussion[edit]

Source Code[edit]

Original upstream by Tails:

Fork by Whonix:

Whonix supplementary:

See Also[edit]

Footnotes[edit]

  1. ↑ https://github.com/Whonix/anon-ws-disable-stacked-tor/blob/master/usr/libexec/anon-ws-disable-stacked-tor/torbrowser.sharchive.org
  2. ↑ As done by Tails.archive.org
  3. ↑ Thanks to HulaHoop for [https://www.whonix.org/old-forum/index.php/topic,342.0.html suggesting this].
  4. ↑ https://github.com/Whonix/whonix-gw-network-conf/blob/master/usr/lib/systemd/system/onion-grater.service.d/30_cpfpy.confarchive.org
  5. ↑ Find out what status/bootstrap-phase answers yourself in Whonix-Gateway. /usr/lib/helper-scripts/tor_bootstrap_check.py 127.0.0.1 9051 1 Example answer. NOTICE BOOTSTRAP PROGRESS=100 TAG=done SUMMARY="Done"
  6. ↑ Find out what status/circuit-established answers yourself in Whonix-Gateway. /usr/lib/helper-scripts/tor_circuit_established_check.py 127.0.0.1 9051 1 Example answer. 1
  7. ↑ https://github.com/Kicksecure/systemcheck/blob/master/usr/libexec/systemcheck/check_tor_bootstrap.bsharchive.org whonixcheck --function check_tor_bootstrap whonixcheck --function check_tor_bootstrap --verbose --debug
  8. ↑ https://git-tails.immerda.ch/onion-grater/commit/?id=33ae20850329930bd1a3686cca2a9ac4dc766aea +* EVENTS: Tor Browser is subscribed to all STREAM events for its + implementation of the circuit view. This means it will know + basically everything Tor is doing which is pretty bad in case Tor + Browser is compromised.
  9. ↑ https://phabricator.whonix.org/T631archive.org
  10. ↑ Kicksecure logo Style Configuration Folders Onion Version
  11. ↑ https://phabricator.whonix.org/T448archive.org
Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

Retrieved from "https://www.whonix.org/w/index.php?title=Dev/onion-grater&oldid=102229"