Merge pull request #17 from freedomofpress/copyedit-and-misc-updates

Full copyedit & updates pass

docs/admin/known_issues.rst

@@ -5,26 +5,31 @@ Limitations and known issues
 Reporting issues
 ----------------
 
-For the duration of the pilot, bugs and other issues found in 
-*SecureDrop Workstation* should be reported by pilot participants via the 
+For the duration of the pilot, bugs and other issues found in
+*SecureDrop Workstation* should be reported by pilot participants via the
 `support portal <https://support.freedom.press>`_. Issues that are not instance-
-specific will be added to the appropriate public issue tracker by the developers, 
+specific will be added to the appropriate public issue tracker by the developers,
 for example:
 
  - `SecureDrop Workstation issues <https://github.com/freedomofpress/securedrop-workstation/issues>`_ - issues related to the Qubes environment and workstation provisioning.
  - `SecureDrop Client issues <https://github.com/freedomofpress/securedrop-client/issues>`_ - issues related to the *SecureDrop Client*.
 
- - `SecureDrop Export issues <https://github.com/freedomofpress/securedrop-export/issues>`_ - issues related to printing and exporting submissions. 
+ - `SecureDrop Export issues <https://github.com/freedomofpress/securedrop-export/issues>`_ - issues related to printing and exporting submissions.
 
 Current known issues
 --------------------
 
+- Updates are slow due to the number of VMs involved, and due to some updates
+  being fetched over Tor. We are investigating various strategies to improve
+  performance and reliability of the updater.
 - Currently, only LUKS-encrypted *Export Devices* are supported. VeraCrypt support
   will be added in a future release.
 - Printer support is limited to specific models by Brother and HP. Support for
   more non-networked printers will be added in a future release.
-- "Flag for reply" functionality, used when a source's reply key was not created
-  on their first submission and needs to be created on their next visit, is not implemented
-  in the *SecureDrop Client*. If the reply feature for a source is disabled, they must be
-  flagged for reply in the *Journalist Interface* - see the 
-  `SecureDrop "Flag for Reply" documentation <https://docs.securedrop.org/en/stable/journalist.html#flag-for-reply>`_ for more information.
+- "Flag for reply" functionality is not implemented in the *SecureDrop Client*.
+  This is used when a source's reply key was not created on their first
+  submission and needs to be created on their next visit.
+  If you are logged into the SecureDrop Client, and the reply feature for a
+  source is disabled for more than a minute, they must be flagged for reply in
+  the *Journalist Interface* - see the `SecureDrop "Flag for Reply"
+  documentation <https://docs.securedrop.org/en/stable/journalist.html#flag-for-reply>`_ for more information.

docs/includes/top-warning.rst

@@ -1,2 +1,3 @@
-.. warning:: SecureDrop Workstation is in a limited beta phase, and is not 
-  recommended for general use at this time.
+.. warning:: SecureDrop Workstation is in a limited beta phase, and is not
+  recommended for general use at this time. See our `blog post <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os/>`__
+  for more information.

docs/index.rst

@@ -3,14 +3,15 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to SecureDrop Workstation's documentation!
-==================================================
+Welcome to the SecureDrop Workstation documentation!
+====================================================
 
 .. include:: includes/top-warning.rst
 
-SecureDrop Workstation is an application built on Qubes OS, that can be used in
-conjunction with SecureDrop to communicate with anonymous sources and manage
-submitted documents with a reasonable level of security.
+SecureDrop Workstation is a tool to enable journalists to communicate with
+anonymous sources and manage submitted documents, while providing mitigations
+against malware and other security risks. It is built on Qubes OS and requires a
+`SecureDrop <https://www.securedrop.org/>`__ server setup.
 
 .. toctree::
    :maxdepth: 2

docs/journalist/faq.rst

@@ -58,30 +58,63 @@ For more about the security features of Qubes, see
 .. _`Xen hypervisor`: https://wiki.xen.org/wiki/Xen_Project_Software_Overview
 .. _`the Qubes OS documentation`: https://www.qubes-os.org/faq/#general--security
 
-How secure is Qubes? How does the security of this system compare to using an air-gapped Secure Viewing Station?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-[This section is a stub]
-  - Audits
-  - grsec
-  - Qubes OS team
-  - Our security team
-  - Discuss Xen
-  - Discuss benefits of avoiding systems where security responsibility is on the user (opsec concerns)
+How does the security of this system compare to using an air-gapped Secure Viewing Station?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The air-gapped Secure Viewing Station that is part of a SecureDrop setup offers strong
+protections against exfiltration of submissions or encryption keys by adversaries. It lacks
+important protections that SecureDrop Workstation provides. On the other hand, vulnerabilities
+in Qubes OS or Xen Hypervisor may have a greater security impact than vulnerabilities
+in Tails, the operating system used on a Secure Viewing Station.
+
+A typical SVS USB drive may contain documents from multiple sources and always
+contains the highly sensitive private key needed to decrypt them. An adversary who does
+manage to achieve a security compromise (e.g., through a vulnerability in a file viewer
+application) can access these other files, and may be able to exfiltrate them.
+
+In spite of the air-gap, this may be possible through physical channels used to transfer files
+off the SVS (e.g., USB drives), or by motivating the journalist user to perform an
+unsafe action (e.g., `scanning a QR code <https://securedrop.org/news/security-advisory-do-not-scan-qr-codes-submitted-through-securedrop-connected-devices/>`__).
+
+Because the air-gapped SVS has no Internet access, updates can only be performed using
+another computer and a USB drive. In practice, newsrooms may not update their SVS
+in a timely manner, which can significantly worsen its security posture.
+
+In SecureDrop Workstation, any document received via SecureDrop is opened in a
+disposable VM that has no Internet access and no access to other files submitted
+via SecureDrop. The encryption keys are stored in a separate, networkless VM
+from the SecureDrop Client app.
+
+Because SecureDrop Workstation has Internet access, updates can be applied
+automatically as soon as they are available. SecureDrop Workstation enforces this
+by downloading and applying updates before the user logs into SecureDrop.
+
+SecureDrop Workstation uses hardware-assisted virtualization, which allows us
+to use custom kernels for its VMs. These custom kernels use the
+`grsecurity <https://grsecurity.net/>`__ patches which are also used on the
+SecureDrop servers, and provide additional mitigation against security
+vulnerabilities.
+
+An attacker able to exploit vulnerabilities in Qubes OS or Xen-based bare metal
+virtualization (likely in combination with other vulnerabilities, e.g., in a
+viewer application) may be able to exfiltrate information directly to the Internet.
+Qubes closely `tracks <https://www.qubes-os.org/security/xsa/>`__ any security
+vulnerabilities that may impact it, and the automatic update mechanism helps to
+ensure that, in the event of a vulnerability, every SecureDrop Workstation can be
+patched as quickly as possible.
 
 Can I install custom software on SecureDrop Workstation?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Right now, the pilot project is designed to make the journalist experience
 easier by combining the functionality of the Journalist Workstation and Secure
 Viewing Station. The main focus is making sure that checking SecureDrop is
-easier and faster. While we hope to add advanced tooling and document-
-processing options down the line, at this time we request that you leave the
-workstation configured the way it was provisioned, and hold off on installing
-additional software or changing the functionality or configuration of any of
-the VMs. If you have specific needs that you'd like to discuss with us, open an
-issue `in our support portal`_ or send us a `GPG-encrypted email`_ at
-support@freedom.press.
+easier and faster.
+
+While we hope to add advanced tooling and document-processing options down the line,
+at this time we request that you do not change the configuration of the workstation
+or install additional software on it. If you have specific needs that you would like
+to discuss with us, please open an issue `in our support portal`_ or send us a
+`GPG-encrypted email`_ at support@freedom.press.
 
 .. _`in our support portal`: https://support.freedom.press/
 .. _`GPG-encrypted email`: https://securedrop.org/sites/default/files/fpf-email.asc

docs/journalist/sources.rst

@@ -39,24 +39,26 @@ Sending a reply
 ---------------
 
 Compose a reply to the selected source in the text box at the bottom of the
-conversation view. You may send it, or leave it in the box without sending to
-save it as a draft.
+conversation view. Click the paper airplane icon or press "Ctrl+Enter" to send
+a reply. Any replies you did not send will be discarded when you exit the
+client.
 
 Sources without reply keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
+You may sometimes see the text "Awaiting encryption key from server" in a grayed
+out reply box for a source. This typically happens in the following situations:
 
-If the reply box for a source is grayed out, this means that you will be unable
-to reply to the source until they have logged in again. This is because system
-resource limitations prevented an encryption key from being generated for the
-source the first time they logged in, possibly due to a large number of sources
-trying to reach your server.
+- A source has just contacted your SecureDrop moments ago, and the server has
+  not created an encryption key yet. If you are logged in, the key will be
+  automatically fetched as soon as it becomes available, usually within a few
+  seconds. At that point, the reply box will become available.
 
-This limitation is scheduled to be fixed in a future version of SecureDrop.
-Until then, you can use the Journalist Interface to `flag sources for reply`_.
-See your SecureDrop administrator for assistance provisioning a *Journalist
-Workstation* USB if you do not have one already.
+- Your SecureDrop server is experiencing a surge of traffic, and the generation
+  of encryption keys has been temporarily disabled. You have to manually
+  `flag the source for reply`_, and the source has to log in again before you
+  can respond. This cannot currently be done from the SecureDrop Client.
 
-.. _`flag sources for reply`: https://docs.securedrop.org/en/release-1.2.0/journalist.html#flag-for-reply
+.. _`flag the source for reply`: https://docs.securedrop.org/en/stable/journalist.html#flag-for-reply
 
 Deleting a conversation
 -----------------------
