From ecaa5d49a03d4de3b19a28ec3126e501cdee04ca Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Tue, 9 Jul 2024 15:20:29 -0400 Subject: [PATCH 1/2] Update install guide for 4.2 --- docs/admin/install/install.rst | 37 +++++---- docs/admin/install/prepare.rst | 59 +++++++++++--- docs/admin/reference/upgrading_fedora.rst | 97 ----------------------- docs/index.rst | 1 - 4 files changed, 66 insertions(+), 128 deletions(-) delete mode 100644 docs/admin/reference/upgrading_fedora.rst diff --git a/docs/admin/install/install.rst b/docs/admin/install/install.rst index a6dc9bd..41a404b 100644 --- a/docs/admin/install/install.rst +++ b/docs/admin/install/install.rst @@ -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 @@ -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: @@ -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: @@ -68,7 +72,7 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -76,9 +80,9 @@ Users of SecureDrop Workstation must enter their username, passphrase and two-fa 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). -- 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. @@ -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. @@ -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: @@ -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: @@ -152,18 +156,17 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec .. code-block:: sh - rpm -Kv securedrop-workstation-dom0-config--1.fc32.noarch.rpm + rpm -Kv securedrop-workstation-dom0-config--1.fc37.noarch.rpm where ```` is the release version number you noted above. The command output should match the following text: .. code-block:: none - securedrop-workstation-dom0-config--1.fc32.noarch.rpm: + securedrop-workstation-dom0-config--1.fc37.noarch.rpm: Header V4 RSA/SHA512 Signature, key ID 7b22e6a3: OK Header SHA256 digest: OK Header SHA1 digest: OK Payload SHA256 digest: OK - V4 RSA/SHA512 Signature, key ID 7b22e6a3: OK MD5 digest: OK @@ -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--1.fc32.noarch.rpm" \ + "cat /home/user/securedrop-workstation-dom0-config--1.fc37.noarch.rpm" \ > securedrop-workstation.rpm - Verify that the RPM was transferred correctly by running the following commands: @@ -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--1.fc32.noarch.rpm + sha256sum securedrop-workstation-dom0-config--1.fc37.noarch.rpm - in the ``dom0`` terminal: diff --git a/docs/admin/install/prepare.rst b/docs/admin/install/prepare.rst index 6b579e7..56e4fac 100644 --- a/docs/admin/install/prepare.rst +++ b/docs/admin/install/prepare.rst @@ -38,15 +38,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/ `_. 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/ `_. 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 `_. +Follow the linked instructions to `verify the ISO `_. Ensure that the ISO and hash values are in the same directory, then run: + +.. code-block:: sh + + 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: .. 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. @@ -62,7 +90,7 @@ To begin the Qubes installation, connect the Qubes install USB to your target co Follow the `installation documentation `_ 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! @@ -75,6 +103,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" - "Create default system qubes (sys-net, sys-firewall, default DispVM)" - "Make sys-firewall and sys-usb disposable" @@ -89,7 +118,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 @@ -113,7 +151,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 @@ -127,13 +165,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 `_ 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. diff --git a/docs/admin/reference/upgrading_fedora.rst b/docs/admin/reference/upgrading_fedora.rst deleted file mode 100644 index 06225fc..0000000 --- a/docs/admin/reference/upgrading_fedora.rst +++ /dev/null @@ -1,97 +0,0 @@ -Upgrading to Fedora 40 -====================== - -.. include:: ../../includes/top-warning.rst - -Why do I need to upgrade? -------------------------- - -SecureDrop Workstation makes use of several Fedora-based VMs which are part of -a Qubes installation by default, including ``sys-firewall``, ``sys-net``, ``sys- -usb``, ``work``, and ``vault`` . In Qubes 4.2, these VMs are based on a -Fedora 39 template, which reaches end-of-life in November 2024. - -If you are provisioning SecureDrop Workstation for the first time, -update your Fedora template manually to Fedora 40 *before* installing -SecureDrop Workstation. - -If you are an existing SecureDrop Workstation user, SecureDrop Workstation -will install the template automatically when updates are applied, but you -should also :ref:`manually configure ` VMs not managed by -SecureDrop Workstation to use the Fedora 40 template. - -Install Fedora-40 template --------------------------- - -In a ``dom0`` terminal (**Qubes Application Menu > Terminal Emulator**), type -the following to download the Fedora 40 template: - -.. code:: sh - - sudo qvm-template install fedora-40-xfce - -You will see some information from the template manager, including a progress -bar. - -When the download has concluded, you will be prompted to install the package. -Type ``y`` to proceed with the installation. - - -Update the Fedora-40 template ------------------------------ -Once the template installation is complete, update the template using the Qubes -Updater. Click **Q > Qubes Tools > Qubes Update** in the application menu. -Click the checkbox "Enable updates for qubes without known updates" option, -and click the checkbox next to ``fedora-40-xfce``. Click **Next** and wait for -any available updates to be downloaded and applied. - -.. _configure_vms: - -Configure VMs to use the new template -------------------------------------- -To apply the template to VMs that currently use an older version, open the -Qube Manager via **Q > Qubes Tools > Qube Manager**. All VMs will be visible at -a glance; to change a VM's settings, right-click it and select **Qube Settings**. - -In the Qube Settings window, select ``fedora-40-xfce`` from the drop-down menu -beside **Template**, then click **OK.** - -|screenshot_qsettings_fedora32| - -You should perform this process for: - - - ``work`` - - ``vault`` - - ``sys-net`` - - ``default-mgmt-dvm``. - -Create a new disposable VM template based on Fedora 40 by running -the following commands in ``dom0``: - -.. code:: sh - - qvm-create -l red -t fedora-40-xfce fedora-40-dvm - qvm-prefs fedora-40-dvm template_for_dispvms True - qvm-features fedora-40-dvm appmenus-dispvm 1 - qubes-prefs default-dispvm fedora-40-dvm - -Now, switch the templates for ``sys-usb`` and ``sys-firewall`` to -``fedora-40-dvm`` using the same process that you used above. - -Reboot the system to ensure the changes take effect. Alternatively, you can -restart only the VMs you have updated. If you get a ``sys-whonix`` prompt asking how you want to connect to the Tor network, select the "Connect" option, which allows a direct connection to the Tor network. - -.. tip:: - - You can also use the **Qubes Template Manager** (also in **Q > Qubes Tools**) - to make template changes. However, note that it will not allow you to make - template changes for VMs that are currently running, so you may have to - manually shut down VMs in the correct order to do so. - -.. |screenshot_qsettings_fedora32| image:: ../../images/screenshot_qsettings_fedora32.png - :width: 100% - -Getting Support ---------------- - -.. include:: ../../includes/getting_support.rst diff --git a/docs/index.rst b/docs/index.rst index 07d46dd..8e60efd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,7 +53,6 @@ against malware and other security risks. It is built on Qubes OS and requires a admin/reference/troubleshooting_connection admin/reference/troubleshooting_updates admin/reference/provisioning_usb - admin/reference/upgrading_fedora admin/reference/backup * :ref:`genindex` From e0adfb40c90f14725f7a341e7ce25f4b4dab0aae Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Thu, 11 Jul 2024 18:23:34 -0400 Subject: [PATCH 2/2] Remove legacy passphrase rotation section --- docs/admin/install/prepare.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/admin/install/prepare.rst b/docs/admin/install/prepare.rst index 56e4fac..be74986 100644 --- a/docs/admin/install/prepare.rst +++ b/docs/admin/install/prepare.rst @@ -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 `_ 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.