Jump to: navigation, search

Dev/Design-Shared

< Dev



[edit]

Authoring Notes:

  • Start with a general description below each headline. Be as general as possible, trying to avoid even using such terms as 'Tor'.
  • Next, describe the Whonix Example Implementation, showing exactly how Whonix implements the goals stated above.


Last updated git[edit]

4a70f4868d683a08b73c6236b36684220d704d97

Get Build Dependencies[edit]

Install a tool to create Virtual Machine images (such as grml-debootstrap) and tools for mouting and apply other useful build configurations.

Whonix-Example-Implementation:

Get Base Operating System[edit]

Use a tool to create a Virtual Machine base installation, which contains a secure operating system and which is bootable.

Whonix-Example-Implementation:

Other Implementations:

  • Old Whonix versions up to 0.3.0 used Ubuntu as base operating system.
  • Old Whonix versions up to 0.3.0 used Preseed, installed the operating system from DVD inside a Virtual Machine.
  • This step can also be done manually, i.e. the user could be told to manually install some operating system.
  • Whonix with Physical Isolation.

Backup Base Operating System[edit]

Make a backup of that image. This is not strictly required, but you will want to modify that image often and want to start fresh often.

Whonix-Example-Implementation:

Mount Image[edit]

Mount the image, so files can be copied into it.

Whonix-Example-Implementation:

Copy Files Into Image[edit]

Copy configuration files and chroot scripts into the Virtual Machine image to transform it into a Gateway or Workstation.

Whonix-Example-Implementation:

Chrooting[edit]

As preparation for the next step, there must be a method to chroot the mounted image.

Whonix-Example-Implementation:

Running Scripts inside Chroot[edit]

The base operating system has to be modified. Some scripts need to be executed inside the virtual machines. This is called running chroot scripts.

Whonix-Example-Implementation:

Unchrooting[edit]

The process of chrooting must be undone after the chroot scripts were executed.

Whonix-Example-Implementation:

Unmounting[edit]

The image must be unmounted after the copying files into it or after chrooting, running chroot scripts and unchrooting.

Whonix-Example-Implementation:

Creating a Virtual Machine package[edit]

It's useful to deploy the Virtual Machine images through a package format, which makes it easy to import them for users.

Whonix-Example-Implementation:

Files[edit]

Essential[edit]

Username, FQDN, hostname[edit]

Hosts file. Use non-identifying values for FQDN and hostname, because some applications may leak it. (Mixmaster is known to leak it.) Set FQDN to "host.localdomain" and set hostname to "host". It's best when they are shared among anonymity focused distributions.

It's recommended to work as non-privileged user and not using one will get into usability trouble (desktop environments don't like running as root). For usability, consistency, defence in depth, name it "user". It's better to say non-saying operating system user account names and ideally share them among anonymity focused distributions since the user could accidentally leak it (ex: ssh).

Whonix-Example-Implementation:

Operating System Updates[edit]

Configure the package manager.

Configure software repositories.

Do not use the default automatic updates mechanism and use higher timeouts. It's better to disable the operating system's default automatic update mechanism, because times of automatic run are too predictable. The network fingerprint (not web fingerprint) could help an ISP guessing, that there is a network hidden operating system.

Notify about operating system updates in a safe way.

Misc settings, higher timeouts, more retries when package download or DNS resolution fails. This is useful because anonymity networks are slow and otherwise updating would occasionally fail due to network problems.

Must have a secure operating system updater (package manager), i.e. must not fall through the TUF Threat Model (w). Additionally, downloading should go thought an anonymity network, with changing exit relays. This makes an adversary less likely to interfere with the update process, because updates go through different ISPs, which makes it much more difficult to mount a man-in-the-middle attack over an extended amount of time.

The package manager shouldn't confuse the user with questions to keep the locally installed configuration file or to install the new version from the upstream package maintainer.

Whonix-Example-Implementation:

TimeSync[edit]

Add a secure method with distributed trust to obtain date and time, because a clock which is drift, is bad for anonymity.

