Skip to content

Commit

Permalink
Merge pull request #71 from rocodes/v3-migration-clarify
Browse files Browse the repository at this point in the history 
Modify v3 migration instructions to emphasize concurrent upgrade path
  • Loading branch information
@zenmonkeykstop
zenmonkeykstop committed Nov 9, 2020
2 parents d082299 + 0ff5cbd commit 9a2829d
Showing 1 changed file with 127 additions and 83 deletions.
210 changes: 127 additions & 83 deletions docs/v3_services.rst
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,106 @@
SecureDrop V3 Onion Services
============================
Tor onion services provide anonymous inbound connections to websites and other
servers exclusively over the Tor network. For example, SecureDrop uses onion services
for the *Journalist* and *Source Interface* websites, as well as for
adminstrative access to the servers in SSH-over-Tor mode.
servers exclusively over the Tor network. SecureDrop uses onion services
for the *Journalist* and *Source Interface* websites, as well as for
adminstrative access to the servers in SSH-over-Tor mode.

SecureDrop currently supports both the older v2 version of the onion services
protocol, and the current version, v3. The current version provides stronger
cryptographic primitives than v2 onion services, and includes redesigned
protocols that guard against service information leaks on the Tor network.
Currently, SecureDrop supports two versions of the onion services
protocol: the older version (v2), and the current version (v3), which provides
stronger cryptography and includes redesigned protocols that guard against
service information leaks on the Tor network. Because of these important
improvements, the Tor project is
`deprecating support for v2 onion services <https://blog.torproject.org/v2-deprecation-timeline>`__.

Because of these important improvements, the Tor project is
`deprecating support for v2 onion services <https://blog.torproject.org/v2-deprecation-timeline>`__.
SecureDrop will remove support for v2 onion services as part of its 2.0.0
release, planned for **February 2021**. If you are currently using v2 onion services,
they will become unreachable at that point.
SecureDrop will begin phasing out support for v2 onion services in
**February 2021**. All newsrooms should enable v3 onion services as soon as
possible, but may continue using v2 concurrently to allow all journalists and
sources to transition smoothly.

The unique identifier in v3 onion addresses is 56 characters long - for example:
.. warning::

If you are still using 16-character v2 onion URLs in April 2021, your SecureDrop
servers will become unreachable, and you will have to reinstall SecureDrop
from scratch.

How to distinguish between v2 and v3 onion services
---------------------------------------------------

If your *Source Interface* address is 56 characters long, you are already using v3 onion services, as in the following example:

.. code-block:: none
http://vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion/
http://sdolvtfhatvsysc6l34d65ymdwxcujausv7k5jk4cy5ttzhjoi6fzvyd.onion/
This makes them easily distinguishable from 16-character v2 onion addresses,
such as:
If your *Source Interface* address is 16-characters long, you are still using
v2 onion services, and need to transition to v3 in order to keep using
SecureDrop, as in the following example:

.. code-block:: none
http://secrdrop5wyphb5x.onion/
.. important::
What an upgrade entails
-----------------------

If you are currently advertising a 16-character v2 address like the above
to your sources, it will become unreachable in February 2021. You must
update to v3 onion services before then.
Enabling v3 onion services will have the following effects:

There is no downgrade path from v3 to v2 using the ``securedrop-admin``
tool. We recommend that you follow the v2+v3 migration path below, and test v3
functionality thoroughly before :ref:`disabling v2 onion services <disable_v2>`.

Migrating from v2 to v3 only or v2+v3
-------------------------------------

Preparing for the migration
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before starting the migration process, you should decide whether to move
straight to v3 only, or move to v2+v3 temporarily. As the URLs of your onion
services will change with the move to v3, moving to v2+v3 first will allow
you to minimize the impact of the migration on sources and journalists.

URL changes will affect the following:

- The *Source Interface* address will change - once the migration is complete,
you will need to update your landing page and other resources that reference
the address, such as your SecureDrop directory entry.
- *Journalist* and *Admin Workstations* will need to be updated to use the v3
addresses of the *Journalist* and *Source Interface*, and the SSH proxy
services if your instance is using SSH over Tor.
- You will get a new, 56-character *Source Interface* onion address.
If you follow our recommended steps, this will work alongside your existing
v2 address. When you're ready to announce the change, you will need to update
your landing page and other resources that reference your *Source Interface*
address, such as your SecureDrop directory entry.
- *Journalist* and *Admin Workstations* will need to be updated by your
administrator so that they contain the new onion service addresses and
credentials.
- If your instance uses HTTPS, you will need to provision a new certificate for
the v3 *Source Interface* address - this will need to be done `after` the new
address has been generated.

