Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Revamp "USB qubes" page; update links

Browse Source
This commit is contained in:
Andrew David Wong 2022-01-24 14:43:22 -08:00
parent 9e414119e7
commit 80d5a6f7c6
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 197 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

319
user/advanced-topics/usb-qubes.md
View File

@ -12,78 +12,83 @@ ref: 181
title: USB qubes
---
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
A USB qube acts as a secure handler for potentially malicious USB devices,
preventing them from coming into contact with dom0 (which could otherwise be
fatal to the security of the whole system). It thereby mitigates some of the
[security risks of using USB
devices](/doc/device-handling-security/#usb-security). Nonetheless, we strongly
recommend carefully reading the [security warning on USB input
devices](/doc/device-handling-security/#security-warning-on-usb-input-devices)
before proceeding.
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login](#enable-a-usb-keyboard-for-login)!
With a USB qube, every time you connect an untrusted USB device to a USB port
managed by that USB controller, you will have to attach it to the qube in which
you wish to use it (if different from the USB qube itself).
## Creating and Using a USB qube ##
If you opted to allow the Qubes installer to create a USB qube for you during
the installation process, then you should already have a working USB qube, and
no further action should be required. However, if you do not have a USB qube,
wish to remove the one you have, or have run into some other related problem,
this page can help.
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue](https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312).
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications](/doc/device-handling-security/#usb-security) of using USB devices.
With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci](/doc/how-to-use-pci-devices/) command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices](/doc/how-to-use-usb-devices/#finding-the-right-usb-controller).
You can create a USB qube using the management stack by performing the following steps as root in dom0:
## USB keyboards
```
sudo qubesctl state.sls qvm.sys-usb
```
If you use a USB keyboard, there is a high risk of locking yourself out of your
system when experimenting with USB qubes. For example, if a USB qube takes over
your sole USB controller (to which your USB keyboard is connected), then your
keyboard will no longer be able to control dom0. This will prevent you from
performing many essential tasks, such as entering your decryption and login
passphrases, rendering your system unusable until you reinstall. This section
covers various options for addressing this problem.
Alternatively, you can create a USB qube manually as follows:
In general, PS/2 keyboards are preferable to USB keyboards. However, many newer
computer models lack PS/2 ports. Moreover, while most laptops use PS/2
connections for the keyboard internally, some use USB. (Check yours by
examining the output of the `lsusb` command.) If you have a PS/2 port but still
wish to use a USB keyboard, then having a backup PS/2 keyboard handy can be
useful in case you accidentally lock yourself out of your system.
1. Read the [PCI Devices](/doc/how-to-use-pci-devices/) page to learn how to list and identify your USB controllers.
Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
If you find a free controller, note its name and proceed to step 2.
2. Create a new qube.
Give it an appropriate name and color label (recommended: `sys-usb`, red).
3. In the qube's settings, go to the "Devices" tab.
Find the USB controller that you identified in step 1 in the "Available" list.
Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
**Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive.
### How to create a USB qube for use with a USB keyboard
4. Click `OK`.
Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
(This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
If you're reading this section, it's likely because the installer did not allow
you to create a USB qube automatically because you're using a USB keyboard.
This section will explain how to create a USB qube that you can use with your
USB keyboard. This section assumes that you have only a single USB controller.
If you have more than one USB controller, see [how to enable a USB keyboard on
a separate USB
controller](#how-to-enable-a-usb-keyboard-on-a-separate-usb-controller).
If the USB qube will not start, please have a look at the [faq](/faq/#i-created-a-usb-vm-and-assigned-usb-controllers-to-it-now-the-usb-vm-wont-boot).
## Enable a USB keyboard for login ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding!
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices).
It is recommended to use separate USB controller for input devices (keyboard, mouse etc). If it is an option on a given system, please see [Enable a USB keyboard on a separate USB controller](#enable-a-usb-keyboard-on-a-separate-usb-controller) section. Otherwise continue with the section below.
### Automatic setup (single USB controller) ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates](/doc/how-to-install-software-in-dom0/#how-to-update-dom0)) and execute in dom0:
First, make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines`
package by [updating
dom0](/doc/how-to-install-software-in-dom0/#how-to-update-dom0). Then, enter
the following command in dom0:
```
sudo qubesctl state.sls qvm.usb-keyboard
```
The above command will take care of all required configuration, including creating USB qube if not present.
Note that it will expose dom0 to USB devices while entering LUKS passphrase. In Qubes 4.1 (or never), only input devices (keyboards, mice etc) are initialized at this stage.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
This command will take care of all required configuration, including creating a
USB qube if not already present. Note, however, that this setup will expose
dom0 to USB devices while you are entering your LUKS passphrase. While only
input devices (keyboards, mice, etc.) are initialized at this stage, users are
advised to physically disconnect other devices from the system during this
vulnerable window in order to minimize the risk.
To undo these changes, please follow the section on [**Removing a USB qube**](#removing-a-usb-qube)!
To undo these changes, see [how to remove a USB
qube](#how-to-remove-a-usb-qube).
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
If you wish to perform only a subset of this configuration (for example, you do
not wish to enable the USB keyboard during boot), see the manual instructions
below.
### Manual setup (single USB controller) ###
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
#### Manual setup for USB keyboards
In order to use a USB keyboard, you must first attach it to a USB qube, then
give that qube permission to pass keyboard input to dom0. Edit the
`qubes.InputKeyboard` policy file in dom0, which is located here:
```
/etc/qubes-rpc/policy/qubes.InputKeyboard
@ -97,40 +102,67 @@ sys-usb dom0 allow
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard to login and for LUKS decryption during boot.
You can now use your USB keyboard to log in and for LUKS decryption during
boot.
For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to:
You can set up your system so that there's a confirmation prompt each time the
USB keyboard is connected. However, this will effectively disable your USB
keyboard for login and LUKS decryption, so **don't do this if you want to
unlock your device with a USB keyboard!** If you're sure you wish to proceed,
change the previous line to:
```
sys-usb dom0 ask,default_target=dom0
```
*Don't do that if you want to unlock your device with a USB keyboard!*
If you wish to use a USB keyboard to enter your LUKS passphrase, you cannot
[hide its USB controller from dom0](#how-to-hide-usb-controllers-from-dom0). If
you've already hidden that USB controller from dom0, you must revert the
procedure by removing the `rd.qubes.hide_all_usb` option and employ an
alternative strategy for protecting your system by physically disconnecting
other devices during startup. You should also add the
`usbcore.authorized_default=0` option, which prevents the initialization of
non-input devices. (Qubes ships with a USBGuard configuration that allows only
input devices when `usbcore.authorized_default=0` is set.)
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0](#how-to-hide-all-usb-controllers-from-dom0).
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup. In Qubes 4.1 (or newer), add `usbcore.authorized_default=0` option - it will prevent initializing non-input devices (Qubes ships an usbguard configuration that allows just input devices when `usbcore.authorized_default=0` is set).
### Enable a USB keyboard on a separate USB controller
### How to enable a USB keyboard on a separate USB controller
This section assumes Qubes 4.1 or newer.
When using a USB keyboard on a system with multiple USB controllers, we
recommend that you designate one of them exclusively for the keyboard (and
possibly the mouse) and keep other devices connected to the other
controller(s). This is often an option on desktop systems, where additional USB
controllers can be plugged in as PCIe cards. In this case, the designated
controller for input devices should remain in dom0 but be limited to input
devices only. To set it up:
When using USB keyboard on a system with multiple USB controllers, it is recommended to designate one of them for the keyboard (and possibly mouse) only, and keep other devices connected to the other controller(s). It is often an option for a desktop systems, where additional USB controller can be plugged in as a PCIe card.
1. [Find the controller used for input
devices](/doc/how-to-use-usb-devices/#finding-the-right-usb-controller).
2. Open the file `/etc/default/grub` in dom0.
3. Find the line that begins with `GRUB_CMDLINE_LINUX`.
4. Add `usbcore.authorized_default=0` and `rd.qubes.dom0_usb=<BDF>` to that
line, where `<BDF>` is the USB controller identifier.
5. Save and close the file.
6. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` (legacy boot) or
`grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg` (EFI) in dom0.
7. Reboot.
8. Proceed with [creating a USB qube](#how-to-create-a-usb-qube) normally. The
selected USB controller will remain in dom0.
In this case, the designated controller for input devices should remain in dom0, but be limited to input devices only. To set it up:
1. [Find the controller used for input devices](/doc/how-to-use-usb-devices/#finding-the-right-usb-controller).
2. Add `usbcore.authorized_default=0 rd.qubes.dom0_usb=<BDF>` options to the kernel command line, where `<BDF>` is the USB controller identifier. See [How to hide USB controllers from dom0](#how-to-hide-usb-controllers-from-dom0) section how do to that (but use options mentioned here instead of `rd.qubes.hide_all_usb`.
3. Restart the system
4. Proceed with adding USB qube normally. The selected USB controller will remain in dom0.
These options can be added during installation. (When the installer prompts for
a reboot, you can switch to tty2 and perform the steps from there, after using
the `chroot /mnt/sysimage` command.) In that case, the initial setup will
create a USB qube automatically, even when a USB keyboard is in use (as long as
it is connected to the designated controller).
Those options can be added during installation (when the installer prompt for reboot, you can switch to tty2 and perform the steps from there, after using `chroot /mnt/sysimage` command). In that case, initial setup will create USB qube automatically, even when USB keyboard is in use (as long as it is connected to the designated controller).
## Auto Enabling A USB Mouse ##
## USB mice
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding.
Handling a USB mouse isn't as critical as handling a keyboard, since you can
log in and proceed through confirmation prompts using the keyboard alone.
Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone.
If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at:
If you want to attach the USB mouse automatically anyway, you have to edit the
`qubes.InputMouse` policy file in dom0, located at:
```
/etc/qubes-rpc/policy/qubes.InputMouse
@ -142,9 +174,13 @@ The first line should read similar to:
sys-usb dom0 ask,default_target=dom0
```
which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0.
There will now be a confirmation prompt each time a USB mouse is attached.
In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file:
If the file is empty or does not exist, something might have gone wrong during
setup. Try to rerun `qubesctl state.sls qvm.sys-usb` in dom0.
In case you are absolutely sure you do not want to confirm mouse access from
`sys-usb` to `dom0`, you may add the following line to the top of the file:
```
sys-usb dom0 allow
@ -152,69 +188,108 @@ sys-usb dom0 allow
(Change `sys-usb` to your desired USB qube.)
## How to hide USB controllers from dom0 ##
(Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
This also occurs automatically if you choose to [create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl` method, which is the
first pair of steps in the linked section.)
## How to create a USB qube
**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
Before hiding USB controllers, make sure your laptop keyboard is not internally connected via USB (by checking output of the `lsusb` command) or that you have a PS/2 keyboard at hand (if using a desktop PC).
Failure to do so will render your system unusable.
If [automatically creating a USB qube for use with a USB
keyboard](#how-to-create-a-usb-qube-for-use-with-a-usb-keyboard) does not apply
to your situation, then you may be interested in more general methods for
creating USB qubes.
If you create a USB qube manually, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices).
This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised.
There are two approaches to this problem:
You can create a USB qube using the management stack by executing the following
command as root in dom0:
```
sudo qubesctl state.sls qvm.sys-usb
```
### Manual creation
You can create a USB qube manually as follows:
1. Read the [PCI devices](/doc/how-to-use-pci-devices/) page to learn how to
list and identify your USB controllers. Carefully check whether you have a
USB controller that would be appropriate to assign to a USB qube. Note that
it should be free of input devices, programmable devices, and any other
devices that must be directly available to dom0. If you find a free
controller, note its name and proceed to the next step.
2. Create a new qube. Give it an appropriate name and color label (recommended:
`sys-usb`, red).
3. In the qube's settings, go to the "Devices" tab. Find the USB controller
that you identified in step 1 in the "Available" list. Move it to the
"Selected" list by highlighting it and clicking the single arrow `>` button.
(**Warning:** By assigning a USB controller to a USB qube, it will no longer
be available to dom0. This can make your system unusable if, for example,
you have only one USB controller, and you are running Qubes off of a USB
drive.)
4. Click `OK`. Restart the qube.
5. Recommended: Check the box on the "Basic" tab that says "Start VM
automatically on boot." (This will help to mitigate attacks in which someone
forces your system to reboot, then plugs in a malicious USB device.)
If the USB qube will not start, please have a look at [this FAQ
entry](/faq/#i-created-a-usb-vm-and-assigned-usb-controllers-to-it-now-the-usb-vm-wont-boot).
## How to hide USB controllers from dom0
USB controllers are automatically hidden from dom0 if you opt to create a USB
qube during installation. This also occurs automatically if you choose to
[create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl`
method. However, if you create a USB qube manually and do not hide USB
controllers from dom0, there will be a brief period of time during the boot
process when dom0 will be exposed to your USB controllers (and any attached
devices). This is a potential security risk, since even brief exposure to a
malicious USB device could result in dom0 being compromised. There are two
approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM](/doc/anti-evil-maid/) device, do not use the second option.
Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
If dom0 cannot read your USB AEM device, AEM will hang.
**Warning:** If you use a USB keyboard, hiding your USB controllers from dom0
could lock you out of your system. See [USB keyboards](#usb-keyboards) for more
information.
The procedure to hide all USB controllers from dom0 is as follows:
**Warning:** Using a USB AEM device requires dom0 to have access to the USB
controller to which your USB AEM device is attached. If dom0 cannot read your
USB AEM device, AEM will hang.
* GRUB2 (legacy boot, or EFI on Qubes 4.1)
The following procedure will hide all USB controllers from dom0.
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` (legacy boot) or `grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg` (EFI) in dom0.
6. Reboot.
### GRUB2 (legacy boot or EFI)
* EFI
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` (legacy boot) or
`grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg` (EFI) in dom0.
6. Reboot.
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
2. Find the lines that begin with `kernel=`. There may be more than one.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. Reboot.
In Qubes 4.1 it is possible to use `rd.qubes.dom0_usb=<BDF>` option in addition to `rd.qubes.hide_all_usb`, to keep a selected USB controller (specified as `<BDF>`) visible in dom0. This can be especially useful if one have multiple USB controllers, and designate one for connecting (only) keyboard/mouse. In such a case, adding `usbcore.authorized_default=0` option is recommended too, to really allow only input devices (see the section about USB keyboard above).
## How to remove a USB qube
## Removing a USB qube ##
**Warning:** This procedure will result in your USB controller(s) being
attached directly to dom0.
**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
### GRUB2
* GRUB2
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
### EFI
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.