Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Condense and clarify v3 onion services migration docs #136

Merged
merged 2 commits into from
Jan 22, 2021
Merged

Condense and clarify v3 onion services migration docs #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a7a0bd0
Condense and clarify v3 onion services migration docs
rocodes Jan 21, 2021
cc7209c
Small wording tweak
eloquence Jan 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 11 additions & 7 deletions docs/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,20 +80,24 @@ documents, and move them to the *Secure Viewing Station* using the
Instructions for using the *Journalist Workstation* are available in our
:doc:`Journalist Guide <journalist>`.

.. _glossary_landing_page:

Landing Page
------------
The *Landing Page* is the public-facing webpage for a SecureDrop instance. This
page is hosted as a standard (i.e. non-Tor) webpage on the news organization's
site. It provides first instructions for potential sources.
site. It provides first instructions for potential sources and includes
the instance's :ref:`Source Interface <glossary_source_interface>` address.


Monitor Server
--------------

The *Monitor Server* keeps track of the *Application Server* and sends out an
email alert if something seems wrong. Only system admins connect
to this server, and they may only do so using Tor.

.. _glossary_onion_service:

Onion Service
-------------
Expand All @@ -111,8 +115,11 @@ service address for the SecureDrop website.
Read more about `onion services in Tor's glossary
<https://support.torproject.org/onionservices/>`__.

Onion Service v2
""""""""""""""""
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed this because previously, it said "Onion Service v2" and then the first sentence started "The third generation of onion services (v3) provides stronger... " etc; I found that slightly confusing.

Onion Service versions
""""""""""""""""""""""

Distinguishing between different generations of onion services is easy:
v3 addresses are longer (56 characters) than v2 addresses (16 characters).

The third generation of onion services (v3) provides stronger cryptographic
algorithms than v2 onion services, and includes redesigned protocols that
Expand All @@ -122,10 +129,6 @@ Support for v2 onion services will start to be removed from SecureDrop in
February 2021, and we strongly recommend :doc:`upgrading SecureDrop
instances to v3 onion services <v3_services>` as soon as possible.

Distinguishing between different generations of onion services is easy:
v3 addresses are longer (56 characters) than v2 addresses (16 characters).


OSSEC Alert Public Key
----------------------
The *OSSEC Alert Public Key* is the GPG key that OSSEC will encrypt alerts to.
Expand Down Expand Up @@ -167,6 +170,7 @@ access SecureDrop through the *Source Interface* and must do so using Tor.
Instructions for using SecureDrop as a *Source* are available in our
:doc:`Source Guide <source>`.

.. _glossary_source_interface:

Source Interface
----------------
Expand Down
145 changes: 66 additions & 79 deletions docs/v3_services.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,92 +1,68 @@
SecureDrop V3 Onion Services
============================
Tor onion services provide anonymous inbound connections to websites and other
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.

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>`__.
.. important::

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.
If you have not enabled v3 onion services before April 30, 2021,
your SecureDrop servers will become unreachable. To minimize disruption
to sources and journalists, you should begin the migration well
before that deadline.

.. warning::
Your SecureDrop's :ref:`Landing Page <glossary_landing_page>`
must be updated with your new 56-character onion address so sources
can continue to reach you.

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.
SecureDrop supports the v3 :ref:`onion services <glossary_onion_service>`
protocol, which provides stronger cryptographic protections than v2 onion
services, and helps mitigate 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>`__,
and SecureDrop is also phasing out support for the v2 protocol.

How to distinguish between v2 and v3 onion services
---------------------------------------------------
SecureDrop administrators should enable v3 onion services as soon as possible,
while initially keeping v2 onion services running as well. Then, administrators
should ensure that the new *Source Interface* URL is published on their instance's
:ref:`Landing Page <glossary_landing_page>`, journalists have received new
Tor credentials, and journalists and sources are aware of the change,
before :ref:`disabling v2 onion services <disable_v2>`.

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

.. code-block:: none

http://sdolvtfhatvsysc6l34d65ymdwxcujausv7k5jk4cy5ttzhjoi6fzvyd.onion/

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:
V2 onion addresses are 16 characters long, as in the following example:

.. code-block:: none

http://secrdrop5wyphb5x.onion/

What an upgrade entails
-----------------------

Enabling v3 onion services will have the following effects:
How to Migrate from v2 to v3 Onion Services
-------------------------------------------

- 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.
#. :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>`.

.. note:: If your instance currently uses
HTTPS with an EV certificate, please contact us via the `SecureDrop
support portal`_ or use `our GPG key`_ to send an encrypted email to
support portal`_ or use `our GPG key`_ to send an encrypted email to
securedrop@freedom.press
before you proceed with the migration.
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
new v3 domain, you may not be able to complete the v3 migration
process
without first disabling HTTPS for v2.
without first disabling HTTPS for v2.

.. _SecureDrop Support Portal: https://support-docs.securedrop.org/
.. _SecureDrop Support portal: https://support-docs.securedrop.org/
.. _our GPG key: https://securedrop.org/sites/default/files/fpf-email.asc


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
Expand Down Expand Up @@ -141,15 +117,13 @@ Enable v3 onion services

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 enable v2 and v3
concurrently (recommended), or ``no`` to v2 and ``yes`` to v3 to migrate to
v3 only.
services, you should choose ``yes`` to both.

.. 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.
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 @@ -169,7 +143,7 @@ Enable v3 onion services
./securedrop-admin tailsconfig

- Next, verify connectivity between the *Admin Workstation* and the SecureDrop
instance as follows:
instance:

- Use the Source desktop shortcut to connect to the *Source Interface* and
verify that the new 56-character address is present in the Tor Browser
Expand All @@ -180,7 +154,8 @@ Enable v3 onion services
- Use the commands ``ssh app`` and ``ssh mon`` in a terminal to verify
SSH access to the *Application* and *Monitor Servers*.

- Finally, back up the instance and *Admin Workstation* USB.
- Finally, back up the instance and *Admin Workstation* USB again. Do not
skip this step.

.. _enable_https_v3:

Expand All @@ -200,12 +175,13 @@ 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:

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

If you followed our recommendations, your other *Admin* and
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.
Expand Down Expand Up @@ -241,7 +217,7 @@ 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
- 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
Expand Down Expand Up @@ -301,7 +277,7 @@ Admin Workstation:

.. _publish_v3:

Publish your new *Source Interface* URL
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
Expand All @@ -314,15 +290,20 @@ You'll find the new *Source Interface* address in the file:

~/Persistent/securedrop/install_files/ansible-base/app-sourcev3-ths

Please open a ticket with us on the `Support Portal`_ advising us of your
new *Source Interface* address as well, so that our Support team can
continue to provide you with outage alerts.

.. _Support Portal: https://support-docs.securedrop.org/

.. _disable_v2:

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

Coordinate with journalists to ensure that any ongoing
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 Down Expand Up @@ -381,13 +362,19 @@ When you're ready, follow the steps below to transition to v3 services only:
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
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
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).
URLs (addresses that start with a few recognizable characters).


Getting Support
---------------

.. include:: includes/getting-support.txt