Docs for post-install configuration, clipboard access, logs

Explains in detail how to set up a password manager, and how
to configure tags for clipboard usage and logs.

Depends on changes introduced in
freedomofpress/securedrop-workstation#533

docs/admin/install.rst

@@ -162,6 +162,8 @@ 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:
+
 Copy Journalist Interface details
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -338,9 +340,75 @@ 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.
+
+Post-Install Configuration
+--------------------------
+Once you have verified that you can log into the SecureDrop Client, you may want to consider making additional configuration changes:
+
+- setting up password management
+- enabling selected clipboard usage, if appropriate
+- enabling copying of system logs to a networked VM.
+
+By default, copy and paste is fully disabled for all SecureDrop Workstation VMs. Copying files from or to SecureDrop VMs using ``qvm-copy`` is also disabled.
+
+.. _Password Management Section:
+
+Password management
+~~~~~~~~~~~~~~~~~~~
+If you have installed Qubes with the default configuration, you should have a VM called ``vault``, which is a networkless VM based on the ``fedora-30`` template. You can use this VM to store SecureDrop login credentials or the passphrases for encrypted export USB drives.
+
+Note that all users of this workstation will have access to the password database. If the workstation will be used by more than one journalist, you may want to encourage the use of a smartphone password manager for managing individual login credentials.
+
+The ``fedora-30`` template includes the KeePassXC password manager. It is not listed in the application menu for ``vault`` by default; you can add it by selecting it from the list of available apps in **Q > Domain: vault > Qube Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
+
+After confirming this change, you can launch KeePassXC from the **Domain: vault** menu. On first start, it will suggest enabling automatic updates, which you should decline: ``vault`` is networkless, so the built-in update check will fail; the app will be updated through system updates instead.
+
+You can now choose between creating a new password database or importing an existing one.
+
+..  important::
+
+    If you import an existing database, make sure you import only the passwords you need. The password database stored on the *Admin Workstation* USB is intended to hold credentials required for the *administration* of the SecureDrop servers, which journalist users should not have access to. In contrast, a *Journalist Workstation* USB is intended to only hold the SecureDrop login credentials for a given journalist user of the system.
+
+    We recommend reviewing each section of the password database before giving other users access to the workstation.
+
+To import an existing database, attach the required USB drive (typically a *Journalist Workstation* USB) to the ``vault`` VM, similar to the process described in :ref:`copy_journalist`. You can use the file manager (**Q > Domain: vault > Files**) to unlock the USB drive and copy the password database (typically a file like ``keepass.kdbx`` in the directory ``Persistent``) to your user directory, and then detach the USB drive.
+
+When importing a passwordless database, KeePassXC may warn you every time about opening the database without a password. Similarly, when creating a new password database, KeePassXC will prompt you to protect it with a password, and will refuse to accept a blank password.
+
+If you want to configure easy access to the password database, you can protect the database using a key file, via **Add additional protection > Add Key File > Generate** on the final screen. Once you have configured a key file, KeePassXC will accept leaving the master password field blank.
+
+Clipboard configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+Qubes supports copying the clipboard contents from one VM to another using `special keyboard shortcuts <https://www.qubes-os.org/doc/copy-paste/>`_. It also permits configuring the access policies for each VM's clipboard. By default, cross-VM clipboard copying is completely disabled for all VMs created as part of the installation (the ones that start with ``sd-``) for security reasons.
+
+..  important::
+
+    Before changing the clipboard configuration, we recommend reviewing the section :doc:`Managing Clipboard Access <managing_clipboard>` of this guide, which goes into further detail on the security considerations.
+
+If you did set up a password manager in the previous step, you may want to enable copying passwords from KeePassXC to the SecureDrop Client. 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
+
+  qvm-tags vault add sd-send-app-clipboard
+
+We recommend confirming that the tag was correctly applied using the ``ls`` subcommand:
+
+.. code-block:: sh
+
+  qvm-tags vault ls
+
+To remove the permission, use:
+
+.. code-block:: sh
+
+  qvm-tags vault del sd-send-app-clipboard
+
+As before, we recommend using the ``ls`` subcommand to confirm that changes were applied successfully.
 
-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.
+All policy changes take effect immediately.
 
 Troubleshooting installation errors
 -----------------------------------

docs/admin/managing_clipboard.rst

@@ -0,0 +1,64 @@
+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 wanted to create a boilerplate "Thank you" message for replies to sources, you could create a textfile in the ``sd-app`` VM and copy its contents to the SecureDrop Client using ``Ctrl+C`` (copy) and ``Ctrl+V`` (paste) keyboard shortcuts.
+
+Qubes also 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.
+
+Configuring clipboard access to ``sd-app``
+------------------------------------------
+
+The process for setting up a password manager and permitting the one-directional copying of passwords 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 is 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>
+
+We recommend confirming 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, we recommend confirming 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-clipboard
+  qvm-tags work-signal ls

docs/admin/reviewing_logs.rst

@@ -0,0 +1,36 @@
+Reviewing and exporting logs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SecureDrop Workstation aggregates system logs from all its VMs in the ``sd-log`` VM, in the folder ``~/QubesIncomingLogs``, with one subfolder for each VM. Please note that while the logs do not include original filenames or message contents, they do contain sensitive information, e.g.:
+
+- timing and usage information related to SecureDrop access
+- the two-word designation for a given source
+- metadata about submissions and replies
+- error messages that disclose further details
+
+For this reason, the ``sd-log`` VM is networkless, and you cannot copy files from ``sd-log`` to other VMs by default.
+
+If you want to selectively enable copying logs to a single VM, you can use tags, similar to the method used for :doc:`managing clipboard access <managing_clipboard>`. You can add and remove the permission just before each copying operation; the change will take effect immediately.
+
+.. important::
+
+   Before copying logs to a networked VM, we recommend carefully inspecting them for sensitive information, and potentially redacting them
+
+To enable copying logs to a target VM, you can use a command like the following in ``dom0``, substituting ``<VM name>`` with the name of the target VM (e.g., ``work``):
+
+.. code-block:: sh
+
+  qvm-tags <VM name> add sd-receive-logs
+
+We recommend verifying that the tag was successfully applied using the ``ls`` subcommand:
+
+.. code-block:: sh
+
+  qvm-tags <VM name> ls
+
+To remove the permission, use this command in ``dom0``:
+
+.. code-block:: sh
+
+  qvm-tags <VM name> del sd-receive-logs
+
+With the permission in effect, you can use the command ``qvm-copy`` in a terminal in ``sd-log`` to copy individual files to the target VM.

docs/index.rst

@@ -29,10 +29,12 @@ against malware and other security risks. It is built on Qubes OS and requires a
 .. toctree::
    :maxdepth: 2
    :caption: Guide for Administrators
- 
+
    admin/hardware
    admin/install
    admin/securing_workstation
+   admin/managing_clipboard
+   admin/reviewing_logs
    admin/troubleshooting_connection
    admin/provisioning_usb
    admin/known_issues

docs/journalist/faq.rst

@@ -139,16 +139,17 @@ without opening it in an interactive viewer application.
 
 Why can't I copy and paste?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the current version, copy and paste between and to SecureDrop Workstation VMs
-is disabled for security reasons. The goal of this restriction is to minimize
-the risk of accidental pastes of sensitive content, and to reduce the attack
-surface for attempts to exfiltrate information.
+You should be able to copy and paste *within* any VM on the system, e.g.,
+from one application running in ``sd-app`` to another.
 
-We recommend entering passwords and passphrases manually, and using the provided
-print and export functionality for submissions.
+Copy and paste between and to SecureDrop Workstation VMs is disabled for security
+reasons. The goal of this restriction is to minimize the risk of accidental
+pastes of sensitive content, and to reduce the attack surface for attempts to
+exfiltrate information.
 
-It is possible to copy and paste from ``dom0`` into SecureDrop Workstation VMs,
-but we do not recommend doing so in production environments.
+Administrators can configure limited exceptions to this policy; please see the
+section :doc:`Managing Clipboard Access <../admin/managing_clipboard>` of the admin guide
+for more information.
 
 Why does it take so long to start the SecureDrop Client?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~