Address several review comments; other tweaks

- Instruct user to copy password database earlier in the process
- Shorten password-related instructions to be more task focused
- Reduce "We recommend" usage a bit
- Introduce use of qvm-ls
- Formatting change; correct one tag name

docs/admin/install.rst

@@ -22,6 +22,7 @@ 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
@@ -37,6 +38,9 @@ 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 Journalist Workstation USB for the intended user of this workstation, if you intend to use the password manager on SecureDrop Workstation.
+- 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.
@@ -232,8 +236,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.
+- In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the Admin Workstation USB.
+
+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 > Qube Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
+
+- Launch KeePassXC from the **Domain: vault** menu. 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:
 
+- Connect the *Journalist Workstation* USB, attach it to the ``vault`` VM, and open it in the file manager, and enter the passphrase for this specific *Journalist Workstation* USB drive.
+
+- 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. Shut down the ``vault`` VM using the Qube widget in the upper right panel.
+
+- Open the database in the home directory by double-clicking it in the file manager.
+
+- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -395,73 +434,29 @@ To start the SecureDrop Client, double-click the SecureDrop desktop icon that wa
 
 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-31`` 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-31`` 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`. Note that you may have to detach the USB drive from the ``sd-devices`` VM, first, which will attempt to automatically attach USB storage devices and printers for use by SecureDrop Workstation.
+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.
 
-Once the USB drive is attached to ``vault``, 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``:
+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
+   qvm-tags vault add sd-send-app-clipboard
 
-We recommend confirming that the tag was correctly applied using the ``ls`` subcommand:
+Confirm that the tag was correctly applied using the ``ls`` subcommand:
 
 .. code-block:: sh
 
-  qvm-tags vault ls
+   qvm-tags vault ls
 
-To remove the permission, use:
+To revoke this configuration change later or correct a typo, you can use the ``del`` subcommand, e.g.:
 
 .. 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.
-
-All policy changes take effect immediately.
+   qvm-tags vault del sd-send-app-clipboard
 
 Troubleshooting installation errors
 -----------------------------------

docs/admin/managing_clipboard.rst

@@ -23,10 +23,10 @@ To support these use cases, SecureDrop Workstation allows you to grant granular
 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 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 is clipboard contents *from* ``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.
 
@@ -40,25 +40,32 @@ The general syntax for adding a tag is as follows, substituting ``<VM name>`` wi
 
 .. code-block:: sh
 
-  qvm-tags <VM name> add <tag name>
+   qvm-tags <VM name> add <tag name>
 
-We recommend confirming that the command was successfully applied using the ``ls`` subcommand:
+Confirm that the command was successfully applied using the ``ls`` subcommand:
 
 .. code-block:: sh
 
-  qvm-tags <VM name> ls
+   qvm-tags <VM name> ls
 
 The syntax for revoking a tag is as follows:
 
 .. code-block:: sh
 
-  qvm-tags <VM name> del <tag name>
+   qvm-tags <VM name> del <tag name>
 
-As before, we recommend confirming the operation via the ``ls`` subcommand.
+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-clipboard
-  qvm-tags work-signal ls
+   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

docs/admin/reviewing_logs.rst

@@ -1,6 +1,8 @@
 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.:
+SecureDrop Workstation aggregates system logs from all its VMs in the ``sd-log`` VM, in the folder ``~/QubesIncomingLogs``, with one subfolder for each VM. You can inspect these logs directly in the ``sd-log`` VM, or you can copy them to another VM, e.g., for purposes of sharing logs with the SecureDrop development team.
+
+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
@@ -19,24 +21,30 @@ To enable copying logs to a target VM, you can use a command like the following
 
 .. code-block:: sh
 
-  qvm-tags <VM name> add sd-receive-logs
+   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
+   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
+   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. For example, to copy a file ``syslog-redacted.log``, you would use this command:
 
 .. code-block:: sh
 
-  qvm-copy syslog-redacted.log
+   qvm-copy syslog-redacted.log
 
 A graphical prompt will permit you to select any target VM that has the ``sd-receive-logs`` tag. Once successfully copied, the file can be found in the directory ``~/QubesIncoming/sd-log`` in the target VM. See the `Qubes OS documentation on copying files <https://www.qubes-os.org/doc/copying-files/>`__ for more information.
+
+To review current copy permissions, you can use ``qvm-ls`` to print out a list of VMs that can receive files from ``sd-log``:
+
+.. code-block:: sh
+
+   qvm-ls --tags sd-receive-logs