@@ -67,4 +69,4 @@ righthand side of the application window, beside the timestamp, and clicking
 
 .. important:: Deleting a source conversation deletes the conversation for
    everyone at your organization, and also prevents the source from logging in
-   again using this codename.
+   again using their current codename.

docs/journalist/starting_client.rst

@@ -3,28 +3,30 @@ Starting the SecureDrop Client
 
 .. include:: ../includes/top-warning.rst
 
-Double-click on the **SecureDrop** desktop shortcut to launch the SecureDrop
-Client application.
+After you log into Qubes, the SecureDrop Client app will start automatically. If
+you have previously exited the application, you can double-click on the
+**SecureDrop** desktop shortcut to launch it.
 
 .. | screenshot_desktop-shortcut|
 
 Performing updates
 ------------------
 
 When you launch the application, it will first check for security
-updates. This can take several minutes.
+updates. This typically takes a few minutes.
 
 .. | screenshot_check_updates |
 
 If updates are found, you will be asked to apply them before launching the
-SecureDrop Client. You have the option of completing this now, or at another
-time. Keep in mind that updates are important to security, and you should apply
-them the same day you receive the notification.
+SecureDrop Client. For security reasons, you will not be able to launch the
+SecureDrop Client unless updates have been applied. If you prefer to shut down
+the machine or do other work in Qubes OS instead, you can cancel the update.
 
 .. important:: When you click "Apply Updates," allow the update
    process to complete fully, without closing or interrupting it, or you risk
-   breaking important system components. The update process may take some
-   time.
+   breaking important system components. The update process can take from just
+   a few minutes to 30 minutes or longer, depending on your network connection
+   and how many updates are available.
 
 .. | screenshot_apply_updates |
 
@@ -50,13 +52,9 @@ you click on a source submission.
 
 Troubleshooting tips
 ~~~~~~~~~~~~~~~~~~~~
-
-[This section is a stub]
- - Check your network connectivity if you are having issues with the updater or
-   with signing in.
- - You may want to refer to the Qubes documentation to understand the layout,
-   toolbars, and menu options you see in Qubes.
-
+If you have trouble running the updater or logging in, please contact your
+administrator. Our :doc:`network troubleshooting guide <../admin/troubleshooting_connection>`
+for administrators gives detailed steps for investigating connectivity issues.
 
 Working offline
 ---------------

docs/journalist/submissions.rst

@@ -15,8 +15,7 @@ To download a file, click the **Download** button.
 
 .. | screenshot_download_button |
 
-In the top left corner of the application window, you will see a message that
-the file is downloading.
+An animated spinner will indicate that the file is downloading:
 
 .. | screenshot_file_downloading |
 
@@ -28,7 +27,7 @@ Once the file has downloaded, the filename will be visible, as will the words
 Viewing
 -------
 
-To view a downloaded submission, double-click on the filename. This will open
+To view a downloaded submission, click its filename. This will open
 the file in a temporary environment, called a "disposable VM." The file you
 clicked on will open in a new window with a different colored border and a
 window title prefixed with "disp" (meaning disposable).
@@ -37,8 +36,8 @@ window title prefixed with "disp" (meaning disposable).
 
 This disposable VM is a special isolated environment similar to the *Secure
 Viewing Station*; it does not have internet access, and isolates the files that
-you are viewing from other sensitive files and applications on the SecureDrop
-Workstation.
+you are viewing from other sensitive files and applications on the same
+computer.
 
 Because this isolation is important to the security of your system, you will
 notice that certain tools that you may be used to have been disabled. For
@@ -56,24 +55,26 @@ Printing
 
 To print a document, click the **Print** button. Currently, printing is only
 supported with select printers from Brother and HP, and for security reasons
-you are required not to use a printer that has any wireless capabilities. You
-should have access to a compatible printer that has been set up by your
-administrator.
+you are required not to use a printer that has any wireless capabilities.
+
+You should have access to a supported printer that has been set up by your
+administrator. The printer must be plugged into the computer's USB port.
 
 Exporting to an Export USB
 --------------------------
 
 Currently, a LUKS-encrypted USB drive is required for exporting submissions. A
-Linux-based system such as Tails is required to configure and use a LUKS-
-encrypted drive, meaning that for the time being, you will only be able to
+Linux-based system such as Tails is required to configure and use a LUKS-encrypted
+drive, meaning that for the time being, you will only be able to
 export to a Linux environment where these drives can be read. For assistance
 with this, see your SecureDrop administrator.
 
 Once you have provisioned a LUKS-encrypted export drive, insert the drive and
 click **Export**. You will be prompted for the password configured for this
 USB drive.
 
-After the export operation is complete, you can physically unplug the USB drive
-or export additional files.
+Once you see a message informing you that the export was successfully completed,
+you can safely unplug the USB drive. Alternatively, you can leave the drive
+plugged in and export additional files.
 
 .. | screenshot_export_drive |