API for working with Tor circuits on Whonix

Support
1

Hi Whonix team,

an app X works with a bundled Tor and it connects to its Tor control port to send HTTP requests under different identities (Tor circuits). Can the app be modified to work under Whonix? Currently it does not work because of Tor-over-Tor problem (I think!)

There are several ideas one can come up with how to modify the application:

  1. Simply don’t use the bundled Tor in the app and send clearnet HTTP requests which are “torrified” by Whonix. This does not work because it ignores the requirent for “having access to multiple Tor circuits”.

  2. Just ignore that Whonix runs everything over Tor. Then we are in Tor-over-Tor situation and AFAIK recently a Tor version was released with a patch that attempts to prevent that. It’s not recommended anyway.

  3. Make the the bundled Tor in the app circumevent Whonix’s Tor. I don’t think it’s possible. (Mentioning it just for the record)

  4. Use some Whonix API to get access to Tor’s circuits. Is there anything like that?

I’m asking this question to get some feedback about preferred approach for this (if there is any).

Thank you for any reply!

2

Documentation exists for a few applications re-configured for use with system Tor.

useful upstream feature request:

  • support using application-name with system Tor
  • support using application-name with Tor running on a different computer / IP
  • support using application-name with Whonix

Definition of system Tor:

For a few applications that ship their own Tor binary and/or use system Tor, documentation has been created to use these applications with Whonix:
Login required - Whonix

(login required so copied here at time of writing)

One solution is to configure the application (or request such a feature upstream or send a pull request) to use system Tor, in other words localhost, IP 127.0.0.1 port 9050 and set a socks user name. The Tor (not Whonix) feature IsolateSOCKSAuth would help here.

Quote Tor manual - Tor Project: manual

IsolateSOCKSAuth

Don’t share circuits with streams for which different SOCKS authentication was provided. (For HTTPTunnelPort connections, this option looks at the Proxy-Authorization and X-Tor-Stream-Isolation headers. On by default; you can disable it with NoIsolateSOCKSAuth.)

Some applications such as Tor Browser intelligently set a unique socks user name when appropriate such as per browser tab. Depends on the specifics of the application. Also unrelated to Whonix. This is general application Tor friendliness.

There’s no Whonix API. And hopefully it’s not needed.

For example, work on making wahay work inside Whonix has been done by @JeremyRand. Perhaps useful:
Issues · digitalautonomy/wahay · GitHub

wahay’s case (or any similar one) is a bit more complicated since that application uses ephemeral Tor onion services. For applications that only use Tor as a client, i.e. not use Tor onion services (server), it’s easier.

If any API is still needed, then Tor has an extensive one. The Tor control protocol.
https://gitweb.torproject.org/torspec.git/tree/control-spec.txt

related:

https://www.whonix.org/wiki/Dev/Whonix_friendly_applications_best_practices

3

Thank you very much for taking the time to write the answer! Appreciated!