Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add section about post-install config: passwords, clipboard & logs #35

Merged
merged 1 commit into from
Jun 1, 2020
Merged

Add section about post-install config: passwords, clipboard & logs #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 85 additions & 18 deletions docs/admin/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ Install tasks:
~~~~~~~~~~~~~~

#. Copy the submission key
#. Copy Journalist Interface details
#. Copy *Journalist Interface* details
#. Copy SecureDrop login credentials
#. Download and install SecureDrop Workstation
#. Configure SecureDrop Workstation
#. Test the Workstation
Expand All @@ -36,7 +37,10 @@ In order to install SecureDrop Workstation and configure it to use an existing S

.. 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.
- 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.
Expand All @@ -51,9 +55,9 @@ 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:
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.
- 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:

Expand All @@ -70,9 +74,9 @@ In order to be used with SecureDrop Workstation, your instance must be running t

- 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 <https://docs.securedrop.org>`_.
- Update the *Admin Workstation* to the current SecureDrop release version, by following the applicable upgrade guide in `our documentation <https://docs.securedrop.org>`_.
- Back up the SecureDrop instance, using the `server backup <https://docs.securedrop.org/en/master/backup_and_restore.html>`_ 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.
- 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.
Expand Down Expand Up @@ -203,16 +207,20 @@ In order to decrypt submissions, your SecureDrop Workstation will need a copy of
- In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the SVS USB.


Copy Journalist Interface details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _copy_journalist:

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:
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:

- Connect the Admin Workstation 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.
- 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.

- 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 Admin Workstation persistent volume passphrase to unlock and mount it.
- 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.

- Copy the Journalist Interface configuration file to ``dom0``. If your SecureDrop instance uses v3 onion services, use the following command:
- 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:

.. code-block:: sh

Expand All @@ -230,8 +238,43 @@ SecureDrop Workstation connects to your SecureDrop instance's API via the Journa

- Verify that the ``/tmp/journalist.txt`` file on ``dom0`` contains valid configuration information using the command ``cat /tmp/journalist.txt`` in the ``dom0`` terminal.

- In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the Admin Workstation USB. Shut down the ``vault`` VM using the Qube widget in the upper right panel.
- 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -327,7 +370,7 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec
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.
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:

Expand All @@ -353,8 +396,8 @@ Before setting up the set of VMs used by SecureDrop Workstation, you must config
- 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
- **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::
Expand Down Expand Up @@ -389,9 +432,33 @@ This command will take a considerable amount of time and approximately 4GB of ba
Test the Workstation
~~~~~~~~~~~~~~~~~~~~

To start the SecureDrop Workstation 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.
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.

.. _Password Management Section:

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 :doc:`Managing Clipboard Access <managing_clipboard>` 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``:

.. code-block:: sh
zenmonkeykstop marked this conversation as resolved.
Show resolved Hide resolved

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

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

.. code-block:: sh

qvm-tags vault ls

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

.. code-block:: sh

Once the update check is complete, the client will launch. Log in using an existing journalist account and verify that sources are listed and submissions can be downloaded, decrypted, and viewed.
qvm-tags vault del sd-send-app-clipboard

Troubleshooting installation errors
-----------------------------------
Expand Down
71 changes: 71 additions & 0 deletions docs/admin/managing_clipboard.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
Managing Clipboard Access
=========================

.. include:: ../includes/top-warning.rst

Every VM in Qubes has its own clipboard, similar to the clipboard of a Mac, Windows or Linux computer. For example, if you used the default ``work`` VM to browse the web and wanted to copy text from one browser window to another, you would use the ``Ctrl+C`` and ``Ctrl+V`` keyboard shortcuts to copy and paste. This type of clipboard usage -- copy and paste in the same VM -- also works in all VMs that are part of SecureDrop Workstation.

In addition, Qubes supports copying information *between* VMs. This is done by using `special keyboard shortcuts <https://www.qubes-os.org/doc/copy-paste/>`_, ``Ctrl+Shift+C`` and ``Ctrl+Shift+V``, in a four-step process. By default, this is disabled for all VMs that are part of SecureDrop Workstation, consistent with the `principle of least privilege <https://en.wikipedia.org/wiki/Principle_of_least_privilege>`__.

As an administrator, you should be aware of the following risks related to clipboard access before changing the default configuration:

1. It is dangerous to copy untrusted, unsanitized content *into* a secure environment. What looks like plain text may contain character sequences that exploit security vulnerabilities in the target environment.
2. The four-step process described above can be difficult to follow, and it is easy to make an operational mistake, such as pasting a password into a message to a source, or into a window belonging to a VM with network access.
3. Like any other part of the operating system, the implementation of Qubes clipboard itself may contain undiscovered security vulnerabilities that an adversary could exploit in an attempt to exfiltrate information.

With these considerations in mind, there are use cases where clipboard access may be an important part of your regular use of SecureDrop Workstation. For example:

- You may want to copy passwords from a password manager to the SecureDrop Client;
- You may want to copy a message you received via SecureDrop into a secure messaging app like Signal, to share it with another journalist.

To support these use cases, SecureDrop Workstation allows you to grant granular access to the ``sd-app`` clipboard (via the cross-VM clipboard) to selected VMs.
eloquence marked this conversation as resolved.
Show resolved Hide resolved

Configuring clipboard access to ``sd-app``
eloquence marked this conversation as resolved.
Show resolved Hide resolved
------------------------------------------

The process for permitting the one-directional copying of passwords from a password manager in ``vault`` to the SecureDrop Client is :ref:`outlined in the installation docs <Password Management Section>`. In general, clipboard access to SecureDrop Workstation VMs is governed by *tags* that can be applied in ``dom0`` to selected VMs:

- the tag ``sd-send-app-clipboard`` can be used to tag a VM that should be able to send its clipboard contents *to* ``sd-app`` via the cross-VM clipboard;
- the tag ``sd-receive-app-clipboard`` can be used to tag a VM that should be able to receive its clipboard contents *from* ``sd-app`` via the cross-VM clipboard.

You can configure these tags for a given VM from the ``dom0`` terminal. Changes to tags take effect immediately, and any VM can have multiple tags.

.. important::

Make sure you fully understand technical and operational security risks before permitting clipboard access to any VM. The "send" and "receive" tags are separate so you can set up only the clipboard direction you need to support a given use case.

We recommend adding a note about any changes to the clipboard configuration to your internal documentation for SecureDrop. If you are unsure how to configure the clipboard to support a specific use case, please do not hesitate to contact us for assistance.

The general syntax for adding a tag is as follows, substituting ``<VM name>`` with the name of an existing VM in the system you want to grant access to the clipboard:

.. code-block:: sh

qvm-tags <VM name> add <tag name>

Confirm that the command was successfully applied using the ``ls`` subcommand:

.. code-block:: sh

qvm-tags <VM name> ls

The syntax for revoking a tag is as follows:

.. code-block:: sh

qvm-tags <VM name> del <tag name>

As before, confirm the operation via the ``ls`` subcommand.

As an example, if you had a custom VM called ``work-signal`` that runs the Signal messenger, and you wanted to copy and paste messages from the SecureDrop Client *into* Signal (and potentially other applications in that VM) but not *out* of Signal into the SecureDrop Client, you would issue the following commands:

.. code-block:: sh

qvm-tags work-signal add sd-receive-app-clipboard
qvm-tags work-signal ls

To review current clipboard permissions, you can use ``qvm-ls`` to print out a list of VMs that can receive or send clipboard contents:

.. code-block:: sh

qvm-ls --tags sd-receive-app-clipboard
qvm-ls --tags sd-send-app-clipboard
Loading