[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/anon-meta-packages/blob/master/debian/control ^[archive]

Files[edit]

Essential[edit]

Anonymizer[edit]

An application to anonymize network traffic, called anonymizer, is required. The application to anonymize network traffic has to be obtained from a safe download source. Increase file maximum, if required by the anonymizer.

Whonix ™-Example-Implementation:

Whonix ™ is based on Tor.
Tor configuration file: ~~https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/etc/torrc.d/50_user.conf.whonix ^[archive]~~ https://github.com/Whonix/anon-gw-anonymizer-config/tree/master/etc/tor ^[archive] ?
Torproject's Debian repository added to package lists: https://github.com/Whonix/anon-shared-build-apt-sources-tpo/blob/master/etc/apt/sources.list.d/torproject.list ^[archive]
Torproject's archive public key: ~~https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/gpg-pubkeys/torprojectarchive.asc ^[archive]~~
Adding Torproject's archive public key to the apt package manager: ~~https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/40_add_torprojects_key ^[archive]~~
Updating package lists to fetch metadata from torproject's repository: ~~https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/50_update_package_lists ^[archive]~~
Installing Torprojects Debian package deb.torproject.org-keyring, which helps to keep Torprojects signing key current and installing tor tor-geoipdb tor-arm torsocks obfsproxy.: ~~https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/share/whonix/chroot-scripts/70_tor ^[archive]~~
Increase file maximum, if required by the anonymizer: https://github.com/Whonix/Whonix/blob/master/whonix_gateway/etc/sysctl.d/whonix.conf ^[archive]

Network Configuration[edit]

The Gateway needs two network interfaces. An external interface to communicate with clearnet for Tor and an internal interface to communicate with the Workstation.

Disable IPv6, if not supported by the anonymity network.

Disable IP forwarding, if it is not required due to the firewall rules (such as in case of Tor, which offers a TransPort and a DNSPort).

Configure the system resolver to use the anonymity network to resolve DNS. - This is not required to anonymize traffic of the Workstation. The system resolver of the Gateway should not get used by any applications anyway, because they are explicitly configured to use the anonymity network. Useful as defence in depth. DNS and other traffic from the Workstation gets forced by the Gateway's firewall to use the anonymity network. The Gateways's own traffic gets anonymized with the purpose of hiding the existence of the Gateway from the ISP, as it is expected that most users do not want to announce the existence of a Gateway, which may indicate that they run onion services or other applications over Tor. The Gateway could alternatively fetch its own operating system updates over clearnet, but since package selection is unique clearnet traffic may imply Gateway. And, as package downloads are only authenticated, not encrypted, it is better to download the updates over the already to hand anonymity network. As an anonymity network, such as Tor, with changing exit relays (and thus exit ISPs) is getting used, this also makes it even harder for an adversary to interfere with the update process. The last sentence gets elaborated on the Design Shared page in chapter about "Operating System Updates".

Prevent DHCP from updating the system resolver.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/tree/master/build-steps.d/2500_create-vbox-vm ^[archive] in function gateway_specific, two virtual network cards are added. The first one, type NAT. The second one, type internal.
https://github.com/Whonix/whonix-gw-network-conf/blob/master/etc/network/interfaces.d/30_non-qubes-whonix ^[archive]
Disable IPv6, Disable IP forwarding. https://github.com/Whonix/ipv6-disable/blob/master/etc/sysctl.d/ipv6-disable.conf ^[archive] https://github.com/Whonix/ipv4-forward-disable/blob/master/etc/sysctl.d/ipv4-forward-disable.conf ^[archive]
Prevent DHCP from updating the system resolver. https://github.com/Whonix/anon-gw-dhcp-conf/blob/master/etc/dhcp/dhclient-enter-hooks.d/nodnsupdate ^[archive]
Configure system resolver to use the anonymity network to resolve DNS. https://github.com/Whonix/anon-gw-dns-conf/blob/master/etc/resolv.conf.anondist ^[archive]

Firewall[edit]

Add a firewall, which permits only the anonymizer's traffic to reach the internet.

Whonix ™-Example-Implementation:

Firewall script: https://github.com/Whonix/whonix-gw-firewall/blob/master/usr/bin/whonix_firewall ^[archive]
configuration file: https://github.com/Whonix/whonix-gw-firewall/blob/master/etc/whonix_firewall.d/30_default.conf ^[archive]
.d-style configuration folder: https://github.com/Whonix/whonix-gw-firewall/tree/master/etc/whonix_firewall.d ^[archive]

Debugging[edit]

Firewall Removal[edit]

Optional

Include a command to easily remove all firewall rules, which can not be run by accident without editing the file with root rights.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/bin/dev_clearnet ^[archive]

Leaktest script[edit]

Optional

Have a script to try to produce a leak and check if there are any leaks.

Whonix ™-Example-Implementation:

Clearnet User[edit]

Optional

To have a user account "clearnet" on the Gateway may be helpful for debugging, an "unsafe" browser (which can be used to register public hotspots).

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/share/whonix/chroot-scripts/70_clearnetuser ^[archive]

Usability[edit]

Tor Controller[edit]

Optional

Whonix ™-Example-Implementation:

Arm is installed by default and documented on the Tor Controller page.
Tor Controller startup script. Starting Tor controller without password by using "sudo arm": https://github.com/Whonix/Whonix/tree/master/whonix_gateway/usr/bin/arm ^[archive]

Help file[edit]

Optional

When the user types a short and easy command, the most important and most asked commands should be listed.

Whonix ™-Example-Implementation:

User can type "whonix".
https://github.com/Whonix/whonix-base-files/blob/master/usr/bin/whonix ^[archive]

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: