[docs] updated documentation to include references to v3 services

docs/admin.rst

@@ -453,15 +453,31 @@ into your Admin Workstation, you should first perform the following troubleshoot
    your *Application Server* is online, and you can trigger a `test OSSEC alert`_
    to verify your *Monitor Server* is online.
 
-#. **Ensure that SSH aliases and the HidServAuth values are configured:** From
-   ``~/Persistent/securedrop``, run  ``./securedrop-admin tailsconfig``. This
-   will ensure your local Tails environment is configured properly.
-
-    .. note:: If you get an error during the Tails configuration step, as an Administrator,
-       you should ensure you have four files ``app-ssh-aths``, ``mon-ssh-aths``,
-       ``app-journalist-aths`` and ``app-source-ths`` in
-       ``~/Persistent/securedrop/install_files/ansible-base/``. These are used by
-       the Tails configuration scripts to configure Tor.
+#. **Ensure that SSH aliases and onion service authentication are configured:**
+
+   - First, ensure that the correct configuration files are present in 
+     ``~/Persistent/securedrop/install_files/ansible-base``. 
+
+     If v2 onion services
+     are configured, you should have 4 files:
+
+     - ``app-ssh-aths``
+     - ``mon-ssh-aths``
+     - ``app-journalist-aths``
+     - ``app-source-ths`` 
+
+
+     If v3 onion services are 
+     enabled, you should have the following 5 files:
+
+     - ``app-ssh.auth_private``
+     - ``mon-ssh.auth_private``
+     - ``app-journalist.auth_private``
+     - ``app-sourcev3-ths``
+     - ``tor_v3_keys.json``
+
+   - Then, from ``~/Persistent/securedrop``, run  ``./securedrop-admin tailsconfig``.
+     This will ensure your local Tails environment is configured properly.
 
 #. **Confirm that your SSH key is available**: During the install, you
    configured SSH public key authentication using ``ssh-copy-id``.

docs/backup_and_restore.rst

@@ -1,6 +1,7 @@
 Back Up, Restore, Migrate
 =========================
 
+
 There are a number of reasons why you might want to backup and restore a
 SecureDrop installation. Maintaining periodic backups is generally a good
 practice to guard against data loss. In the event of hardware failure on
@@ -80,13 +81,12 @@ to debug your connectivity before proceeding further. Make sure:
 * Ansible is installed
 * the *Admin Workstation* is connected to the Internet
 * Tor starts successfully
-* the ``HidServAuth`` values from ``install_files/ansible-base/app-ssh-aths``
-  and ``install_files/ansible-base/mon-ssh-aths`` are in Tails at
-  ``/etc/tor/torrc``
+* The appropriate onion service configuration files are present in 
+  ``~/Persistent/securedrop/install_files/ansible-base`` and the 
+  ``./securedrop-admin tailsconfig`` command completes successfully
 
-(If Ansible is not installed, or the ``HidServAuth`` values are missing
-or incorrect, see :doc:`configure_admin_workstation_post_install` for detailed
-instructions.)
+If Ansible is not installed, or ``./securedrop-admin tailsconfig`` fails, see
+:doc:`configure_admin_workstation_post_install` for detailed setup instructions.
 
 Create the Backup
 '''''''''''''''''
@@ -139,6 +139,11 @@ command. Otherwise, you should copy the backup archive that you wish to restore
 Restoring From a Backup File
 ''''''''''''''''''''''''''''
 
+.. important:: This documentation applies to a SecureDrop instance using
+               v2 onion services. If your instance uses v3 onion services,
+               you will need to follow additional steps depending on your
+               specific restore scenario.
+
 To perform a restore, you must already have a backup archive. Provide its
 filename in the following command:
 

docs/development/tips_and_tricks.rst

@@ -121,6 +121,13 @@ to append values to your local ``torrc``, as in the ``cat`` example above.
 Note that the ``cat`` example above will also add the ATHS info for the
 *Journalist Interface*, as well, which is useful for testing.
 
+.. note:: The instructions above refer to VMs set up with v2 onion services. If
+          v3 onion services are configured instead, the steps required for the 
+          local ``tor`` setup will differ. You will need to add a 
+          ``ClientOnionAuthDir`` directive to ``torrc``, pointing to a directory
+          containing the ``*.auth_private`` files created during the installation
+          process under ``install_files/ansible-base``.
+
 Architecture Diagrams
 ---------------------
 