.. note:: If your certificate provisioning process requires validation of the
new v3 domain, you may not be able to complete the v3 migration process
without first disabling HTTPS for v2. If your instance currently uses
.. note:: If your instance currently uses
HTTPS with an EV certificate, please contact us via the `SecureDrop
support portal`_ or via email to securedrop@freedom.press
before proceeding with the migration. Please use `our GPG key`_ for
any email communication.
support portal`_ or use `our GPG key`_ to send an encrypted email to
securedrop@freedom.press
before you proceed with the migration.
If your certificate provisioning process requires validation of the
new v3 domain, you may not be able to complete the v3 migration
process
without first disabling HTTPS for v2.

.. _SecureDrop Support Portal: https://securedrop-support.readthedocs.io/en/latest/
.. _our GPG key: https://securedrop.org/sites/default/files/fpf-email.asc

Before proceeding with the migration, you should also back up the instance and
*Admin Workstation* USB - for more information, see the following instructions:

How to upgrade
--------------

#. :ref:`Prepare backups <prepare_backups_v3>`
#. :ref:`Enable v3 onion services <enable_v3>` alongside v2, to avoid
disruption to journalists and sources
#. :ref:`(Optional) Enable HTTPS <enable_https_v3>`
#. :ref:`Update Tails workstations <update_tails_v3>` with the new v3 onion addresses
#. :ref:`Publish <publish_v3>` your new *Source Interface* URL
#. Once you are satisfied with these changes, :ref:`disable v2 onion services<disable_v2>`.

Enabling v3 onion services is fairly quick (under an hour), though
the initial backup and the followup steps will take longer. If you have
questions about the upgrade process after reading these instructions, please
contact Support.

.. _prepare_backups_v3:

Prepare backups
^^^^^^^^^^^^^^^

Before proceeding:

- :doc:`Back up the instance <backup_and_restore>`.
- :doc:`Back up the Admin Workstation <backup_workstations>`.

.. _enable_v3:

Enabling v3 onion services
^^^^^^^^^^^^^^^^^^^^^^^^^^
To enable v3 onion services, you will need to run the installation playbook,
via the ``./securedrop-admin install`` command, and then update the *Admin
Workstation* with ``./securedrop-admin tailsconfig``.
Enable v3 onion services
^^^^^^^^^^^^^^^^^^^^^^^^

- First, boot into the *Admin Workstation* with the persistent volume unlocked
and an admin password set.
Expand All @@ -94,38 +111,45 @@ Workstation* with ``./securedrop-admin tailsconfig``.
cd ~/Persistent/securedrop
- Verify that SecureDrop version 1.0.0 or greater is available or installed on
- Verify that SecureDrop version |version| is available or installed on
your instance with the command:

.. code:: sh
ssh app apt-cache policy securedrop-app-code
Version 1.0.0 should be listed as installed or as an installation candidate.
- Verify that the *Admin Workstation*'s SecureDrop code is on 1.0.0 or greater,
Version |version| should be listed as installed or as an installation candidate.
- Verify that the *Admin Workstation*'s SecureDrop code is on |version|,
using the GUI updater or the command:

.. code:: sh
./securedrop-admin update
- After updating the latest SecureDrop version, use the following command to
- After updating to the latest SecureDrop version, use the following command to
update ``securedrop-admin``'s dependencies:

.. code:: sh
./securedrop-admin setup
- Next, enable v3 onion services (and optionally disable v2 services) using:
- Next, enable v3 onion services using:

.. code:: sh
./securedrop-admin sdconfig
This command will step through the current instance configuration. None of the
current settings should be changed. When prompted to enable v2 and v3
services, you should choose either ``yes`` to both to use v2 and v3
concurrently, or ``no`` to v2 and ``yes`` to v3 to migrate to v3 only.
services, you should choose either ``yes`` to both to enable v2 and v3
concurrently (recommended), or ``no`` to v2 and ``yes`` to v3 to migrate to
v3 only.

.. important::

There is no downgrade path from v3 to v2 using the ``securedrop-admin``
tool. We strongly recommend enabling v2 + v3 concurrently
to minimize the impact of the migration on sources and journalists.

- Once the configuration has been updated, run the installation playbook using
the command:
Expand All @@ -134,7 +158,8 @@ Workstation* with ``./securedrop-admin tailsconfig``.
./securedrop-admin install
This will enable v3 onion services on the *Application* and *Monitor Servers*.
This will enable v3 onion services on the *Application* and *Monitor Servers*,
and may take some time to complete.

- When the installation playbook run is complete, update the *Admin Workstation*
to use v3 onion services using the command:
Expand All @@ -157,8 +182,11 @@ Workstation* with ``./securedrop-admin tailsconfig``.

- Finally, back up the instance and *Admin Workstation* USB.

(Optional) enabling HTTPS
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _enable_https_v3:

(Optional) Enable HTTPS
^^^^^^^^^^^^^^^^^^^^^^^

If your instance serves the *Source Interface* over HTTPS, and you plan to
continue using HTTPS with v3 onion services, you'll need to provision a
new certificate for the new v3 address.
Expand All @@ -172,13 +200,15 @@ You'll find the new *Source Interface* address in the file:
Follow the instructions in :doc:`HTTPS on the Source Interface <https_source_interface>`
to provision and install the new certificate.

.. _update_tails_v3:

Updating Workstation USBs
^^^^^^^^^^^^^^^^^^^^^^^^^^
Update Workstation USBs
^^^^^^^^^^^^^^^^^^^^^^^

If you chose to keep v2 enabled, *Admin* and *Journalist Workstations* that have
not yet been updated will still be able to connect to the v2 onion services. Even
so, you should update all workstations to use v3 services as soon as possible.
If you followed our recommendations, your other *Admin* and
*Journalist Workstations* will still work over the old v2 protocol until that
is disabled. Even so, you should update all workstations to use v3 services as
soon as possible, for security reasons and to avoid future breakage.

Journalist Workstation:
~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -211,8 +241,8 @@ Journalist Workstation:
- Open a terminal and run ``./securedrop-admin tailsconfig`` to update the
SecureDrop desktop shortcuts.

- Verify that the new 56-character addresses are in use by visiting the *Source*
and *Journalist Interfaces* via the SecureDrop desktop shortcuts.
- Verify that the new 56-character addresses are in use by visiting the
*Source* and *Journalist Interfaces* via the SecureDrop desktop shortcuts.

- Securely wipe the files on the *Transfer Device*, by right-clicking them
in the file manager and selecting **Wipe**.
Expand Down Expand Up @@ -269,9 +299,10 @@ Admin Workstation:
- Securely wipe the files on the *Transfer Device*, by right-clicking them
in the file manager and selecting **Wipe**.

.. _publish_v3:

Updating Source Interface references
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Publish your new *Source Interface* URL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order for sources to find and use the new v3 *Source Interface*, you'll
need to update your landing page. If your instance details are listed
anywhere else (for example, in the SecureDrop directory), you should update
Expand All @@ -286,14 +317,13 @@ You'll find the new *Source Interface* address in the file:
.. _disable_v2:

Disabling v2 onion services
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once you've successfully enabled v3 onion services, and updated your workstations,
you should disable v2 onion services altogether.
Disable v2 onion services
^^^^^^^^^^^^^^^^^^^^^^^^^
Once you've successfully enabled v3 onion services and updated your
workstations, you should disable v2 onion services altogether.

First, it's recommended that you coordinate with the journalists using the
instance to ensure that any ongoing source conversations are uninterrupted. They
Coordinate with journalists to ensure that any ongoing
source conversations are not interrupted. Journalists
can use SecureDrop's reply feature to give active sources advance notice of
the address change.

Expand All @@ -309,14 +339,13 @@ When you're ready, follow the steps below to transition to v3 services only:
cd ~/Persistent/securedrop
- Next, update the application configuration using the command:

.. code:: sh
./securedrop-admin sdconfig
This command will step through the current instance configuration. When prompted
This command will step through the current instance configuration. When prompted,
you should type ``no`` for v2 services and ``yes`` for v3 services to migrate to
v3 only. No other settings should be modified.

Expand Down Expand Up @@ -347,3 +376,18 @@ When you're ready, follow the steps below to transition to v3 services only:
./securedrop-admin sdconfig # choose "no" for v2, "yes" for v3
./securedrop-admin tailsconfig
Human-readable onion URLs
-------------------------

Despite their important security benefits, v3 onion URLs are longer and more
unwieldy. See
`our blog post <https://securedrop.org/news/introducing-onion-names-securedrop/>`_
for information on how to get an onion name (a human-readable alias)
for your new *Source
Interface* URL, with the format ``<yourorganization>.securedrop.tor.onion``.

Onion names are the supported solution for organizations wishing to
customize their *Source Interface* URL, and are recommended over "vanity"
URLs (addresses that start with a few recognizable characters).

0 comments on commit 9a2829d

Please sign in to comment.