Whonix ™ friendly applications best practices
config.d support[edit]
Please parse a /etc/your-application.d
configuration folder (and /usr/local/etc/your-application.d
for better Qubes support) so Linux distributions such as Debian, Kicksecure ™ and Whonix ™ can set defaults (such as proxy / stream isolation configuration). Users are of course free to overrule these defaults using the usual configuration files in the user's home folder.
Please parse only configuration files with a file extension such as .conf
. This is because graphical editors such as kate
create backup files such as file-name~
or APT / dpkg creating files such as config-file-name.dpkg-old
which would lead to unexpected results.
Stream Isolation[edit]
- Please set a socks user name for Stream Isolation. (
IsolateSOCKSAuth
)
add_onion[edit]
- Please use
add_onion
Tor control protocol command / Tor ephemeral onion services.
ephemeral: Means the onion service will be gone after the Tor control connection is closed. It's however possible and usual to retrieve onion service private key and to restore it at next run.
For example ricochet by @special
is doing that.
Tor ephemeral onion services are a lot a lot better for Whonix ™ than preconfigued Tor hidden services.
OnionShare by @micahflee
has superb Tails and Whonix ™ support.
Listen Interface[edit]
- Listen on all interfaces rather than just localhost. (This is required since the incoming onion service connection comes from the network, not from localhost.)
# In Whonix, listen on 0.0.0.0 instead of 127.0.0.1 (#220) if os.path.exists('/usr/share/anon-ws-base-files/workstation'): host = '0.0.0.0' else: host = '127.0.0.1'
Related: Listen Port Convention
Listen Port[edit]
- Don't listen on a random local server port.
- Listen on a specific local server port or port range.
- Tor
VIRTPROT
(remote virtual port on the onion service) does not matter. - [1]
Tor Settings Autodetection[edit]
- Auto detect Tor settings through
TOR_*
environment variables.
In Whonix:
TOR_CONTROL_IPC_PATH=/var/run/anon-ws-disable-stacked-tor/127.0.0.1_9151.sock
TOR_SOCKS_IPC_PATH=/var/run/anon-ws-disable-stacked-tor/127.0.0.1_9150.sock
These are unix domain socket files.
Ports would also work but nowadays unix domain socket files are much more advisable since these are less likely to leak.
Robustness[edit]
- The application should not crash if Tor
ControlPort
replies something unexpected such as510 Command filtered
.
Usability[edit]
- Show an error message if Whonix ™ is detected and
ControlPort
seeing510 Command filtered
replies. Sample error message:Error talking to the Tor controller.\nIf you're using Whonix ™, check out https://www.whonix.org/wiki/ProgramName
to make ProgramName work.
- onionshare has a Tor settings dialog
. But not really needed in Whonix ™.
Bonus[edit]
- Bonus: Make a list of Tor control commands you are using so an onion-grater profile can be written.
- Bonus: Write an onion-grater profile
.
Programmatically Detecting Whonix ™[edit]
Various marker files are available:
- Whonix ™ generally:
/usr/share/whonix/marker
- Whonix-Gateway ™:
/usr/share/anon-gw-base-files/gateway
- Whonix-Workstation ™:
/usr/share/anon-ws-base-files/workstation
See Also[edit]
- See also Tor friendly applications best practices
.
Forum Discussion[edit]
https://forums.whonix.org/t/whonix-friendly-applications-best-practices
Footnotes[edit]
- ↑
- onionshare uses
17600 - 17659
. That is handy, so we can match for it using(176[0-5][0-9])
in the onionshare onion-grater whitelist config.
- That way onionshare (running inside a compromised workstation) cannot open arbitrary ports on the workstation. For example, not to the real Tor
ControlPort
and circumvent the filtering. (We use TorControlSocket
rather thanControlPort
now for this reason.) There are no local ports open on Whonix-Gateway ™ besides TorSocks
,DNS
andTransPort
, but if there was (let's say for example for brltty), then we don't want connections to it.
- That allows us to set a limit on how many Tor hidden services (a compromised) workstation can create.
- It's also useful so users don't have to open all incoming ports in Whonix-Workstation Firewall.
- onionshare uses