Installation - maqp/tfc Wiki

Installation process overview

When obtaining software online, there is usually a long and complicated PGP verification process where you need to import keys, verify key fingerprints, download the software and its detached signature, verify the software with the signature, and then install the software if everything was okay.

TFC is installed with a one-liner, a kind of mini-program, that does all the complex steps above for you. It does everything except one thing: You must compare the signature verification key's SHA-256 fingerprint 6f752f451f2690b54048406b0714a271f827530c995fd4c5875fe26ad9db172f used in the one-liner with a copy obtained from a trustworthy source, before executing the one-liner. The fingerprint is the root of trust for the entire project.

If you don't not have a way to verify the fingerprint, you should at least write it down for TOFU, meaning you will detect an attack if the key fingerprint changes prematurely. The current signature verification key expires on June 5, 2022. Your connection will also be protected by GitHub's TLS (which is excellent but not designed against nation-state actors).

For a complete explanation on what the one-liner does, see this wiki article.

0. Preparation of hardware

Before installing TFC on Source/Destination Computer, you must make sure both have been stripped from all devices that malware might use to covertly leak data:

The computer should be connected to the network with an Ethernet cable; If the computer has no Ethernet port, a USB-to-Ethernet adapter should be used. The OS installation must be fresh, and full-disk-encryption (not just encryption of home directory) must be enabled during installation.

1. Preparation of OS

If you're installing TFC on Debian, make sure the user has sudo privileges.

$ su -
# usermod -aG sudo <username>
# reboot

After reboot, the you should be able to sudo. You can test this by running e.g.

$ sudo echo test

If the the message test is echoed after you enter password, you now have sudo privileges.

For Qubes, you should update both Dom0 and all Template VMs before installing TFC.

For all other operation systems, it's highly recommended you update the OS before installing TFC with

$ sudo apt update && sudo apt upgrade -y

This prevents the installer from failing due to background update process with the following message:

E: Could not get lock /var/lib/dpkg/lock-frontend - open (11: Resource temporarily unavailable)
E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?

Warning! The X11 window manager does not protect inputs to e.g. TFC Transmitter Program from other user-level applications running in the background. Use of Wayland is thus necessary.


2. Select configuration specific instructions

You should select the hardware-isolated configuration when the communication must stay secure even if an organized crime group or nation state actor tried to remotely hack your devices to steal the keys and messages from the endpoints. See full threat model here.

3. Execute following one-liner in the terminal:

The installer is fully automatic. For TCB (Source and Destination Computer) configurations, once everything has been downloaded from the network, the installer will turn down the network interfaces of the system. TFC will notify you about this and wait for you to hit a key before continuing. You can confirm the network connection goes down from the GNOME menu, where the network interface message Wired Connected disappears. To guarantee the system stays offline, you should disconnect the Ethernet cable permanently at this point. Other installation configurations do not show this behavior as they are not supposed to be disconnected from the network.

Indication of disabled network interface


For TCB and Relay configurations, the installer will prompt you to insert the USB-to-serial/TTL adapter if you intend to use such for the computer. If the interface is not plugged at this point, serial permissions can not be set for the session, and you must restart your computer before TFC can use the serial port. Note that in the case of Tails configuration, the user amnesia is already in the dialout group, thus no restart is required.

Indication of disabled network interface


The installer will notify you when the installation completes. You can then close the installer by hitting any key.

Message about completed installation

4. Launch Transmitter / Receiver / Relay Program

In the case of TCB configurations, TFC is launched from the TFC-Transmitter and TFC-Receiver launcher which you can find in the OS specific app search system, or under the Internet, Messaging, or Security submenu of the OS's Applications menu.

Transmitter and Receiver Program launchers

You can find the launcher for Relay Program for Networked Computer the same way.

Relay Program launcher

Running TFC on Qubes allows Xen hypervisor based isolation for the TCBs. In Qubes-isolated configuration, each TFC program runs on a dedicated Debian 10 virtual machine (VM) called a Qube. The Source and Destination VMs are isolated from the network by the hypervisor, and inter-VM data transfers are handled with qrexec RPC calls.

The Qubes-isolated configuration adds some protection against remote key/plaintext compromise. It is not (and will never be) as secure as the hardware-isolated configuration:

That being said, architecture-wise, the Qubes-isolated configuration is still much, much more secure than e.g. the local testing configuration, or any other E2EE messaging app on a single networked OS, whether that OS is running as host or as a Qubes guest VM. An attacker can compromise a networked OS via many paths, and if keys and plaintexts reside in that system, they are trivial to exfiltrate. In contrast, TFC's Qubes-isolated configuration has extremely small attack surface, as compromise of Destination VM requires compromising the qrexec framework, or TFC's RPC service:

The Qubes-isolated configuration should thus be used when the adversary is assumed to be in possession of some exploits, but not in possession of rare Xen exploits.

To get started, download the Qubes OS 4.0.3 ISO file, authenticate it, and install Qubes on your computer.

3. Update QubesOS

Update the dom0 system, and both the debian-10 and the fedora-30 Template VM before installing TFC.

This can be done by opening the Qube Manager by navigating to Applications menu > System Tools > Qube Manager...

Qube Manager location

...and by right-clicking the dom0, debian-10 Template VM, and the fedora-30 Template VM, and by selecting Update qube from the context menu:

Updating qube from context menu

4. Create TFC VMs

You can create the VMs by clicking on the Applications button (Qubes OS logo on the top-left corner of the screen), and by clicking the Create Qubes VM from the appearing drop-down menu.

Creating new Qubes VMs

Create following VMs for TFC.

WARNING: The VM names are hard-coded into TFC. Use the exact same names for your TFC VMs.

  1. Name: TFC-Source
  2. Label color: blue
  3. Type: Standalone qube copied from a template
  4. Template: debian-10
  5. Networking: sys-firewall

TFC-Source VM creation

  1. Name: TFC-Networker
  2. Label color: red
  3. Type: Standalone qube copied from a template
  4. Template: debian-10
  5. Networking: sys-firewall

TFC-Networker VM creation

  1. Name: TFC-Destination
  2. Label color: yellow
  3. Type: Standalone qube copied from a template
  4. Template: debian-10
  5. Networking: sys-firewall

TFC-Destination VM creation

If you're an advanced user, you should increase the amount of RAM and the number of available threads (VCPUs no.) for the Source and Destination VMs to allocate more resources for the Argon2 key derivation.

VM Memory/CPU settings

5. Open the TFC wiki page anonymously

5.1. Launch the Tor Browser by navigating to Applications > Domain: anon-whonix > anon-whonix: Tor Browser (AnonDist).

Launching Tor Browser on Whonix domain