docs/development/virtual_environments.rst

@@ -102,11 +102,33 @@ local git repository and then installed on the staging servers.
           (last tested on 10.11.6).
 
 The web interfaces and SSH are available over Tor. A copy of the the Onion URLs
-for Source and Journalist Interfaces, as well as SSH access, are written to the
-Vagrant host's ``install_files/ansible-base`` directory, named:
+for *Source* and *Journalist Interfaces*, as well as SSH access, are written to the
+Vagrant host's ``install_files/ansible-base`` directory.
+
+To access the *Source Interface* from Tor Browser, use the v3 onion URL from the file 
+``install_files/ansible-base/app-sourcev3-ths``.
+
+To use the *Journalist Interface*, you will need to modify Tor Browser's 
+configuration to allow access to an authenticated onion service:
+
+- First, add the following line to your Tor Browser's ``torrc`` file, typically
+  found at ``tor-browser_en-US/Browser/TorBrowser/Data/Tor/torrc``:
+
+  .. code-block:: none
+
+    ClientOnionAuthDir TorBrowser/Data/Tor/onion_auth
+
+- Next, create the ``onion_auth`` directory:
+
+  .. code:: sh
+
+    mkdir tor-browser_en-US/Browser/TorBrowser/Data/Tor/onion_auth
+    chmod 0700 tor-browser_en-US/Browser/TorBrowser/Data/Tor/onion_auth
+
+- Finally, copy the file ``install_files/ansible-base/app-journalist.auth_private``
+  to the ``onion_auth`` directory and restart Tor Browser. You should now be able 
+  to visit the v3 onion address in ``app-journalist.auth_private`` from Tor Browser.
 
-* ``app-source-ths``
-* ``app-journalist-aths``
 
 For working on OSSEC monitoring rules with most system hardening active, update
 the OSSEC-related configuration in
@@ -318,10 +340,10 @@ A copy of the Onion URLs for Source and Journalist Interfaces, as well as
 SSH access, are written to the Vagrant host's ``install_files/ansible-base``
 directory, named:
 
-* ``app-source-ths``
-* ``app-journalist-aths``
-* ``app-ssh-aths``
-* ``mon-ssh-aths``
+* ``app-sourcev3-ths``
+* ``app-journalist.auth_private``
+* ``app-ssh.auth_private``
+* ``mon-ssh.auth_private``
 
 SSH Access
 ~~~~~~~~~~

docs/https_source_interface.rst

@@ -15,16 +15,12 @@ encryption and authentication via HTTPS:
   they are communicating with the intended organization when they access a
   given Source Interface.
 
-* The cryptographic primitives used by Tor Onion Services are considered to be
-  outdated, and while there are no known compromises of the security of Tor
-  Onion Services due to this issue, you may wish to provide an additional
-  layer of transport encryption using stronger cryptographic primitives, which
-  is most easily achieved by setting up HTTPS on the Source Interface.
-
-  .. note:: This issue is being addressed by the Tor Project with their Next
-     Generation Onion Services design, but the implementation of the new design
-     is still a work in progress and is not expected to be deployed until
-     December 2017 at the earliest.
+* SecureDrop supports v3 onion services, which use updated cryptographic 
+  primitives that provide better transport-layer encryption than those used 
+  by v2 onion services. It is **strongly** recommended that you configure your
+  instance to use :doc:`v3 onion services <v3_services>`, but if you cannot 
+  switch your instance to v3, using HTTPS on the source interface will provide
+  an extra layer of encryption for data in transit.
 
 .. _`SecureDrop Directory`: https://securedrop.org/directory/
 

docs/index.rst

@@ -80,6 +80,7 @@ anonymous sources.
    rebuild_admin
    kernel_troubleshooting
    getting_support
+   v3_services
 
 .. toctree::
    :caption: Upgrade SecureDrop

docs/install.rst

@@ -13,7 +13,7 @@ command:
 
     ./securedrop-admin setup
 
-The package installation will take approximately 10 minutes, depending
+The package installation will take approximately 10 minutes or longer, depending
 on network speed and computing power.
 
 .. note:: On Tails 3.9 or later, the apt persistence feature will prompt
@@ -53,6 +53,18 @@ parentheses.
           French to be available to read the documents and follow up in that
           language.
 
+Onion Service Options
+---------------------
+SecureDrop supports the use of tradtional (v2)  or next-generation (v3) onion
+services for the *Source* and *Journalist Interfaces*, as well as the SSH proxy
+services if they are configured. Either or both may be enabled, but we recommend
+the use of v3 onion services for any new instances, as they offer greater
+security.
+
+For more information on v3 onion services, including upgrade options 
+for existing instances, see 
+:doc:`SecureDrop v3 onion services <v3_services>`.
+
 Configure the Installation
 --------------------------
 
@@ -156,10 +168,13 @@ an email to [email protected].
 
 .. _`Source Offer`: https://github.com/freedomofpress/securedrop/blob/develop/SOURCE_OFFER
 
-Once the installation is complete, addresses and credentials for each Tor Hidden
-Service will be available in the following files under
+Once the installation is complete, addresses and credentials for each 
+onion service will be available in the following files under
 ``install_files/ansible-base``:
 
+V2 onion services
+^^^^^^^^^^^^^^^^^
+
 - ``app-source-ths`` contains the ``.onion`` address of the *Source
   Interface*.
 - ``app-journalist-aths`` contains the ``HidServAuth``
@@ -174,13 +189,38 @@ Service will be available in the following files under
 
 .. warning:: The ``app-journalist-aths``, ``app-ssh-aths``, and
              ``mon-ssh-aths`` files contain passwords for their corresponding
-             authenticated Onion Services. They should not be shared with
+             authenticated onion 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
-from the ``app-ssh-aths`` and ``mon-ssh-aths`` files and use them to connect
-to the servers over SSH during subsequent playbook runs.
+If v3 onion services are not enabled, the dynamic inventory file will 
+automatically read the Onion URLs from the ``app-ssh-aths`` and ``mon-ssh-aths``
+files and use them to connect to the servers over SSH during subsequent playbook
+runs.
+
+V3 onion services
+^^^^^^^^^^^^^^^^^
+
+- ``app-sourcev3-ths`` contains the v3 ``.onion`` address of the *Source
+  Interface*.
+- ``app-journalist.auth_private`` contains the ``onion`` address and private key
+  providing access to the *Journalist Interface*.
+- ``app-ssh.auth_private`` contains the ``onion`` address and private key
+  providing SSH access to the *Application Server*.
+- ``mon-ssh.auth_private`` contains the ``onion`` address and private key
+  providing SSH access to the *Monitor Server*.
+- ``tor_v3_keys.json`` contains the keypairs required for access to the
+  *Journalist Interface* and SSH access to the servers - it is required for 
+  future runs of ``./securedrop-admin install``.
+
+.. warning:: The three ``.auth_private`` files and the ``tor_v3_keys.json`` file 
+             contain secret keys that should not be shared with third parties,
+             or copied from the *Admin Workstation* for any purpose other than
+             tasks such as performing backups or onboarding new users.
+
+The dynamic inventory file will automatically read the ``onion`` addresses from
+the ``app-ssh.auth_private`` and ``mon-ssh.auth_private`` files and use them to
+connect to the servers over SSH during subsequent playbook runs.
 
 .. |Tails Apt Persistence| image:: images/tails-install-once-or-every-time.png

docs/onboarding.rst

@@ -11,8 +11,8 @@ In order to use SecureDrop, each journalist needs two things:
 
 1. A *Journalist Tails USB*.
 
-     The *Journalist Interface* is only accessible as an Authenticated Tor
-     Hidden Service (ATHS). For ease of configuration and security, we
+     The *Journalist Interface* is only accessible as an authenticated
+     onion service. For ease of configuration and security, we
      require journalists to set up a Tails USB with persistence that
      they are required to use to access the *Journalist Interface*.
 
@@ -68,52 +68,65 @@ passphrase before continuing with the next section.
 Set Up Automatic Access to the *Journalist Interface*
 -----------------------------------------------------
 
-Since the *Journalist Interface* is an ATHS, we need to set up the
-*Journalist Workstation* to auto-configure Tor just as we did with the
-*Admin Workstation*. The procedure is essentially identical, except the
+Since the *Journalist Interface* is an authenticated onion service, you must
+set up the *Journalist Workstation* to auto-configure Tor, similarly to 
+the *Admin Workstation*. The procedure is essentially identical, except the
 SSH configuration will be skipped, since only admins need
 to access the servers over SSH.
 
