Installing and Configuring SecureDrop Workstation

Warning

SecureDrop Workstation is in a limited beta phase, and is not recommended for general use at this time. See our blog post for more information.

Overview

SecureDrop Workstation must be installed on a system running Qubes OS. The installation and configuration process should take between 4 and 6 hours, including time spent waiting for downloads and updates. At a high level, the tasks to be performed are as follows:

Pre-install tasks:

  1. Verify the SecureDrop server configuration
  2. Apply BIOS updates and check settings
  3. Download and verify Qubes OS
  4. Install Qubes OS
  5. Apply updates to system templates
  6. Install Fedora 31 base template

Install tasks:

  1. Copy the submission key
  2. Copy Journalist Interface details
  3. Copy SecureDrop login credentials
  4. Download and install SecureDrop Workstation
  5. Configure SecureDrop Workstation
  6. Test the Workstation

Prerequisites

In order to install SecureDrop Workstation and configure it to use an existing SecureDrop instance, you will need the following:

  • A Qubes-compatible computer with at least 16GB of RAM (32 GB is recommended). SecureDrop Workstation has mainly been tested against Lenovo 6th-gen T480 and X1 models - see Qubes’ Hardware Compatibility List and the SecureDrop Workstation Recommended hardware page for more options .

  • Qubes installation medium - this guide assumes the use of a USB 3.0 stick. Qubes may also be installed via optical media, which may make more sense depending on your security concerns.

    Note

    A USB stick with a Type-A connector is recommended, as USB-C ports may be disabled on your computer when the BIOS settings detailed below are applied.

  • The SecureDrop instance’s Admin Workstation and Secure Viewing Station (SVS) USBs, and the full GPG fingerprint of the submission key.

  • (Optional, for a single-user workstation) The Journalist Workstation USB for the intended user of this workstation, if you want to import their SecureDrop login credentials into the workstation’s password manager.

  • The passphrases required to unlock the persistent volumes on each of these USB drives.

  • A working computer (Linux is recommended and assumed in this guide) to use for verification and creation of the Qubes installation medium.

    Note

    A Tails USB can be used to perform the tasks below, but due to the size of the Qubes installation ISO, it may make sense to download it on another computer rather than via Tor, and then to use a USB stick to transfer it to Tails for verification and creation of the installation medium.

  • A password manager or other system to generate and store strong passphrases for Qubes full disk encryption (FDE) and user accounts.

A basic knowledge of the Qubes OS is helpful.

Pre-install tasks

Verify the SecureDrop server configuration

In order to be used with SecureDrop Workstation, your instance must be running the latest version of SecureDrop, and the server configuration must have been updated to allow for HTTP DELETE requests. The configuration change to enable this was added in the 0.13.0 version of SecureDrop, released on May 29 2019. If your instance was created using this or a later version, it has the necessary changes. If not, then the ./securedrop-admin install command must have been run from an Admin Workstation updated with the 0.13.0 code or later. To check this:

  • Use an Admin Workstation USB to boot into Tails, with the persistent volume unlocked and an administration password set.

  • Navigate to Applications ▸ System Tools ▸ Terminal to open a terminal.

  • Verify that the Journalist Interface Apache configuration allows for HTTP DELETE using the following command:

    ssh app "grep '^\s\s<LimitExcept GET POST HEAD DELETE>$' /etc/apache2/sites-enabled/journalist.conf"
    
  • If your instance is configured correctly, this command will output two lines as follows:

    <LimitExcept GET POST HEAD DELETE>
    <LimitExcept GET POST HEAD DELETE>
    
  • If not, then you will need to:

    • Update the Admin Workstation to the current SecureDrop release version, by following the applicable upgrade guide in our documentation.
    • Back up the SecureDrop instance, using the server backup instructions.
    • Verify that the configuration stored on the Admin Workstation is correct by running cd ~/Persistent/securedrop && ./securedrop-admin sdconfig. This command will display each setting in turn - to accept without changing, press Enter for each.
    • Update the instance configuration by running ./securedrop-admin install.
  • When the instance configuration is up to date, continue with the SecureDrop Workstation installation.

Apply BIOS updates and check settings

Before beginning the Qubes installation, make sure that your Qubes-compatible computer’s BIOS is updated to the latest available version. If you’re using the recommended ThinkPad T480, see the Upgrading the T480 BIOS section in this documentation. The process will be different for other makes and models, and can usually be found on their respective support sites.

Once the BIOS is up-to-date, boot into the BIOS setup utility and update its settings. Note that not all BIOS versions will support the items listed, but if available following changes are recommended:

  • Ensure the internal clock is correct.
  • Set a password to access the BIOS (and record the password in your password manager).
  • Disable BIOS downgrades.
  • Enable Data Execution Prevention.
  • Enable virtualization support (required for Qubes OS). - for Intel-based devices, Intel VT-d and Intel VT-x should be enabled - for AMD-based devices, AMD-VI and AMD-V should be enabled
  • Disable unnecessary I/O options such as Wireless WAN and Bluetooth.
  • Disable Thunderbolt ports, or any other ports that allow Direct Memory Access (DMA).
  • Enable any physical tamper detection options.
  • Disable Computrace.
  • Disable SecureBoot.

If the Qubes hardware compatibility list entry for your computer recommends the use of Legacy Mode for boot, change that setting in the BIOS as well.

Download and verify Qubes OS

On the working computer, download the latest stable Qubes OS ISO (4.0.3 at time of writing) from https://www.qubes-os.org/downloads/. The ISO is 4.5GB approximately, and may take some time to download based on the speed of your Internet connection.

Follow the linked instructions to verify the ISO.

Once you’ve verified the ISO, copy it to your installation medium - for example, if using Linux and a USB stick, using the command:

sudo dd if=Qubes-R4.0.3-x86_64.iso of=/dev/sdX bs=1048576 && sync

where if is set to the path to your downloaded ISO file and of is set to the block device corresponding to your USB stick. Note that any data on the USB stick will be overwritten.

Caution

Make sure to verify that you have the correct device name using, for example, the lsblk command. You should write to the full device (eg. /dev/sdc) rather than to a partition (eg. /dev/sdc1).

Install Qubes OS (estimated wait time: 30-45 minutes)

To begin the Qubes installation, connect the Qubes install USB to your target computer and boot from it. You may need to bring up a boot menu at startup to do so - on Lenovo laptops, for example, you can do so by pressing F12 on boot.

Follow the installation documentation to install Qubes on your computer, ensuring that you:

  • Use all available storage space for the installation (as the computer should be dedicated to SecureDrop Workstation).

  • Set a strong FDE passphrase - a 6-word Diceware passphrase is recommended.

  • Create an administrative account named user with a strong password.

    Note

    Qubes is not intended to have multiple user accounts, so this account name and password will be shared by all SecureDrop Workstation users. The password will be required to log in and unlock the screen during sessions - choosing something strong but memorable and easily typed is recommended!

Once the installation is complete, you will be prompted to reboot into Qubes. Reboot, removing the install USB when the computer restarts.

You will be prompted to enter the FDE passphrase set during installation.

Note

On first booting into a Qubes OS 4.0.3 installation, you may be prompted to enter the FDE passphrase at a command-line prompt rather than via the GUI. The next system update will restore the GUI prompt.

After the disk is unlocked and Qubes starts, you will be prompted to complete the initial setup. Click the Qubes OS icon, then accept the default options and click Done. Finally, click Finish Configuration to set up the default system TemplateVMs and AppVMs.

Once the initial setup is complete, the login dialog will be displayed. Log in using the username and password set during installation.

Apply updates to system templates (estimated wait time: 45-60 minutes)

Before installing SecureDrop Workstation, you must set up network and Tor access, then update the system VMs:

  • After logging in, use the network manager widget in the upper-right panel to configure your network connection.

  • Next, configure Tor by selecting the Qubes menu (the Q icon in the upper left corner) and selecting Service: sys-whonix > sys-whonix: Anon Connection Wizard. In most cases, choosing the default Connect option is best. Click Next, then Next again. Then, if Tor connects successfully, click Finish. If Tor fails to connect, make sure your network conection is up and does not filter Tor connections, then try again.

    Note

    If Tor connections are blocked on your network, you may need to configure Tor to use bridges in order to get a connection. For more information, see the Anon Connection Wizard documentation.

  • Once Tor has connected, select Q > System Tools > Qubes Update to update the system VMs. in the [Dom0] Qubes Updater window, first check Enable updates for qubes without known available updates, then check all entries in the list above. Then, click Next. The system’s VMs will be updated sequentially - this may take some time. When the updates are complete, click Finish.

Install Fedora 31 template

See Upgrading to Fedora 31.

Install tasks

Copy the submission key

