Installing and Configuring SecureDrop Workstation
Warning
SecureDrop Workstation is currently in a closed beta, and we do not recommend installing it for production purposes independently. 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:
Rotate legacy passphrases (for pre-2018 installations)
Apply BIOS updates and check settings
Download and verify Qubes OS
Install Qubes OS
(Hardware-dependent) Apply USB fixes
Apply updates to system templates
Install tasks:
Copy the submission key
Copy Journalist Interface details
Copy SecureDrop login credentials
Download and install SecureDrop Workstation
Configure SecureDrop Workstation
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 T480, T490 and T14 - 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
Rotate legacy passphrases
To ensure that all passphrases meet the security requirements of the system, you must rotate the passphrases of any Journalist Interface users whose accounts were set up on or before September 12, 2017.
To verify when users were added to the system:
Log into the Journalist Interface with an admin account.
Click the Admin link in the top right.
Review the Created column in the list of users.
To rotate passphrases for accounts, please see the instructions in the SecureDrop Admin Guide.
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 one of the recommended ThinkPad T-series models, see the section on Lenovo T series laptops. 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 unnecessary network options such as Wake-on-LAN and UEFI network stacks.
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 Qubes OS ISO for version 4.1.2
from https://www.qubes-os.org/downloads/. The ISO is 5.4 GiB 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.1.2-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 your 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.
After the disk is unlocked and Qubes starts, you will be prompted to complete the initial setup. Click the Qubes OS icon.
On the configuration screen, ensure that the following options are checked:
“Create default system qubes (sys-net, sys-firewall, default DispVM)”
“Make sys-firewall and sys-usb disposable”
If there is a grayed out option “USB qube configuration disabled”, make a note of this. An additional setup step will be required (see next section).
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.
(Hardware-dependent) Apply USB fixes
If, during the installation, you encountered the grayed out option “USB qube configuration disabled”, you must now create a VM to access your USB devices. If you did not encounter this issue, you can skip this section.
To create a USB qube, open a dom0
terminal via the Qubes menu (the Q icon in the upper left corner): Q > Terminal Emulator. Run the following command:
sudo qubesctl state.sls qvm.sys-usb
After the command exits, confirm that you see an entry “Service: sys-usb” in the Qubes menu. If sys-usb
is not running, you can start it with the command qvm-start sys-usb
in dom0
. Once sys-usb
is running, click the devices widget in the upper right panel to expand a listing of all devices detected by Qubes OS.
Now, insert a safe USB device you intend to use with the SecureDrop Workstation. Click the devices widget again. Does the newly attached USB device appear in the list? If so, USB support is working and you can proceed with the installation. If you do encounter the error message “Denied qubes.InputKeyboard from sys-usb to dom0”, you need to additionally enable USB keyboard support:
sudo qubesctl state.sls qvm.usb-keyboard
While we recommend against the use of a USB keyboard for security reasons, this error can also occur in combination with other USB devices on some hardware.
Apply dom0
updates (estimated wait time: 15-30 minutes)
dom0
is the most trusted domain on Qubes OS, and has privileged access to all other VMs. As such, it is important to ensure that all available security updates have been applied to dom0
as the first step after the installation.
After logging in, use the network manager widget in the upper-right panel to configure your network connection.
Open a dom0
terminal via the Qubes menu (the Q icon in the upper left corner): Q > Terminal Emulator. Run the following command:
sudo qubes-dom0-update -y
Wait for all updates to complete. If you encounter an error during this stage, please contact us for assistance, as it may not be safe to proceed with the installation.
After updating dom0
, reboot the workstation to ensure that all updates have taken effect for your active session.
Apply updates to system templates (estimated wait time: 45-60 minutes)
After logging in again, confirm that the network manager successfully connects you to the configured network. If necessary, verify the network settings using the network manager widget.
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 > Qubes Tools > Qubes Update to update the system VMs. in the
[Dom0] Qubes Updater
window, first checkEnable updates for qubes without known available updates
, then check all entries in the list above except for dom0 (which you have already updated in the previous step). Then, click Next. The system’s VMs will be updated sequentially - this may take some time. When the updates are complete, click Finish.
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, labeledTails
, 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 namedN GB encrypted
, where N is the size of the persistent volume. Enter the SVS persistent volume passphrase to unlock and mount it.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, labeledTails
, 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
Verify that the
/tmp/journalist.txt
file ondom0
contains valid configuration information using the commandcat /tmp/journalist.txt
in thedom0
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 namedkeepassx.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 \ "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3" gpg --armor --export 2359E6538C0613E652955E6C188EDD3B7B22E6A3 \ > 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 commandsudo nano
) 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/f32 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. During the download, you may be prompted to confirm importing the Qubes OS Release 4 Signing Key. You can safely do so; it will not be used during the subsequent steps.
Verify the package with the following command:
rpm -Kv securedrop-workstation-dom0-config-<versionNumber>-1.fc32.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.fc32.noarch.rpm: Header V4 RSA/SHA512 Signature, key ID 7b22e6a3: OK Header SHA256 digest: OK Header SHA1 digest: OK Payload SHA256 digest: OK V4 RSA/SHA512 Signature, key ID 7b22e6a3: 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.fc32.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.fc32.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-colons --import-options import-show --dry-run --import /tmp/sd-journalist.sec
The fingerprint will be on a line that starts with
fpr
. For example, if the output included the linefpr:::::::::65A1B5FF195B56353CC63DFFCC40EF1228271441:
, the fingerprint would be the character sequence65A1B5FF195B56353CC63DFFCC40EF1228271441
.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 asvi
ornano
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
TLDhidserv.key: use the private v3 onion service authorization key value
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.
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:sdw-admin --validate
Configure infinite scrollback for your terminal via Edit > Preferences > General > Unlimited scrollback. This helps to ensure that you will be able to review any error output printed to the terminal during the installation.
Finally, in the
dom0
terminal, run the command:sdw-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 the command finishes, reboot the machine to complete the installation. 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
“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 sdw-admin --apply
command.
Uninstalling SecureDrop Workstation
To uninstall SecureDrop Workstation, open a dom0
terminal and run the following command:
sdw-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}
Getting Support
If you are part of the SecureDrop Workstation Pilot and you have questions about this process or about any other aspect of SecureDrop Workstation, please reach out to us.