5.2. Navigate to this very page (https://github.com/maqp/tfc/wiki/Installation) using the Tor Browser

TFC installer page open in Tor Browser

6. Run the TFC installer one-liner in the TFC VM terminals

6.1. From the Applications menu, click on the Terminal under each TFC VM

Launching TFC VM's terminal

6.2. Copy and paste the correct one-liner (below) from the Tor Browser window into the Terminal of the correct VM.

Installer one-liners copied to TFC VMs

Make sure to double-check that you copied the correct command into each terminal. Once you've verified the command, you can press Enter in each terminal to start the installation for that VM. The rest of the installation is fully automatic and the installer will notify you when the installation completes. You can then close the installer by focusing the VM and hitting any key.

Completed TFC installers

7. Create dom0 policy files

The installation of TFC on the three VMs takes a few minutes. In the meantime, you should open the dom0 terminal

Launching dom0 terminal

and type these two commands into dom0's terminal. These commands set the policies that allow the VMs to talk to one another over qrexec.

echo "TFC-Source TFC-Networker allow" > /etc/qubes-rpc/policy/tfc.SourceNetworker
echo "TFC-Networker TFC-Destination allow" > /etc/qubes-rpc/policy/tfc.NetworkerDestination

Launching dom0 terminal

8. Disable network from Source and Destination VM

WARNING! Do not proceed to this step until installation has completed on TFC-Source and TFC-Destination VMs. Repeat following steps for both TFC-Source and TFC-Destination VMs:

  1. In the Qube Manager, right-click the VM name and select Kill qube, and click Yes in the confirmation dialogue
  2. Right-click the VM name and select Qube Settings
  3. In the Qube Settings panel, stay on the Basic tab and click the Networking drop-down menu.
  4. Select (none) in the drop-down menu
  5. Click OK in the bottom right corner.

Disable Source/Destination VM networking

Remember to repeat this for the TFC-Destination VM!

9. Setup TFC Launchers

9.1. In the Qube Manager, right-click each TFC VM and select Qube Settings

Qube settings location

9.2. In the settings panel

  1. go to the Applications tab
  2. press the Refresh Applications button
  3. select the TFC application
  4. press the > button to add TFC to the Selected applications list.
  5. Finally, press OK to close the AppVM settings.

Adding TFC to the application menu of its VM

10. Launch TFC

You can now launch TFC from the dedicated launcher under each TFC VM in the Qubes' Applications menu.

TFC's VM specific launcher

You can also launch TFC by entering

Launching TFC application from VM's terminal

11. Create master passwords and proceed with the use

TFC applications running on their dedicated VMs

Tip: During the use, you can save time and effort by using the Qubes' inter-VM clipboard feature to copy values -- that you'd normally need to type by hand -- across VMs in a reasonably secure way:

Copied local key decryption key

Pasted local key decryption key

To stay safe, pay attention to the message on the amount of data copied to the the clipboard. It should say

This is very important, because if malware would try to jump over the isolation, it is very likely the clipboard would contain different amount of data to fit some malicious payload.


Use of TFC is quite straightforward, but if you need further assistance, please refer to the How to use articles in the TFC Wiki. Again, for the sake of privacy, it's best to access the wiki only using the Whonix VM's Tor Browser.

The local testing configuration is an easy way to emulate a complete TFC system (software and hardware) with just software, on a single Linux OS (Debian/PureOS/Ubuntu/Mint/LMDE). It is mainly intended for users who want to try out the features and study the system before buying additional computers and building the data diode (or before installing Qubes for the related TFC configuration).

Warning! The local testing configuration does not provide endpoint security.

If however, the threat model does not include a scenario where someone is going to try to remotely hack your endpoint, the local testing configuration still offers superior protection against adversaries in the network who would try to observe content and/or metadata of users' communication. The local testing configuration is thus an alternative to normal end-to-end encrypted apps like Signal (that does not anonymize the user with Tor by default), and Ricochet (that uses older generation Onion Services) under similar threat model.

3. Execute the following one-liner in the terminal:

The installer is fully automatic and will notify you when the installation completes. You can then close the installer by hitting any key.

Message about completed installation

4. Launch the Local testing configuration

You can launch the local testing configuration with the TFC-Local-Testing launcher which you can find in the OS specific app search system, or under the Internet, Messaging, or Security submenu of the OS's Applications menu.

Local Testing configuration launcher

Local testing launcher layouts

By right-clicking the local testing launcher, you can select different local testing layouts:

Right-clicking the launcher allows layout selection

The default layout

The default layout is TFC-Local-Test-LR that has the Transmitter and Receiver Programs on the left side of the Relay Program. The layout of TFC-Local-Test-RL is vice versa. These layouts can be used to simulate mirrored hardware setups similar to those in TFC's README rendering.

Default layout for local testing

The default local testing layout runs the three main programs that normally run on three separate computers, inside Terminator, a tiling terminal emulator.

Comparison between normal operation and default local testing layout

Data diode simulator layout

The TFC-Local-Test-DD-LR and TFC-Local-Test-DD-RL layouts run like the default layout, with the exception two additional programs called data diode simulators are launched. These two programs simulate and visualize data transmission through the data diode from the Source Computer to the Networked Computer, and from the Networked Computer to the Destination Computer. The tiling terminal emulator places the data diode simulators between Transmitter and Relay Program, and between Relay and Receiver Program. It automatically orients the direction of data diode simulator's Tx and Rx end depending on whether the user chooses the LR or RL configuration. Please note that the data diode simulators do not provide any of the endpoint security guarantees the hardware data diodes do.

Layout for local testing with data diode simulators

Comparison between normal operation and local testing layout with data diode simulators