In order to decrypt submissions, your SecureDrop Workstation will need a copy of the secret key from your SecureDrop instance’s SVS. To protect this key and preserve the air gap, you will need to connect the SVS USB to a Qubes VM with no network access, and copy it from there to dom0. Note that you cannot directly copy and paste to the dom0 VM from another VM - instead, follow the steps below to copy the file into dom0:

  • First, use the network manager widget in the upper right panel to disable your network connection. These instructions refer to the vault VM, which has no network access by default, but if the SVS USB is attached to another VM by mistake, this will offer some protection against exfiltration.

  • Next, choose Q > Domain: vault > vault: Files to open the file manager in the vault VM.

  • Connect the SVS USB to a USB port on the Qubes computer, then use the devices widget in the upper right panel to attach it to the vault VM. There will be 3 listings for the USB in the widget: one for the base USB, one for the Tails partition on the USB, labeled Tails, and a 3rd unlabeled listing, for the persistent volume. Choose the third listing.

    Attach TailsData

  • In the the vault file manager, select + Other Locations, then click the persistent volume’s listing in the right panel. It will be named N GB encrypted, where N is the size of the persistent volume. Enter the SVS persistent volume passphrase to unlock and mount it.

    Unlock Tailsdata

  • Open a dom0 terminal via Q > Terminal Emulator, and run the following command to list the SVS submission key details, including its fingerprint:

    qvm-run --pass-io vault \
      "gpg --homedir /run/media/user/TailsData/gnupg -K --fingerprint"
    
  • Next, run the comand:

    qvm-run --pass-io vault \
      "gpg --homedir /run/media/user/TailsData/gnupg --export-secret-keys --armor <SVSFingerprint>" \
      > /tmp/sd-journalist.sec
    

    where <SVSFingerprint> is the submission key fingerprint, typed as a single unit without whitespace. This will copy the submission key in ASCII format to a temporary file in dom0, /tmp/sd-journalist.sec.

  • Verify the that the file starts with -----BEGIN PGP PRIVATE KEY BLOCK----- using the command:

    head -n 1 /tmp/sd-journalist.sec
    
  • In the vault file manager, select + Other Locations and eject the TailsData volume, then disconnect the SVS USB.

Copy Journalist Interface details

