[edit]

Authoring Notes:

Start with a general description below each headline. Be as general as possible and try to avoid using terms like 'Tor'.
Next, carefully describe the Whonix ™ Example Implementation. Show exactly how Whonix ™ implements the goals stated above.
See Dev/Documentation_Guidelines for the preferred formatting style and grammatical considerations.

List of installed Packages[edit]

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/Whonix-Workstation_packages ^[archive]

Files[edit]

Essential[edit]

Network Configuration[edit]

Configure the system resolver to use the Gateway to resolve DNS. (There can be no DNS leaks, because the Gateway firewall prevents that.) It shouldn't get used often, only for applications which are not configured to use Stream Isolation (SocksPort). Just as a general catch all for user installed applications to improve usability.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/build-steps.d/2500_create-vbox-vm ^[archive] in function workstation_specific, one virtual network card, type internal
https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/resolv.conf.whonix ^[archive]
https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/network/interfaces.whonix ^[archive]

DummyTor[edit]

Since the anonymizer software runs on the Gateway, users could still accidental install the anonymizer software on the Workstation. This would lead into connecting to the anonymity network over the anonymity network itself. In best case it just doesn't work or is very slow and in worst case it leads to unknown consequences. Prevent that.

Whonix ™-Example-Implementation:

Banning the Tor package from Whonix-Workstation ™ to prevent Tor over Tor. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/chroot-scripts/70_dummytor ^[archive]
Install an empty Tor package which does no more than simulating, that Tor is already installed and thus preventing the package manager from installing Tor, see also Dev/Dummy Tor.
DummyTor package description file: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/dummytor/tor ^[archive]
rinetd (see below) also prevents Tor from opening the default listener on port 9050. Therefore the Tor service will fail to start.

KDE / GNOME - application wide proxy settings[edit]

Whether KDE / GNOME will be used or not, in addition to stream isolation wrappers and other preconfigured applications for stream isolation, in addition it is useful to also configure KDE / GNOME - wide proxy settings. In case the user installs KDE or GNOME applications, which connect to the internet, which honor proxy settings, those won't go through Tor's TransPort, but through a dedicated SocksPort for further improved stream isolation. These settings are not system-wide, but KDE-wide / GNOME-wide.

Whonix ™-Example-Implementation:

KDE: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/kde/share/config/kioslaverc ^[archive]
GNOME: Not yet implemented. TODO

Extra[edit]

second, optional, extra firewall[edit]

Optional.

Optional second, optional, extra firewall for advanced users as damage protection in case the Whonix-Gateway ™ gets ever compromised (Tor exploit).

Whonix ™-Example-Implementation:

Please read the script comments.
Firewall script: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/bin/whonix_firewall ^[archive]
Configuration file: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/whonix_firewall.d/10_default ^[archive]

Usability[edit]

Swap[edit]

Let the kernel only swap if it is absolutely necessary.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/sysctl.d/whonix-workstation-sysctl.conf ^[archive]

Environment Variables[edit]

Optional.

It is useful to have an environment variable announcing "I am a Workstation", so applications such as TorButton and TorBirdy can act accordingly. (I.e. not starting Tor/Vidalia on the Workstation; not using 127.0.0.1 as proxy, but therefore the Gateway.)

Whonix ™-Example-Implementation:

apt.conf[edit]

Optional.

Whonix ™-Example-Implementation:

Doesn't do anything by default. Just some comments. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/apt/apt.conf.d/90whonix ^[archive]
(apt is forced though Tor by APT uwt wrapper (Design-Shared) and by the firewall running on the Gateway.

http to socks converter[edit]

Optional.

Some applications don't support socks, but http. It is useful to have a http to socks converter.

Whonix ™-Example-Implementation:

None required to be installed by default.
If someone likes to use polipo, the config file from torproject.org is shipped. (Only adapted to use the Whonix-Gateway ™. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/polipo/config ^[archive]

Sending e-mails without registration[edit]

Optional.

Install a tool, which can send e-mails without registration.

Whonix ™-Example-Implementation:

Using Mixmaster. (Of course over Tor.)
Implementation notes: Dev/Mixmaster
https://github.com/Whonix/Whonix/blob/master/whonix_workstation/home/user/.Mix/mix.cfg ^[archive]
Documented on Remailer and Mixmaster page.

GnuPG Configuration[edit]

Optional.

Using more secure defaults for GnuPG.

Whonix ™-Example-Implementation:

Using more secure defaults. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/home/user/.gnupg/gpg.conf ^[archive]

Project News Notification[edit]

Optional.

Whonix ™-Example-Implementation:

Using rawdog, a privacy friendly rss reader to download Whonix ™ News Blogs.
Privacy friendly as in, once it downloaded the blog's content, there will be no incoming/outgoing traffic. The page can be viewed offline and contains no tracking scripts.
Non-ideal configuration. In rawdog config is a https link with a sourceforge rss feed, which unfortunately redirects to a non-https page, which rawdog follows. Thus, news is not fetched over https and a man-in-the-middle could spread malicious news.
rawdog Configuration folder: https://github.com/Whonix/Whonix/tree/master/whonix_workstation/home/user/.rawdog/ ^[archive]
Documented on page rss and Download (Stay Tuned) page.
rawdog gets run by whonixcheck. (See Dev/Design-Shared.)
The user is asked to prefer to start Tor Browser using the Tor Browser Recommended shortcut on the Desktop: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/kde/share/applications/whonix-tbrecommend.desktop ^[archive]

TorChat Configuration[edit]

Optional.

Using TorChat on a already torified Workstation while preventing Tor over Tor is not trivial. Therefore it is useful to ship required configuration files, preconfigured as much as possible by default to ease installation of TorChat.

Whonix ™-Example-Implementation:

TorChat does not get installed by default.
Due to popular request, Whonix ™ makes it as easy as possible to use TorChat with Whonix ™.
https://github.com/Whonix/Whonix/blob/master/whonix_workstation/home/user/.torchat/torchat.ini ^[archive]
Documented on Chat page.
Banning the Tor package from Whonix-Workstation ™ to prevent Tor over Tor. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/chroot-scripts/70_dummytor ^[archive]

IRC Client[edit]

Optional.

Secure IRC Client configuration and script for getting a new IRC identity.

Whonix ™-Example-Implementation:

Whonix ™ comes with HexChat configured for privacy.
https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/bin/xchat-reset ^[archive]
Documented on HexChat page.
Configuration files. https://github.com/Whonix/Whonix/tree/master/whonix_workstation/usr/local/share/whonix/xchat2 ^[archive]
Deactivating plugins. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/chroot-scripts/70_xchat ^[archive]

Web Browser[edit]

Secure Web Browser, which doesn't suffer from likability and browser fingerprinting.

Whonix ™-Example-Implementation:

Whonix ™ comes with Tor Browser, which is maintained by The Tor Project.
Reasons for TorBrowser can be found on the Tor Browser page.
Documented on Tor Browser page.
torbrowser update script: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/bin/torbrowser ^[archive]
Patched torbrowser startup script to make Tor Browser work without the bundled Tor and Vidalia: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/start-tor-browser ^[archive] The torbrowser update script https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/bin/torbrowser ^[archive] keeps care to replace the upstream start-tor-browser file.
Install Tor Browser while building Whonix: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/chroot-scripts/70_torbrowser ^[archive]
Environment variables: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/profile.d/20_torbrowser.sh ^[archive]
Gpg keys to verify the downloaded Tor Browser:
- https://github.com/Whonix/Whonix/tree/master/whonix_workstation/usr/local/share/whonix/gpg-pubkeys ^[archive]
- Dev/Source_Code_Intro#OpenPGP_keys

rinetd[edit]

Optional.

Whonix ™-Example-Implementation:

rinetd is configured to listen on local ports 9050 and 9150.
- rinetd forwards port 127.0.0.1:9050 (Workstation) to 10.152.152.10:9050 (Gateway).
- Forwards port 127.0.0.1:9150 (Workstation) to 10.152.152.10:9150 (Gateway).
- https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/rinetd.conf ^[archive]
- This prevents Tor over Tor by just installing Tor or by using the complete Tor Browser Bundle, which starts Vidalia and Tor. This is because, it listens on port 9050 and 9150 and therefore lets a default Tor or TBB fail to start.
- Should the Tor Browser update script ever break,
  - Whonix ™ users can download (and verify) the stock Tor Browser Bundle (TBB) from torproject.org,
  - unpack to /home/user/tor-browser_en-US and
  - start it from the desktop menu shortcut or from the start menu.
  - As long as The Tor Project will still ship Vidalia with TBB: Starting with the stock startup script /home/user/tor-browser_en-US/start-tor-browser will fail closed. Vidalia will report, that Tor won't connect, because port 9150 is already blocked by rinetd. This will be fixed as soon as The Tor Project merges a proposed patch https://gitlab.torproject.org/legacy/trac/-/issues/5611 ^[archive] for the start-tor-browser startup script, which adds an optional environment variable, once set, only starts Tor Browser and not the bundled Tor/Vidalia.
  - As soon as The Tor Project moved to tor-launcher and drops Vidalia: Starting stock TBB inside Whonix ™ should work out of the box, because https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/profile.d/20_torbrowser.sh ^[archive] sets the required environment variables to deactivate tor-launcher.

Marker file[edit]

Optional.

Add a marker file so scripts you write can find out, whether they are running on the Gateway or inside the Workstation. There are probably different implementations possible to reach that goal.

Whonix ™-Example-Implementation: