Merge pull request freedomofpress#4413 from freedomofpress/docs-submi…

…ssion-key

[docs] Standardize Submission Key language and usage

docs/admin.rst

@@ -383,7 +383,7 @@ Currently, when one admin pushes changes in ``site-specific`` to the server, the
 changes will not sync to the local ``site-specific`` file on the remaining admin workstations.
 Without being aware of changes made to ``site-specific``, admins run the risk of pushing old
 information to the servers. This can affect the receipt of OSSEC alerts, viability of the
-Submission Key, among other critical components of the SecureDrop environment.
+*Submission Key*, among other critical components of the SecureDrop environment.
 
 There are multiple ways to avoid pushing out-of-date information to the servers.
 We recommend admins establish a secure communication pipeline to alert fellow admins

docs/generate_securedrop_application_key.rst → docs/generate_submission_key.rst

@@ -1,15 +1,15 @@
-Generate the SecureDrop Submission Key
-======================================
+Generate the *Submission Key*
+=============================
 
 When a document or message is submitted to SecureDrop by a source, it is
-automatically encrypted with the *SecureDrop Submission Key*. The private part
+automatically encrypted with the *Submission Key*. The private part
 of this key is only stored on the *Secure Viewing Station* which is never
 connected to the Internet. SecureDrop submissions can only be decrypted and
 read on the *Secure Viewing Station*.
 
-We will now generate the *SecureDrop Submission Key*. If you aren't still
-logged into your *Secure Viewing Station* from the previous step, boot it using
-its Tails USB stick, with persistence enabled.
+We will now generate the *Submission Key*. If you aren't still logged into your
+*Secure Viewing Station* from the previous step, boot it using its Tails USB
+stick, with persistence enabled.
 
 .. important:: Do not follow these steps before you have fully configured the
   *Secure Viewing Station* according to the :doc:`instructions <set_up_svs>`.
@@ -53,8 +53,8 @@ Create the Key
    needed**.
 #. Wait for the key to finish generating.
 
-Export the Public Key
----------------------
+Export the *Submission Public Key*
+----------------------------------
 
 To manage GPG keys using the graphical interface (a program called Seahorse),
 click the clipboard icon |gpgApplet| in the top right corner and select

docs/glossary.rst

@@ -98,19 +98,40 @@ device with the FreeOTP app installed.
 Secure Viewing Station
 ----------------------
 
-The *Secure Viewing Station* (or *SVS* for short) is a machine that is
-kept offline and only ever used together with the Tails operating system
-on the *offline* USB stick. This machine will be used to generate GPG
-keys for all journalists with access to SecureDrop, as well as to
-decrypt and view submitted documents.
+The *Secure Viewing Station* (or *SVS* for short) is the computer you use to
+decrypt and view documents and messages submitted to your SecureDrop. This
+computer is permanently kept offline. It is "air-gapped", meaning that there
+is a gap between it and any computer connected to the Internet.
+
+You will boot the *SVS* from a designated USB stick running the Tails operating
+system. Once you have created it, you should never attach this USB stick to any
+Internet-connected device.
+
+During the installation, the *SVS* is used to generate the *Submission Key*
+for encrypting and decrypting documents and messages submitted to SecureDrop.
+In addition, we recommend importing the public keys of individual journalists to
+the *SVS*, so you can securely encrypt files to their keys before exporting them.
 
 Since this machine will never touch the Internet or run an operating
 system other than Tails on a USB, it does not need a hard drive or
 network device. We recommend physically removing the drive and any
 networking cards (wireless, Bluetooth, etc.) from this machine.
 
-This is also referred to as the "air-gapped computer," meaning there is a
-gap between it and a computer connected to the Internet.
+Submission Key
+--------------
+
+The *Submission Key* is the GPG keypair used to encrypt and decrypt documents
+and messages sent to your SecureDrop. Because the public key and private key
+must be treated very differently, we sometimes refer to them explicitly as the
+*Submission Public Key* and the *Submission Private Key*.
+
+The *Submission Public Key* is uploaded to your SecureDrop servers as part of
+the installation process. Once your SecureDrop is online, anyone will be able
+to download it.
+
+The *Submission Private Key* should never be accessible to a computer with
+Internet connectivity. Instead, it should remain on the *Secure Viewing Station*
+and on offline backup storage.
 
 Two-Factor Authenticator
 ------------------------

docs/index.rst

@@ -33,7 +33,7 @@ anonymous sources.
    set_up_tails
    set_up_svs
    set_up_transfer_device
-   generate_securedrop_application_key
+   generate_submission_key
    set_up_admin_tails
    network_firewall
    servers

docs/install.rst

@@ -61,9 +61,8 @@ continuing:
 
 -  the *Application Server* local IP address
 -  the *Monitor Server* local IP address
