Tor integration in Whonix Development Notes
Tor Version, Package source (Debian, backports, Tor Project package repository), Config Files, Miscellaneous
Tor Version
[edit]This section documents Tor version selection considerations for Whonix. It compares C Tor and Arti, explains why the latest stable Tor package from deb.torproject.org might not always match the stable Debian release used by Whonix, and summarizes the advantages and disadvantages of using Debian packages, the Tor Project repository, Debian backports, or versions migrated to deb.kicksecure.com.
There are two implementations of Tor.
- C Tor - Originally called "Tor". This is the original implementation of Tor written in the C programming language.
- Arti - New implementation of Tor based on Rust.
Both are developed by their upstream developer, The Tor Project (TPO).
According to the Tor release notes, there are usually several major versions of Tor supported by The Tor Project. However, because the Tor packager has limited time, only a few major versions are packaged and ready for use.
For example, in December 2017, five major versions of Tor were supported. Specifically:
- The Debian
stretchrepository contained an LTS version, which was version0.2.9. deb.torproject.org, also known as the Tor, Tor Project or TPO repository, provided the latest stable Tor, which was version0.3.1.9.
A major consideration in choosing the most suitable Tor version for Whonix is that the latest stable version found in the TPO repository may lead to network breakage. [1] The reason is that the "stable" tag indicates a stable version of Tor, which does not necessarily match the "stable" Debian version that Whonix uses. [2]
There are three primary Tor options for Whonix developers and each of them has pros and cons:
1. Use the Tor LTS version from the official Debian package repository: packages.debian.org
- Advantages: Minimal effort is required in Whonix.
- Disadvantages: Might miss the advantages of later versions (see below).
- While this was true in the past, development of C Tor has slowed down because its replacement, Arti, is now the development focus of the Tor developers. [3]
- Related: Whonix forum discussion Keep an eye on Arti (Tor)
- Related: Whonix forum discussion Keep an eye on Arti (Tor)
- While this was true in the past, development of C Tor has slowed down because its replacement, Arti, is now the development focus of the Tor developers. [3]
2. Use the latest stable version in the TPO repository and allow testers to use the Tor nightly build in Whonix, with bug reporting to TPO
- Advantages: The latest features, better security, improved Tor Browser compatibility (using
SocksPortwith flags), and even better connectivity performance. [4] - Disadvantages:
- From the Whonix perspective, these packages are uploaded to
deb.torproject.orgat random times. These packages are not guaranteed to be compatible with Whonix. While there are no security concerns, these packages could break a system's APT package management due to incompatible dependencies, or connectivity if Tor refuses to start. This can arise due to a configuration incompatibility in a newer version of Tor, or for other reasons such as systemd or AppArmor related changes. - In May 2021, a transient repository issue
broke
- In December 2022, it caused the issue FAILED to start Anonymizing overlay network for TCP - Tor fails to start a few times before succeeding to start
- In February 2023, it might have caused the issue Fresh whonix-kvm install gateway error
- In December 2023, Tor 0.4.8.9 broke connectivity in combination with vanguards
- There is no equivalent to
snapshot.debian.org. It keeps changing as newer versions are added. Therefore, it can introduce build issues such as the ones above. It is unsuitable for reproducible builds / Verifiable Builds. - Porting to other architectures issues.
- Only available for the
i386,amd64, andarm64architectures. - Introduces differences / issues, for example on the
ppc64elplatform. [5]
- Only available for the
- From the Whonix perspective, these packages are uploaded to
3. Versions are downloaded from deb.torproject.org, verified to work, and then migrated to deb.kicksecure.com
(Why deb.kicksecure.com? Because Kicksecure also uses the Tor package, and Whonix is Based on Kicksecure.)
- Advantages: Flexibility in version selection, and a guaranteed way to confirm that only stable Tor versions which are functional in Whonix will be uploaded.
- Disadvantages:
- A few testers are needed, manual uploads are required, and Whonix touches Tor packaging.
- Other issues from 2. above equally apply.
4. Versions are downloaded from Debian backports, verified to work, and then migrated to deb.kicksecure.com
Advantages:
- Good support for other architectures. No porting to other architectures issues.
Open Questions:
Scenario A)...
1. Newer Tor version downloaded from Debian backports.
2. Verified to work, and then migrated to deb.kicksecure.com.
3. Debian backports starts to provide an even newer Tor version.
4. TODO: Would it automatically get installed?
Scenario B)...
1. Newer Tor version downloaded from Debian backports.
2. Verified to work, and then migrated to deb.kicksecure.com.
3. Debian backports becomes outdated but the Tor Project repository provides a newer version.
4. Newer Tor version downloaded from TPO repository.
5. Migrated to deb.kicksecure.com.
6. TODO: Would the newer Tor version get installed or would the installed Tor version from Debian backports prevent this?
Current Choice
Whonix developers have chosen the third method for Whonix 16. [6] However, the comparison above suggests that the second option provides better security and compatibility. This approach, however, would require a lot of active testers who can use the Tor nightly build and report bugs to The Tor Project or Whonix, but these are currently unavailable.
Whonix developers have chosen the first method for Whonix 17 because development of C Tor has slowed down in favor of Arti as mentioned above.
Back to the third method: https://forums.whonix.org/t/tor-integration-in-whonix/10593/45
Tor Config Files
[edit]Rationale for Tor Drop-In Configuration Folder
[edit]Having a Tor Configuration Drop-In Folder makes implementation of additional features that require additional Tor settings much easier. For example, it could improve usability to provide a whonix-gw-hidden-webserver package that automates the Whonix-Gateway™ specific instructions for Onion Services. Such a package could just drop the configuration snippet into that folder, and if the feature is disabled or the package is uninstalled, that configuration snippet gets purged. Adding additions to /etc/tor/torrc with a script is problematic, because those additions cannot be removed by a script if the user slightly modified those lines and because they can cause a dpkg interactive conflict resolution dialog.
Current Implementation
[edit]The implementation is as follows.
/etc/tor/torrcholds minimal content, so ideally it will need as few updates as possible, or none in the future. The only effective command is%include /etc/torrc.d/which results in parsing the folder/etc/torrc.d- The lexically highest file
/etc/torrc.d/95_whonix.conf%include /usr/local/etc/torrc.d/. - Instructions in
/etc/tor/torrcand documentation tell users not to edit that file and to use/usr/local/etc/torrc.d/50_user.confinstead. /etc/tor/torrc.examplescontains configuration examples.- Some Whonix Tor settings unfortunately still go into
/usr/share/tor/tor-service-defaults-torrc - Most users probably ignore
/usr/share/tor/tor-service-defaults-torrc, because this file is barely advertised and seldom used. /usr/share/tor/tor-service-defaults-torrccan be modified by Qubes-Whonixreplace-ipsdpkg interactive conflict resolution dialog.- Debian feature request: add torrc.d configuration directory
- Initial Tor feature request: torrc.d-style configuration directories
- Tor improvement feature request: Parse only .torrc files in torrc.d directory
- https://github.com/Whonix/anon-gw-anonymizer-config
Rejected Alternatives
[edit]Only Two Config Files
[edit]- Using only /usr/share/tor/tor-service-defaults-torrc and /etc/tor/torrc, not using /etc/tor/torrc.examples.
- Storing configuration examples (instructions) in /usr/share/tor/tor-service-defaults-torrc. Using a minimal /etc/tor/torrc to tell users to look into /usr/share/tor/tor-service-defaults-torrc for configuration examples.
- This is a bad idea, because users are tempted to uncomment things in /usr/share/tor/tor-service-defaults-torrc.
- If they do this, their settings would get lost and overwritten without asking next time they update anon-gw-anonymizer-config
Only One Config File
[edit]- Using only /etc/tor/torrc, leaving /usr/share/tor/tor-service-defaults-torrc with defaults from Debian, not using /etc/tor/torrc.examples.
- Using /etc/tor/torrc for user examples, users' own modifications, and Whonix Tor settings.
- This is bad, because when users have edited /etc/tor/torrc and anon-gw-anonymizer-config gets updated, it will throw a
dpkg interactive conflict resolution dialog. Users might decide to keep their old config file and then miss (security) improvements.
Tor Control
[edit]See Talking to the real Tor Control Port.
Tor Readiness to Serve Connections API
[edit]What API answers the question, "When is Tor ready to serve connections?"
The short answer is: none.
Unfortunately, there is no reliable API for that. There is the Tor control protocol status/circuit-established, which can return 1 (yes), but that does not mean a connection will succeed. The only way to test it would be to perform a connection test, such as using curl against some clearnet or onion domain(s). But which ones, without creating single points of failure?
Why Waste Network Bandwidth by Downloading Operating System Updates over Tor?
[edit]The short answer is that this option was discussed with The Tor Project and Whonix was granted permission to do so.
Interested readers who want to learn more should review the following:
- Tor Project thread about this issue; see updates over Tor, should not waste Tor bandwidth
- The Tor Project was asked directly after this issue and possible solutions were discussed thoroughly by the Whonix team; see tor-talk Operating system updates / software installation behind Tor Transparent Proxy
- Andrew Lewman, a former Executive Director, Director, and press contact for Tor, downloads a lot of updates over the network and did not complain
Forum Discussion
[edit]- https://forums.whonix.org/t/tor-integration-in-whonix/10593
- https://forums.whonix.org/t/tor-upgrades/10302
Footnotes
[edit]- ↑
- ↑ The Debian target is usually the stable package, which is currently: trixie for Whonix.
- ↑
- ↑
Patrick: "Historically when there was a botnet starting to use Tor, the LTS version barely connected while the latest stable had the ntor handshake which worked." See tor-weekly-news-september-4th-2013
- ↑
Package: tor-geoipdbVersion: 0.4.5.8-1~d10.buster+1isArchitecture: allandDepends: tor (>= 0.4.5.8-1~d10.buster+1). Thereby for example ended up in Whonix repository for architectureppc64el. This has not caused an issue yet. - ↑
Related Whonix Forum discussion: https://forums.whonix.org/t/tor-releases-discussion/4578
- ↑ Click here
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 14 year success story and maybe DONATE!