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

Update Install Guide for 4.2 #228

Merged
merged 2 commits into from
Jul 12, 2024
+66 −140
Merged

Update Install Guide for 4.2 #228

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
ecaa5d4
Update install guide for 4.2
nathandyer Jul 9, 2024
e0adfb4
Remove legacy passphrase rotation section
nathandyer Jul 11, 2024
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
37 changes: 20 additions & 17 deletions docs/admin/install/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,21 @@ In order to decrypt submissions, your SecureDrop Workstation will need a copy of

- First, use the network manager widget in the upper right panel to disable your network connection. These instructions refer to the ``vault`` VM, which has no network access by default, but if the SVS USB is attached to another VM by mistake, this will offer some protection against exfiltration.

- Next, choose **Q > Domain: vault > vault: Files** to open the file manager in the ``vault`` VM.
- Next, choose **Q > Apps > vault > Thunar File Manager** to open the file manager in the ``vault`` VM.

- Connect the SVS USB to a USB port on the Qubes computer, then use the devices widget in the upper right panel to attach it to the ``vault`` VM. There will be three entries for the USB in the section titled **Data (Block) Devices**. Choose the *unlabeled* entry (*not* the one labeled "TAILS") annotated with a ``sys-usb`` text that ends with a number, like ``sys-usb:sdb2``. That is the persistent volume.

|Attach TailsData|

- In the the ``vault`` file manager, select **+ Other Locations**, then click the persistent volume's listing in the right panel. It will be named ``N GB encrypted``, where N is the size of the persistent volume. Enter the SVS persistent volume passphrase to unlock and mount it.
- In the the ``vault`` file manager, select the persistent volume's listing in the lower left sidebar. It will be named ``N GB encrypted``, where N is the size of the persistent volume. Enter the SVS persistent volume passphrase to unlock and mount it. When asked if you would like to forget the password immediately or remember it until you logout, choose the option to **Forget password immediately**.

.. note::

You will receive a message that says **Failed to open directory "TailsData"**. This is normal behavior and will not cause any issues with the subsequent steps.

|Unlock TailsData|

- Open a ``dom0`` terminal via **Q > Terminal Emulator**, and run the following command to list the SVS submission key details, including its fingerprint:
- Open a ``dom0`` terminal by opening the **Q Menu**, selecting the gear icon on the left-hand side, then selecting **Other > Xfce Terminal**. Once the Terminal window opens, run the following command to list the SVS submission key details, including its fingerprint:

.. code-block:: sh

nathandyer marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -42,7 +46,7 @@ In order to decrypt submissions, your SecureDrop Workstation will need a copy of

head -n 1 /tmp/sd-journalist.sec

- In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the SVS USB.
- In the ``vault`` file manager, right-click on the **TailsData** sidebar entry, then select **Unmount** and disconnect the SVS USB.


.. _copy_journalist:
Expand All @@ -56,7 +60,7 @@ SecureDrop Workstation connects to your SecureDrop instance's API via the *Journ

- Connect the USB drive to a USB port on the Qubes computer, then use the devices widget in the upper right panel to attach it to the ``vault`` VM. There will be 3 listings for the USB in the widget: one for the base USB, one for the Tails partition on the USB, labeled ``Tails``, and a 3rd unlabeled listing, for the persistent volume. Choose the third listing.

- In the the ``vault`` file manager, select **+ Other Locations**, then click the persistent volume's listing in the right panel. It will be named ```N GB encrypted``, where N is the size of the persistent volume. Enter the persistent volume passphrase to unlock and mount it.
- In the the ``vault`` file manager, select the persistent volume's listing in the lower left sidebar. It will be named ```N GB encrypted``, where N is the size of the persistent volume. Enter the persistent volume passphrase to unlock and mount it. When prompted, select the option to **Forget password immediately**.

- Copy the *Journalist Interface* configuration file to ``dom0``. If your SecureDrop instance uses v3 onion services, use the following command:

Expand All @@ -68,17 +72,17 @@ SecureDrop Workstation connects to your SecureDrop instance's API via the *Journ

- Verify that the ``/tmp/journalist.txt`` file on ``dom0`` contains valid configuration information using the command ``cat /tmp/journalist.txt`` in the ``dom0`` terminal.

- If you used an *Admin Workstation* USB drive, or you don't intend to copy a password database to this workstation, safely disconnect the USB drive now. In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the USB drive.
- If you used an *Admin Workstation* USB drive, or you don't intend to copy a password database to this workstation, safely disconnect the USB drive now. In the ``vault`` file manager, right-click on the **TailsData** sidebar entry, then select **Unmount** and disconnect the USB drive.