--  the SecureDrop Submission Key (from the *Transfer
-   Device*)
--  the SecureDrop Submission Key fingerprint
+-  the *Submission Public Key* (from the *Transfer Device*)
+-  the *Submission Key* fingerprint
 -  the email address that will receive alerts from OSSEC
 -  the GPG public key and fingerprint for the email address that will
    receive the alerts
@@ -93,10 +92,10 @@ will need:
 Before proceeding, you will need to copy the following files to
 ``install_files/ansible-base``:
 
--  the SecureDrop Submission Key public key file
+-  the *Submission Public Key* file
 -  the admin's GPG public key file (for encrypting OSSEC alerts)
 
-The SecureDrop Submission Key should be located on your *Transfer
+The *Submission Public Key* should be located on your *Transfer
 Device* from earlier. Its exact path will depend on the location where the USB stick
 is mounted. From the root of the SecureDrop repository, run: ::
 
@@ -173,11 +172,11 @@ Service will be available in the following files under
 - ``mon-ssh-aths`` contains the ``HidServAuth`` for SSH access to the
   *Monitor Server*.
 
-.. warning:: The ``app-journalist-aths``, ``app-ssh-aths``, and 
-             ``mon-ssh-aths`` files contain passwords for their corresponding 
-             authenticated hidden services. They should not be shared with 
-             third parties or copied from the *Admin Workstation* for any 
-             reason other than well-defined administrative tasks such as 
+.. warning:: The ``app-journalist-aths``, ``app-ssh-aths``, and
+             ``mon-ssh-aths`` files contain passwords for their corresponding
+             authenticated hidden services. They should not be shared with
+             third parties or copied from the *Admin Workstation* for any
+             reason other than well-defined administrative tasks such as
              onboarding new users or performing backups.
 
 The dynamic inventory file will automatically read the Onion URLs

docs/journalist.rst

@@ -142,11 +142,11 @@ it from their inbox, a checkmark will appear next to the reply in the interface.
 You may also delete replies if you change your mind after sending them.
 
 Documents and messages are encrypted to the SecureDrop installation's
-GPG public key. In order to read the messages or look at the documents
-you will need to transfer them to the *Secure Viewing Station*. To recall
-the conversation history between your organization and sources, you can also
-download replies and transfer them to the *Secure Viewing Station* for
-decryption.
+*Submission Public Key*. In order to read the messages or look at the documents
+you will need to transfer them to the *Secure Viewing Station*, which holds
+the *Submission Private Key*. To recall the conversation history between your
+organization and sources, you can also download replies and transfer them to the
+*Secure Viewing Station* for decryption.
 
 Flag for Reply
 ~~~~~~~~~~~~~~
@@ -233,8 +233,8 @@ Decrypting on the *Secure Viewing Station*
 
 To decrypt documents, return to your **Persistent** folder and
 double-click on the zipped file folder. After you extract the files,
-click on each file individually. A prompt will ask you for the
-application PGP key passphrase to decrypt the document.
+click on each file individually. If you have configured a passphrase during
+the generation of your *Submission Key*, you will be prompted for it.
 
 |Decrypting|
 

docs/onboarding.rst

@@ -28,9 +28,9 @@ Determine Access Protocol for the *Secure Viewing Station*
 ----------------------------------------------------------
 
 Currently, SecureDrop only supports encrypting submissions to a single
-public/private key pair - the *SecureDrop Submission Key*. As a
-result, each journalist needs a way to access the Secure Viewing
-Station with a Tails USB that includes the submission private key.
+public/private key pair - the *Submission Key*. As a result, each journalist
+needs a way to access the *Secure Viewing Station* with a Tails USB that
+includes the *Submission Private Key*.
 
 The access protocol for the *Secure Viewing Station* depends on the
 structure and distribution of your organization. If your organization
@@ -69,18 +69,18 @@ to access the servers over SSH.
          the *Admin Workstation* via the Transfer Device. Place these files
          in ``~/Persistent/securedrop/install_files/ansible-base`` on the
          *Journalist Workstation*, and the ``./securedrop-admin tailsconfig``
-         tool will automatically use them. Don't forget to securely delete 
-         these files from the *Transfer Device* when you're done, by 
+         tool will automatically use them. Don't forget to securely delete
+         these files from the *Transfer Device* when you're done, by
          right-clicking them in the file manager and selecting **Wipe**.
 
 .. warning:: Do **not** copy the files ``app-ssh-aths`` and ``mon-ssh-aths``
              to the *Journalist Workstation*. Those files grant access via SSH,
              and only the *Admin Workstation* should have shell access to the
              servers.
 