SecureDrop Workstation connects to your SecureDrop instance’s API via the Journalist Interface. In order to do so, it will need the Journalist Interface address and authentication info. As the clipboard from another VM cannot be copied into dom0 directly, follow these steps to copy the file into place:

  • Locate an Admin Workstation or Journalist Workstation USB drive. Both hold the address and authentication info for the Journalist Interface; if you also want to copy the journalist user’s password database, use the Journalist Workstation USB drive.

  • Connect the USB drive to a USB port on the Qubes computer, then use the devices widget in the upper right panel to attach it to the vault VM. There will be 3 listings for the USB in the widget: one for the base USB, one for the Tails partition on the USB, labeled Tails, and a 3rd unlabeled listing, for the persistent volume. Choose the third listing.

  • In the the vault file manager, select + Other Locations, then click the persistent volume’s listing in the right panel. It will be named `N GB encrypted, where N is the size of the persistent volume. Enter the persistent volume passphrase to unlock and mount it.

  • Copy the Journalist Interface configuration file to dom0. If your SecureDrop instance uses v3 onion services, use the following command:

    qvm-run --pass-io vault \
      "cat /run/media/user/TailsData/Persistent/securedrop/install_files/ansible-base/app-journalist.auth_private" \
      > /tmp/journalist.txt
    

    If your instance uses legacy v2 onion services, use the following command instead:

    qvm-run --pass-io vault \
      "cat /run/media/user/TailsData/Persistent/securedrop/install_files/ansible-base/app-journalist-aths" \
      > /tmp/journalist.txt
    
  • Verify that the /tmp/journalist.txt file on dom0 contains valid configuration information using the command cat /tmp/journalist.txt in the dom0 terminal.

  • If you used an Admin Workstation USB drive, or you don’t intend to copy a password database to this workstation, safely disconnect the USB drive now. In the vault file manager, select + Other Locations and eject the TailsData volume, then disconnect the USB drive.

Copy SecureDrop login credentials

Users of SecureDrop Workstation must enter their username, passphrase and two-factor code to connect with the SecureDrop server. You can manage these passphrases using the KeePassXC password manager in the vault VM. If this laptop will be used by more than one journalist, we recommend that you shut down the vault VM now (using the Qube widget in the upper right panel), skip this section, and use a smartphone password manager instead.

In order to set up KeePassXC for easy use:

  • Add KeePassXC to the application menu by selecting it from the list of available apps in Q > Domain: vault > vault: Qube Settings > Applications and pressing the button labeled > (do not press the button labeled >>, which will add all applications to the menu).
  • Launch KeePassXC via Q > Domain: vault > vault: KeePassXC. When prompted to enable automatic updates, decline. vault is networkless, so the built-in update check will fail; the app will be updated through system updates instead.
  • Close the application.

Important

The Admin Workstation password database contains sensitive credentials not required by journalist users. Make sure to copy the credentials from the Journalist Workstation USB.

In order to copy a journalist’s login credentials:

  • If a Journalist Workstation USB is not currently attached, connect it, attach it to the vault VM, open it in the file manager, and enter its encryption passphrase.
  • Locate the password database. It should be in the Persistent directory, and will typically be named keepassx.kdbx or similar.
  • Open a second vault file manager window (Ctrl + N in the current window) and navigate to the Home directory.
  • Drag and drop the password database to copy it.
  • In the vault file manager, select + Other Locations and eject the TailsData volume, then disconnect the Journalist Workstation USB. Close this file manager window.
  • In the file manager window that displays the home directory, open the copy you made of the password database by double-clicking it.
  • If the database is passwordless, KeePassXC may display a security warning when opening it. To preserve convenient passwordless access, you can protect the database using a key file, via Database > Database settings > Security > Add additional protection > Add Key File > Generate. This key file has to be selected when you open the database, but KeePassXC will remember the last selection.
  • Inspect each section of the password database to ensure that it contains only the information required by the journalist user to log in.
  • Close the application window and shut down the vault VM (using the Qube widget in the upper right panel).

Download and install SecureDrop Workstation

With the key and configuration available in dom0, you’re ready to set up SecureDrop Workstation:

  • First, re-enable the network connection using the network manager widget.
  • Next, start a terminal in the network-attached work VM, via Q > Domain:work > work: Terminal.

Note

As the next steps include commands that must be typed exactly, you may want to open a browser in the work VM, open this documentation there, and copy-and-paste the commands below into your work terminal. Note that due to Qubes’ default security settings you will not be able to paste commands into your dom0 terminal. The work browser can be opened via Q > Domain: work > work: Firefox

  • In the work terminal, run the following commands to download and add the SecureDrop signing key, which is needed to verify the SecureDrop Workstation package:

    gpg --keyserver hkps://keys.openpgp.org --recv-key \
      "2224 5C81 E3BA EB41 38B3 6061 310F 5612 00F4 AD77"
    
    gpg --armor --export 22245C81E3BAEB4138B36061310F561200F4AD77 \
      > securedrop-release-key.pub
    
    sudo rpmkeys --import securedrop-release-key.pub
    
  • In the work terminal, open a text editor with escalated privileges (for example, with the command sudo gedit) and create a file /etc/yum.repos.d/securedrop-temp.repo with the following contents:

    [securedrop-workstation-temporary]
    enabled=1
    baseurl=https://yum.securedrop.org/workstation/dom0/f25
    name=SecureDrop Workstation Qubes initial install bootstrap
    
  • Download the SecureDrop Workstation config package to the curent working directory with the command:

    dnf download securedrop-workstation-dom0-config
    

    Note the release version number in the filename, you’ll need it below.

  • Verify the package with the following command:

    rpm -Kv securedrop-workstation-dom0-config-<versionNumber>-1.fc25.noarch.rpm
    

    where <versionNumber> is the release version number you noted above. The command output should match the following text:

    securedrop-workstation-dom0-config-<versionNumber>-1.fc25.noarch.rpm:
      Header V4 RSA/SHA256 Signature, key ID 00f4ad77: OK
      Header SHA1 digest: OK
      V4 RSA/SHA256 Signature, key ID 00f4ad77: OK
      MD5 digest: OK
    
  • If the package verification was successful, in the dom0 terminal, run the following command to transfer the RPM package to dom0:

    qvm-run --pass-io work \
      "cat /home/user/securedrop-workstation-dom0-config-<versionNumber>-1.fc25.noarch.rpm" \
      > securedrop-workstation.rpm
    
  • Verify that the RPM was transferred correctly by running the following commands:

    • in the work terminal:

      sha256sum securedrop-workstation-dom0-config-<versionNumber>-1.fc25.noarch.rpm
      
    • in the dom0 terminal:

      sha256sum securedrop-workstation.rpm
      

    If the hash output for both files matches, the RPM was transferred successfully.

  • Install the RPM using the following command in the dom0 terminal:

    sudo dnf install securedrop-workstation.rpm
    

    When prompted, type Y and Enter to install the package.

  • Shut down the work VM using the Qube widget in the top-right panel.

Configure SecureDrop Workstation (estimated wait time: 60-90 minutes)

Before setting up the set of VMs used by SecureDrop Workstation, you must configure the Journalist Interface connection and submission key.

  • To add the submission key, run the following command in the dom0 terminal:

    sudo cp /tmp/sd-journalist.sec /usr/share/securedrop-workstation-dom0-config/
    
  • Your submission key has a unique fingerprint required for the configuration. Obtain the fingerprint by using this command:

    gpg --with-fingerprint --with-colons /tmp/sd-journalist.sec
    

    The fingerprint will be on a line that starts with fpr. For example, if the output included the line fpr:::::::::65A1B5FF195B56353CC63DFFCC40EF1228271441:, the fingerprint would be the character sequence 65A1B5FF195B56353CC63DFFCC40EF1228271441.

  • Next, create the SecureDrop Workstation configuration file:

    cd /usr/share/securedrop-workstation-dom0-config
    sudo cp config.json.example config.json
    
  • The config.json file must be updated with the correct values for your instance. Open it with root privileges in a text editor such as vi or nano and update the following fields’ values:

    • submission_key_fpr: use the value of the submission key fingerprint as displayed above
    • hidserv.hostname: use the hostname of the Journalist Interface, including the .onion TLD
    • hidserv.key: use the value of the v2 HidServAuth token for the Journalist Interface, or the v3 private authorization key value if your SecureDrop instance uses v3 onion services
    • environment: use the value prod

Note

You can find the values for the hidserv.* fields in the /tmp/journalist.txt file that you created in dom0 earlier:

If your instance uses v2 onion services, the file will be formatted as follows:

HidServAuth ONIONADDRESS.onion AUTHTOKEN # comments, can be ignored

If your instance uses v3 onion services, the file will be formatted as follows:

ONIONADDRESS:descriptor:x25519:AUTHTOKEN
  • Verify that the configuration is valid using the command below in the dom0 terminal:

    securedrop-admin --validate
    
  • Finally, in the dom0 terminal, run the command:

    securedrop-admin --apply
    

This command will take a considerable amount of time and approximately 4GB of bandwidth, as it sets up multiple VMs and installs supporting packages. When it completes, your SecureDrop Workstation is finally ready to use!

Test the Workstation

To start the SecureDrop Client, double-click the SecureDrop desktop icon that was set up by the previous command. The preflight updater will start and check for updates. The system should be up-to-date and no updates should be required, but if updates are available follow the instructions in the preflight updater to apply them.

Once the update check is complete, the SecureDrop Client will launch. Log in using an existing journalist account and verify that sources are listed and submissions can be downloaded, decrypted, and viewed.

Enable password copy and paste

If you use KeePassXC in the vault VM to manage login credentials, you can enable the user to copy passwords to the SecureDrop Client using inter-VM copy and paste. While this is relatively safe, we recommend reviewing the section Managing Clipboard Access of this guide, which goes into further detail on the security considerations for inter-VM copy and paste.

The password manager runs in the networkless vault VM, and the SecureDrop Client runs in the sd-app VM. To permit this one-directional clipboard use, issue the following command in dom0:

qvm-tags vault add sd-send-app-clipboard

Confirm that the tag was correctly applied using the ls subcommand:

qvm-tags vault ls

To revoke this configuration change later or correct a typo, you can use the del subcommand, e.g.:

qvm-tags vault del sd-send-app-clipboard

Troubleshooting installation errors

“Recurse failed: none of the specified sources were found”

An error similar to the following may be displayed during the installation, after which the installation will fail:

______ID: dom0-securedrop-launcher-directory
Function: file.recurse
    Name: /opt/securedrop/launcher
  Result: False
 Comment: Recurse failed: none of the specified sources were found
 Started: 20:52:46.766870
Duration: 2.371 ms
 Changes:

To clear this error, clear the Salt cache and resynchronize by running the following commands in a dom0 terminal:

sudo rm -rf /var/cache/salt
sudo qubesctl saltutil.sync_all refresh=true

Then, run securedrop-admin --apply again.

“Failed to return clean data”

An error similar to the following may be displayed during an installation or update:

sd-log:
      ----------
      _error:
          Failed to return clean data
      retcode:
          None
      stderr:
      stdout:
          deploy

This is a transient error that may affect any of the SecureDrop Workstation VMs. To clear it, run the installation command or update again.

“Temporary failure resolving”

Transient network issues may cause an installation to fail. To work around this, verify that you have a working Internet connection, and re-run the securedrop-admin --apply command.

Uninstalling SecureDrop Workstation

To uninstall SecureDrop Workstation, open a dom0 terminal and run the following command:

securedrop-admin --uninstall

This will remove all associated VMs and configuration details, and uninstall the dom0 SecureDrop Workstation package.

The submission key and config.json file will still be present in dom0 in /usr/share/securedrop-workstation-dom0-config. To delete them, use the command:

sudo shred /usr/share/securedrop-workstation-dom0-config/{config.json,sd-journalist.sec}