Copy SecureDrop login credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Users of SecureDrop Workstation must enter their username, passphrase and two-factor code to connect with the SecureDrop server. You can manage these passphrases using the KeePassXC password manager in the ``vault`` VM. If this laptop will be used by more than one journalist, we recommend that you shut down the ``vault`` VM now (using the Qube widget in the upper right panel), skip this section, and use a smartphone password manager instead.

In order to set up KeePassXC for easy use:

- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Domain: vault > vault: Qube Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Apps > vault > Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
Copy link
Member

Choose a reason for hiding this comment

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

This is a pre-existing issue, but "Applications" is part of a separate menu, and I think it's misleading to make it think it's part of the same Q menu.

(Not asking for a fix, just flagging for a future potential improvement)

Copy link
Contributor

Choose a reason for hiding this comment

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

I would vote to fix it while we're in here!


- Launch KeePassXC via **Q > Domain: vault > vault: KeePassXC**. When prompted to enable automatic updates, decline. ``vault`` is networkless, so the built-in update check will fail; the app will be updated through system updates instead.
- Launch KeePassXC via **Q > Apps > vault > KeePassXC**. When prompted to enable automatic updates, decline. ``vault`` is networkless, so the built-in update check will fail; the app will be updated through system updates instead.

- Close the application.

Expand All @@ -96,7 +100,7 @@ In order to copy a journalist's login credentials:

- Drag and drop the password database to copy it.

- In the ``vault`` file manager, select **+ Other Locations** and eject the TailsData volume, then disconnect the *Journalist Workstation* USB. Close this file manager window.
- In the ``vault`` file manager, right-click on the **TailsData** sidebar entry, then select **Unmount** and disconnect the *Journalist Workstation* USB. Close this file manager window.

- In the file manager window that displays the home directory, open the copy you made of the password database by double-clicking it.

Expand All @@ -115,9 +119,9 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec

- First, re-enable the network connection using the network manager widget.

- Next, start a terminal in the network-attached ``work`` VM, via **Q > Domain:work > work: Terminal**.
- Next, start a terminal in the network-attached ``work`` VM, via **Q > Apps > work > Xfce Terminal**.

.. note:: As the next steps include commands that must be typed exactly, you may want to open a browser in the ``work`` VM, open this documentation there, and copy-and-paste the commands below into your ``work`` terminal. Note that due to Qubes' default security settings you will *not* be able to paste commands into your ``dom0`` terminal. The ``work`` browser can be opened via **Q > Domain: work > work: Firefox**
.. note:: As the next steps include commands that must be typed exactly, you may want to open a browser in the ``work`` VM, open this documentation there, and copy-and-paste the commands below into your ``work`` terminal. Note that due to Qubes' default security settings you will *not* be able to paste commands into your ``dom0`` terminal. The ``work`` browser can be opened via **Q > Apps > work > Firefox**

- In the ``work`` terminal, run the following commands to download and add the SecureDrop signing key, which is needed to verify the SecureDrop Workstation package:

Expand All @@ -137,7 +141,7 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec

[securedrop-workstation-temporary]
enabled=1
baseurl=https://yum.securedrop.org/workstation/dom0/f32
baseurl=https://yum.securedrop.org/workstation/dom0/f37
name=SecureDrop Workstation Qubes initial install bootstrap

- Download the SecureDrop Workstation config package to the curent working directory with the command:
Expand All @@ -152,18 +156,17 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec

nathandyer marked this conversation as resolved.
Show resolved Hide resolved
.. code-block:: sh

rpm -Kv securedrop-workstation-dom0-config-<versionNumber>-1.fc32.noarch.rpm
rpm -Kv securedrop-workstation-dom0-config-<versionNumber>-1.fc37.noarch.rpm

where ``<versionNumber>`` is the release version number you noted above. The command output should match the following text:

.. code-block:: none

securedrop-workstation-dom0-config-<versionNumber>-1.fc32.noarch.rpm:
securedrop-workstation-dom0-config-<versionNumber>-1.fc37.noarch.rpm:
Header V4 RSA/SHA512 Signature, key ID 7b22e6a3: OK
Header SHA256 digest: OK
Header SHA1 digest: OK
nathandyer marked this conversation as resolved.
Show resolved Hide resolved
Payload SHA256 digest: OK
V4 RSA/SHA512 Signature, key ID 7b22e6a3: OK
MD5 digest: OK


Expand All @@ -172,7 +175,7 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec
.. code-block:: sh

qvm-run --pass-io work \
"cat /home/user/securedrop-workstation-dom0-config-<versionNumber>-1.fc32.noarch.rpm" \
"cat /home/user/securedrop-workstation-dom0-config-<versionNumber>-1.fc37.noarch.rpm" \
> securedrop-workstation.rpm

- Verify that the RPM was transferred correctly by running the following commands:
Expand All @@ -181,7 +184,7 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec

.. code-block:: sh

sha256sum securedrop-workstation-dom0-config-<versionNumber>-1.fc32.noarch.rpm
sha256sum securedrop-workstation-dom0-config-<versionNumber>-1.fc37.noarch.rpm

- in the ``dom0`` terminal:

Expand Down
71 changes: 46 additions & 25 deletions docs/admin/install/prepare.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,6 @@ Pre-install Tasks
=================
.. include:: ../../includes/top-warning.rst

Rotate legacy passphrases
~~~~~~~~~~~~~~~~~~~~~~~~~
To ensure that all passphrases meet the security requirements of the system, you must rotate the passphrases of any *Journalist Interface* users whose accounts were set up on or before September 12, 2017.

To verify when users were added to the system:

- Log into the *Journalist Interface* with an admin account.
- Click the **Admin** link in the top right.
- Review the **Created** column in the list of users.

To rotate passphrases for accounts, please see the `instructions <https://docs.securedrop.org/en/stable/admin/reference/admin_interface.html#passphrases-and-two-factor-resets>`_ in the SecureDrop Admin Guide.

Apply BIOS updates and check settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before beginning the Qubes installation, make sure that your Qubes-compatible computer's BIOS is updated to the latest available version. If you're using one of the recommended ThinkPad T-series models, see the section on :ref:`thinkpad_t_series`. The process will be different for other makes and models, and can usually be found on their respective support sites.
Expand All @@ -38,15 +26,43 @@ If the Qubes hardware compatibility list entry for your computer recommends the

Download and verify Qubes OS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On the working computer, download the Qubes OS ISO for version ``4.1.2`` from `https://www.qubes-os.org/downloads/ <https://www.qubes-os.org/downloads/#qubes-release-4-1-2>`_. The ISO is 5.4 GiB approximately, and may take some time to download based on the speed of your Internet connection.
On the working computer, download the Qubes OS ISO and cryptographic hash values for version ``4.2.2`` from `https://www.qubes-os.org/downloads/ <https://www.qubes-os.org/downloads/#qubes-release-4-2-2>`_. The ISO is 6.9 GB approximately, and may take some time to download based on the speed of your Internet connection.

Follow the linked instructions to `verify the ISO <https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-detached-pgp-signatures-on-qubes-isos>`_. Ensure that the ISO and hash values are in the same directory, then run:

.. code-block:: sh

Follow the linked instructions to `verify the ISO <https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-detached-pgp-signatures-on-qubes-isos>`_.
gpg --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-4.2-signing-key.asc
gpg -v --verify Qubes-R4.2.2-x86_64.iso.DIGESTS

The output should look like this:

.. code-block:: sh

gpg: requesting key from 'https://keys.qubes-os.org/keys/qubes-release-4.2-signing-key.asc'
gpg: key E022E58F8E34D89F: public key "Qubes OS Release 4.2 Signing Key" imported
gpg: Total number processed: 1
gpg: imported: 1
gpg: no ultimately trusted keys found

gpg: armor header: Hash: SHA256
gpg: original file name=''
gpg: Signature made Tue 25 Jun 2024 01:32:23 PM EDT
gpg: using RSA key 9C884DF3F81064A569A4A9FAE022E58F8E34D89F
gpg: using pgp trust model
gpg: Good signature from "Qubes OS Release 4.2 Signing Key" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 9C88 4DF3 F810 64A5 69A4 A9FA E022 E58F 8E34 D89F
gpg: textmode signature, digest algorithm SHA256, key algorithm rsa4096

Specifically, you will want to make sure that you see "Good signature" listed in the text. If it does not report a good signature, try deleting the ISO and downloading it again.

Once you've verified the ISO, copy it to your installation medium - for example, if using Linux and a USB stick, using the command:
zenmonkeykstop marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: sh

sudo dd if=Qubes-R4.1.2-x86_64.iso of=/dev/sdX bs=1048576 && sync
sudo dd if=Qubes-R4.2.2-x86_64.iso of=/dev/sdX bs=1048576 && sync

where ``if`` is set to the path to your downloaded ISO file and ``of`` is set to
the block device corresponding to your USB stick. Note that any data on the USB stick will be overwritten.
Expand All @@ -62,7 +78,7 @@ To begin the Qubes installation, connect the Qubes install USB to your target co
Follow the `installation documentation <https://www.qubes-os.org/doc/installation-guide/>`_ to install Qubes on your computer, ensuring that you:

- Use all available storage space for the installation (as the computer should be dedicated to SecureDrop Workstation).
- Set a strong FDE passphrase - a 6-word Diceware passphrase is recommended.
- Set a strong full disk encryption (FDE) passphrase - a 6-word Diceware passphrase is recommended.
- Create an administrative account named ``user`` with a strong password.

.. note:: Qubes is not intended to have multiple user accounts, so your account name and password will be shared by all SecureDrop Workstation users. The password will be required to log in and unlock the screen during sessions - choosing something strong but memorable and easily typed is recommended!
Expand All @@ -75,6 +91,7 @@ After the disk is unlocked and Qubes starts, you will be prompted to complete th

On the configuration screen, ensure that the following options are checked:

- Default Template should be set to "Fedora 40 Xfce"
zenmonkeykstop marked this conversation as resolved.
Show resolved Hide resolved
- "Create default system qubes (sys-net, sys-firewall, default DispVM)"
- "Make sys-firewall and sys-usb disposable"

Expand All @@ -89,7 +106,16 @@ Once the initial setup is complete, the login dialog will be displayed. Log in u

If, during the installation, you encountered the grayed out option "USB qube configuration disabled", you must now create a VM to access your USB devices. If you did not encounter this issue, you can skip this section.

To create a USB qube, open a ``dom0`` terminal via the Qubes menu (the **Q** icon in the upper left corner): **Q > Terminal Emulator**. Run the following command:
To create a USB qube, open a ``dom0`` terminal by opening the **Q Menu**, selecting the gear icon on the left-hand side, then selecting **Other > Xfce Terminal**

.. tip::

For quicker access, you can add the ``dom0`` terminal to the "Favorites" section of the
Qubes menu (identified by a bookmark symbol). Right-click the entry and select
**Add to favorites**. To remove it at a later time, right-click the entry in your
list of favorites and select **Remove from favorites**.

Run the following command:

.. code-block:: sh

Expand All @@ -113,7 +139,7 @@ Apply ``dom0`` updates (estimated wait time: 15-30 minutes)

After logging in, use the network manager widget in the upper-right panel to configure your network connection.

Open a ``dom0`` terminal via the Qubes menu (the **Q** icon in the upper left corner): **Q > Terminal Emulator**. Run the following command:
Open a ``dom0`` terminal by opening the **Q Menu**, selecting the gear icon on the left-hand side, then selecting **Other > Xfce Terminal**. Run the following command:

.. code-block:: sh

Expand All @@ -127,13 +153,8 @@ Apply updates to system templates (estimated wait time: 45-60 minutes)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After logging in again, confirm that the network manager successfully connects you to the configured network. If necessary, verify the network settings using the network manager widget.

- Next, configure Tor by selecting the Qubes menu (the **Q** icon in the upper left corner) and selecting **Service: sys-whonix > sys-whonix: Anon Connection Wizard**. In most cases, choosing the default **Connect** option is best. Click **Next**, then **Next** again. Then, if Tor connects successfully, click **Finish**. If Tor fails to connect, make sure your network conection is up and does not filter Tor connections, then try again.
- Next, configure Tor by selecting the Qubes menu (the **Q** icon in the upper left corner) and selecting **Q > Service > sys-whonix > Anon Connection Wizard**. In most cases, choosing the default **Connect** option is best. Click **Next**, then **Next** again. Then, if Tor connects successfully, click **Finish**. If Tor fails to connect, make sure your network conection is up and does not filter Tor connections, then try again.

.. note:: If Tor connections are blocked on your network, you may need to configure Tor to use bridges in order to get a connection. For more information, see the `Anon Connection Wizard <https://www.whonix.org/wiki/Anon_Connection_Wizard>`_ documentation.

- Once Tor has connected, select **Q > Qubes Tools > Qubes Update** to update the system VMs. in the ``[Dom0] Qubes Updater`` window, first check ``Enable updates for qubes without known available updates``, then check all entries in the list above except for dom0 (which you have already updated in the previous step). Then, click **Next**. The system's VMs will be updated sequentially - this may take some time. When the updates are complete, click **Finish**.

Install Fedora 40 template
~~~~~~~~~~~~~~~~~~~~~~~~~~

See :doc:`../reference/upgrading_fedora`.
- Once Tor has connected, select the **Q Menu**, click the gear icon on the left-hand side, then select **Qubes Tools > Qubes Update** to update the system VMs. in the ``[Dom0] Qubes Updater`` window, check all entries in the list above except for ``dom0`` (which you have already updated in the previous step). Then, click **Update**. The system's VMs will be updated sequentially - this may take some time. When the updates are complete, click **Next**. You will then be prompted to **Finish and restart/shutdown 4 qubes.** Go ahead and do so, and allow time for them to restart.
Loading