-.. warning:: The ``app-journalist-aths`` file contains a password for the 
-             authenticated hidden service used by the *Journalist Interface*, 
-             and should not be shared except through the onboarding process. 
+.. warning:: The ``app-journalist-aths`` file contains a password for the
+             authenticated hidden service used by the *Journalist Interface*,
+             and should not be shared except through the onboarding process.
 
 Since you need will the Tails setup scripts (``securedrop/tails_files``) that
 you used to :doc:`Configure the *Admin Workstation* Post-Install
@@ -163,7 +163,7 @@ The journalist should verify that they:
 .. note:: Again, it is important that they test on the same *SVS Tails USB* and
    the same *Secure Viewing Station* they will be using on a day to day basis.
 
-6. Verify the submission private key is present in the *Secure Viewing Station*
+6. Verify the *Submission Private Key* is present in the *Secure Viewing Station*
    persistent volume by clicking the clipboard icon |gpgApplet| in the top right
    corner of the Tails desktop and selecting “Manage Keys”. When clicking
    “GnuPG keys” the key should be present.

docs/threat_model/mitigations.rst

@@ -1,4 +1,4 @@
-Attacks and Countermeasures on the SecureDrop Environment  
+Attacks and Countermeasures on the SecureDrop Environment
 =========================================================
 
 SecureDrop is a complex ecosystem comprised of various pieces of hardware, a
@@ -55,7 +55,7 @@ Countermeasures on both *Source* and *Journalist Interfaces*
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -  *Interfaces* run on an end-to-end encrypted Tor hidden service
 -  Sensitive source and submission data is sent through HTTP POST
--  All source submissions are encrypted with GPG at rest using the airgapped submission key
+-  All source submissions are encrypted with GPG at rest using the airgapped *Submission Key*
 -  *Interface* sessions are invalidated after a user logs out or inactivity over 120 minutes
 -  Session control on *Interface* includes CSRF token in Flask Framework
 -  All *Interface* session data (except language and locale selection) is discarded at logout, and fully deleted upon exiting the Tor Browser
@@ -146,7 +146,7 @@ Attacks on SecureDrop Dependencies
 
 Countermeasures Against Vulnerabilities in Python or Libraries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--  FPF performs vulnerability management for all Python packages used by SecureDrop 
+-  FPF performs vulnerability management for all Python packages used by SecureDrop
 -  CI will run safety check to ensure dependencies do not have a CVE associated with the `version <https://github.com/freedomofpress/securedrop/commit/e9c13ff3d09dfc446bc28da4347f627b5533b150>`__
 
 Countermeasures Against Vulnerabilities in Tor
@@ -166,7 +166,7 @@ Countermeasures Against Malicious Tails or Ubuntu ISOs
 
 Countermeasures Against Vulnerabilities in the Hardware Firewall
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--  SecureDrop `Admin Guide <https://docs.securedrop.org/en/stable/admin.html>`__ informs administrators to update the hardware firewall and provides a very restrictive policy for accessing the administrative interface (blocked on app and mon ports of the firewall). 
+-  SecureDrop `Admin Guide <https://docs.securedrop.org/en/stable/admin.html>`__ informs administrators to update the hardware firewall and provides a very restrictive policy for accessing the administrative interface (blocked on app and mon ports of the firewall).
 -  Alert emails are sent out to admins when there are critical pfSense vulnerabilities.
 -  *Application* and *Monitor Servers* use IPTables as host-based firewall for defense-in-depth
 -  All application traffic is over Tor Hidden services (end-to-end encrypted) and all software packages are signed. Only DNS and NTP are transmitted over HTTP (unauthenticated and in cleartext)

docs/threat_model/threat_model.rst

@@ -12,15 +12,15 @@ to [email protected].
 Actors
 ------
 
-The SecureDrop ecosystem comprises a host of actors, organzed by the following high-level categories: :ref:`Users <users>`, :ref:`Adversaries <adversaries>`, and :ref:`Systems <systems>`. 
+The SecureDrop ecosystem comprises a host of actors, organzed by the following high-level categories: :ref:`Users <users>`, :ref:`Adversaries <adversaries>`, and :ref:`Systems <systems>`.
 
 .. _users:
 
 Users
 ~~~~~
 
-The following table of the users who interact with the SecureDrop web application. 
-Note that the airgapped SVS with the GPG submission key is required to decrypt
+The following table of the users who interact with the SecureDrop web application.
+Note that the airgapped SVS with the GPG *Submission Key* is required to decrypt
 submissions or messages.
 
 +------------------+----------+-------------------------------------------------+
@@ -102,12 +102,12 @@ deployment, please visit the :doc:`hardware section <../hardware>`.
 +------------------+------------------------------------------------------------+
 | Secure Viewing   | * Airgapped and stripped-down laptop                       |
 | Station (SVS)    | * Tails USB with persistence volume                        |
-+------------------+------------------------------------------------------------+   
++------------------+------------------------------------------------------------+
 
 Assumptions
 -----------
 
-The following assumptions are accepted in the threat model of every SecureDrop project: 
+The following assumptions are accepted in the threat model of every SecureDrop project:
 
 Assumptions About the Source
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -229,7 +229,7 @@ Assets
 +------------------+----------+-------------------------------------------------+
 
 Implications of SecureDrop Area Compromise
------------------------------------------- 
+------------------------------------------
 
 What a Compromise of the *Application Server* Can Surrender
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~