-.. tip:: Copy the files ``app-journalist-aths`` and ``app-source-ths`` from
-         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
-         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
+- First, boot into the *Admin Workstation*. If your instance has not been set up
+  to use v3 onion services, copy the following v2 service files to a *Transfer Device*:
+
+  .. code-block:: none
+
+    ~/Persistent/securedrop/install_files/ansible_base/app-source-ths
+    ~/Persistent/securedrop/install_files/ansible_base/app-journalist-aths
+
+  If your instance was set up to use v3 services, copy the following files instead:
+
+  .. code-block:: none
+
+    ~/Persistent/securedrop/install_files/ansible_base/app-sourcev3-ths
+    ~/Persistent/securedrop/install_files/ansible_base/app-journalist.auth_private
+
+  Then, boot into the new *Journalist Workstation* USB.
+
+.. warning:: Do **not** copy the ``app-ssh-aths``, ``mon-ssh-aths``,
+             ``app-ssh.auth_private``, ``mon-ssh.auth_private``, or ``tor_v3_keys.json``
+             files to the *Journalist Workstation*. Those files contain private
+             keys and authentication information for SSH server access.
+             Only the *Admin Workstation* should have shell access to the
              servers.
 
-.. warning:: The ``app-journalist-aths`` file contains a password for the
-             authenticated Onion Service used by the *Journalist Interface*,
-             and should not be shared except through the onboarding process.
+- Install the SecureDrop application code on the workstation's persistent volume,
+  following the documentation for :ref:`cloning the SecureDrop
+  repository <Download the SecureDrop repository>`.
+
+- Copy the files from the *Transfer Device* to ``~/Persistent/securedrop/install_files/ansible-base``
 
-Since you need will the Tails setup scripts (``securedrop/tails_files``) that
-you used to :doc:`Configure the *Admin Workstation* Post-Install
-<configure_admin_workstation_post_install>`, clone (and verify) the SecureDrop
-repository on the *Journalist Workstation*, just like you did for the Admin
-Workstation. Refer to the docs for :ref:`cloning the SecureDrop
-repository <Download the SecureDrop repository>`, then return here to
-continue setting up the *Journalist Workstation*.
-
-Once you've done this, use the ``securedrop-admin`` script to configure the
-shortcuts for the Source and *Journalist Interfaces*: ::
-
-  ./securedrop-admin setup
-  ./securedrop-admin tailsconfig
-
-If you did not copy over the ``app-source-ths`` and ``app-journalist-aths``
-files from the *Admin Workstation*, the script will prompt for the information.
-Make sure to type the information carefully, as any typos will break access
-for the *Journalist Workstation*.
-
-Once the script is finished, you should be able to access the
-*Journalist Interface*. Open the Tor Browser and navigate to the .onion address for
-the *Journalist Interface*. You should be able to connect, and will be
-automatically taken to a login page.
+- Open a terminal and run the following commands:
+
+  .. code:: sh
+ 
+    cd ~/Persistent/securedrop
+    ./securedrop-admin setup
+    ./securedrop-admin tailsconfig
+
+  .. note:: The ``setup`` command may take several minutes, and may fail partway
+            due to network issues. If so, run it again before proceeding.
+
+- Once the ``tailsconfig`` command is complete, verify that the *Source* and
+  *Journalist Interfaces* are accessible at their v2 addresses via the 
+  SecureDrop desktop shortcuts.
+
+- Securely wipe the files on the *Transfer Device*, by right-clicking them
+  in the file manager and selecting **Wipe**.
+
+
+.. warning:: The ``app-journalist-aths`` and ``app-journalist.auth_private`` 
+             files contain secret authentication information for the
+             authenticated onion service used by the *Journalist Interface*,
+             and should not be shared except through the onboarding process.
 
 Add an account on the *Journalist Interface*
 --------------------------------------------

docs/rebuild_admin.rst

@@ -1,6 +1,14 @@
 Rebuilding an *Admin Workstation* USB
 -------------------------------------
 
+.. note:: These instructions refer to a SecureDrop instance using v2 onion 
+          services. If your instance uses v3 onion services and you need to
+          rebuild your *Admin Workstation*, please contact FPF through the
+          `SecureDrop Support Portal`_.                            
+
+.. _SecureDrop Support Portal: https://securedrop-support.readthedocs.io/en/latest/
+
+
 In cases where an *Admin Workstation* USB stick has been lost or destroyed, and no
 backup exists, it is possible to rebuild one. In order to do so, you'll need