Whonix-Example-Implementation:

General Information

Start Hooks

Install Hooks

Supporting Files

Script

Banned Packages[edit]

Some packages aren't suited for an anonymous operating system. Reasons are privacy issues or messing with network settings. Ensure, that those get removed, if they got installed by the virtual machine image creation tool. This shouldn't be the case because of the hand selected package selection. Just in case upstream dependencies change or custom packages get added by users who build from source code. Ensure that those packages won't get installed by accident. Since it's documented, advanced users can overwrite these recommendations if they know better.

Whonix-Example-Implementation:

Stream Isolation Wrapper[edit]

Stream isolate different applications to prevent identity correlation through circuit sharing. To my knowledge, only the anonymizer Tor supports this feature.

Whonix-Example-Implementation:

Extra[edit]

Time Privacy[edit]

Applications such as gpg and git embed time stamps in their output. For improved privacy it may make sense to fake this data. The user should enable it oneself, otherwise it could be very surprising and may not do what the user wants. Experimental design and implementation. Disabled by default.

Whonix-Example-Implementation:

hdd configuration / swap / Disk uuid / dbus machine-id[edit]

Since the virtual machine creation tool won't create a swap partition (which is actually good because it simplifies the setup) but the system could run out of memory, add a swap file. The is optional depending on the operating system and available RAM. Configure swap to be used as little as possible to improve speed.

Whonix-Example-Implementation:

Base Files[edit]

Perhaps only required for Debian and derivatives. Whonix was asked to replace the default dpkg origin symlink.

Whonix-Example-Implementation:

Usability[edit]

check mechanism[edit]

Recommended, not strictly required.

Whonix-Example-Implementation:

General Information

  • whonixcheck
  • Whonixcheck essentially runs whonixcheck at least once very day.
  • Whonixcheck, although run on each boot and every hour by cron, itself is rate limited and stops running checks, if it was run less than one day ago. The user can always manually perform all whonixcheck checks.

Start Hooks

Supporting Files

Script

Desktop Environment[edit]

Optional.

It's useful to have a desktop preconfigured to make it as easy as possible for users who use Linux for the first time.

Whonix-Example-Implementation:

sudoers[edit]

Optional. For convenience. Only recommended for Virtual Machines.

Allow shutdown, reboot and poweroff without a password. Allow starting Tor Controller arm without password. (No effect on Workstation, since arm is only Gateway.) Allow mixmaster-update without password. (No effect on Gateway, since mixmaster is only installed on Gateway.)

Whonix-Example-Implementation:

Console Autologin[edit]

Optional. Only recommended for virtual machines.

Whonix-Example-Implementation:

Console Default Password Hint[edit]

Optional.

The system will be shipped with a default password (which users are suggested to change in documentation). To prevent user frustration when not knowing the password it greatly reduced (from Whonix experience) support requests if the default password is displayed right above the password prompt.

Whonix-Example-Implementation:

Console Welcome Message[edit]

Optional.

Contains general information about derivative, licensing, default passwords, how to open the help file.

Whonix-Example-Implementation:

Deactivate display power saving in Virtual Machines[edit]

Since it's confusing and not useful and not saving any energy. (Needs to be applied on host.)

Whonix-Example-Implementation:

boot manager configuration[edit]

Optional. For higher boot resolution, it's required to run update-grub after changing grub configuration files.

Whonix-Example-Implementation:

update command not found[edit]

Optional.

Initially update the command not found database, to prevent showing "please run update-command-not-found" in case a non-existent command gets entered in console.

Whonix-Example-Implementation:

Secure/SSL Command Line Downloader[edit]

Add a command line downloader, which enforces using https (SSL).

Whonix-Example-Implementation:

Slim Down[edit]

Optional. To safe space and to prevent (some) development related leaks, remove cache, temporary files, dhcp leases, package manager cache, logs, history.

Whonix-Example-Implementation:

Icons[edit]

Optional.

Some pretty icons for the start menu and the desktop for custom applications, which are only useful in a Gateway/Workstation design.

Whonix-Example-Implementation:

Debugging[edit]

Sanity Checks[edit]

Recommended, not strictly required.

Some simple tests to check for example, if all files have been correctly copied into the image, if the package manager is fully functional, because some virtual machine creation tools build broken images. Package integrity checks.

Whonix-Example-Implementation:

Misc[edit]

Optional.

Whonix-Example-Implementation:

Variables[edit]

Recommended, not strictly required.

It's useful to configure the system, not to ask any questions which require user interaction such as when you plan to run the package manager from within chroot. This is because interaction isn't useful when automating things.

Whonix-Example-Implementation:

Package Cache[edit]

Optional.

If the package manager is used inside chroot, it makes sense to run it though a cache, so debugging steps can be done faster.

Whonix-Example-Implementation:

What is /usr/local/share/whonix/apt.conf good for?

This apt.conf is only used inside chroot and currently only in effect for "./debug-steps/download-source -tg" and "./debug-steps/download-source -tw".

It points to http://10.152.152.11 :3142, which is expected to be a Whonix-Workstation with apt-cacher-ng running. It's useful for running "apt-get install" and "apt-get source" inside chroot, because downloads are cached, which speeds up the build process when building several times in a row. (Debugging with only minor changes.)

In case you don't want to use it or to use another proxy, edit /home/user/Whonix/whonix_shared/usr/local/share/whonix/apt.conf (comment out with a # or change proxy settings). Don't forget "sudo ./build-steps.d/30_copy-into-img -tX" after modifying the file.

Prevent daemons from starting inside chroot[edit]

Optional.

Only in case you want to install something inside chroot for debugging purposes. Otherwise they can lock the chroot folder and you won't be able to unchroot.

Whonix-Example-Implementation:

Indicate last chroot script[edit]

Not strictly required. A chroot script, which indicates that all went well.

Whonix-Example-Implementation:

Lower priority while building[edit]

Optional. Not strictly required.

Using ionice and renice.

Whonix-Example-Implementation:

Enable debugging[edit]

Optional. Not strictly required.

When using bash, set -x to show each command that gets executed.

Whonix-Example-Implementation:

Error handling[edit]

Optional. Not strictly required.

It's important to ensure that there are no error while copying files into the images or while running the chroot scripts because many steps are essential. Stop and loudly complain if any unexpected error occurs.

Whonix-Example-Implementation:

Delete Virtual Machine files[edit]

Optional. Not strictly required.

So they can be re-created for debugging purposes.

Whonix-Example-Implementation:

Interactive Chroot[edit]

Optional. Not strictly required.

After creating the base operating system image, after copying files into it or after applying the chroot scripts, it's useful to have a command, which allows to look around inside the image without having to boot the image. Adrelanos calls this Interactive Chroot.

Whonix-Example-Implementation:

Licensing[edit]

Only required for builds, which will be redistributed in public.

Make a list of GPLed software.

Whonix-Example-Implementation:

Build Automation[edit]

Optional. Not strictly required.

Since many steps are required to build a Gateway or Workstation, it's useful to automate build creation.

Whonix-Example-Implementation:

Release Automation[edit]

Optional. Not strictly required.

Since many steps are required to redistribute a Gateway or Workstation, it's useful to automate releases.

Whonix-Example-Implementation:

Other important things[edit]

The things on this (Design-Shared) page are supposed to be added to the Gateway and the Workstation.

To build a Gateway, also things from the Dev/Design-Gateway page have to be added.

To build a Workstation, also things from the Dev/Design-Workstation page have to be added.

Justify other design decisions, what the project doesn't and what it doesn't do. Have loads of documentation. Have a source code hacking guide and source code introduction.

Whonix-Example-Implementation:


Random News:

Interested in becoming author for Whonix blog? Writing about anonymity/privacy/security? Get in touch!


Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
This is a wiki. Want to improve this page? Help welcome, volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation. Whonix (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.