mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-10-01 01:25:40 -04:00
Cleaned up documentation
Moved USB qube instructions to the top of the document. Removed references to closed out issues. Added USB mouse instructions. Added disk passphrase warning. Removed Qubes 3.1 specific references due to EOL.
This commit is contained in:
Yethal
GitHub
parent
f343ab34b0
commit
9b69a5a146
@ -17,6 +17,160 @@ redirect_from:
|
||||
Using and Managing USB Devices
|
||||
==============================
|
||||
|
||||
Creating and Using a USB qube
|
||||
-----------------------------
|
||||
|
||||
The connection of an untrusted USB device to dom0 is a security risk since dom0,
|
||||
like almost every OS, reads partition tables automatically and since the whole
|
||||
USB stack is put to work to parse the data presented by the USB device in order
|
||||
to determine if it is a USB mass storage device, to read its configuration, etc.
|
||||
This happens even if the drive is then assigned and mounted in another qube.
|
||||
|
||||
To avoid this risk, it is possible to prepare and utilize a USB qube.
|
||||
|
||||
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). 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).
|
||||
You can create a USB qube using the management stack by performing the following
|
||||
steps as root in dom0:
|
||||
|
||||
1. Enable `sys-usb`:
|
||||
|
||||
qubesctl top.enable qvm.sys-usb
|
||||
|
||||
2. Apply the configuration:
|
||||
|
||||
qubesctl state.highstate
|
||||
|
||||
Alternatively, you can create a USB qube manually as follows:
|
||||
|
||||
1. Read the [Assigning 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). If you need to attach a networking device,
|
||||
it might make sense to create a NetVM. If not, an AppVM might make more
|
||||
sense. (The default `sys-usb` is a NetVM.)
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
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 the USB qube will not start, see [here][faq-usbvm].
|
||||
|
||||
How to hide all USB controllers from dom0
|
||||
-----------------------------------------
|
||||
|
||||
If you create a USB qube manually, there will be a brief period of time during the
|
||||
boot process during which 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] 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.
|
||||
|
||||
The procedure to hide all USB controllers from dom0 is as follows:
|
||||
|
||||
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` in dom0.
|
||||
6. Reboot.
|
||||
|
||||
(Note: Beginning with R3.2, `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] using the `qubesctl` method, which is the
|
||||
first pair of steps in the linked section.)
|
||||
|
||||
**Warning** USB keyboard cannot be used to type the disk passphrase
|
||||
if USB controllers were hidden from dom0 as USB qube is not active yet. Before hiding
|
||||
USB controllers make sure your laptop keyboard is not internally connected via USB
|
||||
(by checking output of `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.
|
||||
|
||||
|
||||
Removing a USB qube
|
||||
-------------------
|
||||
|
||||
**Warning:** This procedure will result in your USB controller(s) being attached
|
||||
directly to dom0.
|
||||
|
||||
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.
|
||||
|
||||
How to use a USB keyboard
|
||||
-------------------------
|
||||
|
||||
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. Note that allowing
|
||||
keyboard access from a USB qube gives it great power. In short:
|
||||
|
||||
* It will see whatever you type on that keyboard (including passwords).
|
||||
* It will be able to inject keystrokes, which basically means that it will be
|
||||
able to enter any command. For example, if some malware catches your
|
||||
screenlocker password, it will be able to unlock the screen when you are not
|
||||
present. (For more details, see [here][input-proxy].)
|
||||
|
||||
If you are sure you wish to proceed, then you must edit the
|
||||
`qubes.InputKeyboard` policy file in dom0, which is located here:
|
||||
|
||||
/etc/qubes-rpc/policy/qubes.InputKeyboard
|
||||
|
||||
Add a line like this one to the top of the file:
|
||||
|
||||
sys-usb dom0 ask,user=root
|
||||
|
||||
(Change `sys-usb` to your desired USB qube.)
|
||||
|
||||
You can now use your USB keyboard.
|
||||
|
||||
How to use a USB mouse
|
||||
----------------------
|
||||
|
||||
In order to use a USB mouse, you must first attach it to a USB qube, then
|
||||
give that qube permission to pass mouse input to dom0.
|
||||
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
|
||||
|
||||
/etc/qubes-rpc/policy/qubes.InputMouse
|
||||
|
||||
Add a line like this to the op of the file:
|
||||
|
||||
sys-usb dom0 ask,user=root
|
||||
|
||||
(Change `sys-usb` to your desired USB qube.)
|
||||
|
||||
You can now use your USB mouse.
|
||||
|
||||
How to attach USB drives
|
||||
------------------------
|
||||
|
||||
@ -102,11 +256,7 @@ follows:
|
||||
Otherwise, you will not be able to attach it anywhere later. See issue [1082]
|
||||
for details.
|
||||
|
||||
There have been reports that when attaching a single partition, the Nautilus
|
||||
file manager would not see it and automatically mount it (see issue [623]).
|
||||
This problem seems to be resolved (see [this comment on issue 1072][1072-comm1]).
|
||||
|
||||
If, however, the device does not appear in Nautilus, you will need to mount it
|
||||
If the device does not appear in Nautilus, you will need to mount it
|
||||
manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is
|
||||
already one device attached -- if two, `/dev/xvdk`, and so on).
|
||||
|
||||
@ -147,162 +297,6 @@ steps:
|
||||
`qvm-block -d` command.
|
||||
|
||||
|
||||
Creating and Using a USB qube
|
||||
-----------------------------
|
||||
|
||||
The connection of an untrusted USB device to dom0 is a security risk since dom0,
|
||||
like almost every OS, reads partition tables automatically and since the whole
|
||||
USB stack is put to work to parse the data presented by the USB device in order
|
||||
to determine if it is a USB mass storage device, to read its configuration, etc.
|
||||
This happens even if the drive is then assigned and mounted in another qube.
|
||||
|
||||
To avoid this risk, it is possible to prepare and utilize a USB qube.
|
||||
|
||||
For this reason, you may wish to avoid using a USB qube if you do not have a USB
|
||||
controller free of input devices and programmable devices, although Qubes R3.1
|
||||
introduced support for USB mice and keyboards (see below).
|
||||
|
||||
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). 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). Again, this works only for USB mass storage devices.
|
||||
Other devices cannot currently be virtualized.
|
||||
|
||||
You can create a USB qube using the management stack by performing the following
|
||||
steps as root in dom0:
|
||||
|
||||
1. Enable `sys-usb`:
|
||||
|
||||
qubesctl top.enable qvm.sys-usb
|
||||
|
||||
2. Apply the configuration:
|
||||
|
||||
qubesctl state.highstate
|
||||
|
||||
(Note: This automatically [hides all USB controllers from dom0][hide-usb].)
|
||||
|
||||
Alternatively, you can create a USB qube manually as follows:
|
||||
|
||||
1. Read the [Assigning 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). If you need to attach a networking device,
|
||||
it might make sense to create a NetVM. If not, an AppVM might make more
|
||||
sense. (The default `sys-usb` is a NetVM.)
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
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 the USB qube will not start, see [here][faq-usbvm].
|
||||
|
||||
|
||||
Removing a USB qube
|
||||
-------------------
|
||||
|
||||
**Warning:** This procedure will result in your USB controller(s) being attached
|
||||
directly to dom0.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
How to hide all USB controllers from dom0
|
||||
-----------------------------------------
|
||||
|
||||
Even if you create a USB qube, there will be a brief period of time during the
|
||||
boot process during which 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] 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.
|
||||
|
||||
The procedure to hide all USB controllers from dom0 is as follows:
|
||||
|
||||
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` in dom0.
|
||||
6. Reboot.
|
||||
|
||||
(Note: Beginning with R3.2, `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] using the `qubesctl` method, which is the
|
||||
first pair of steps in the linked section.)
|
||||
|
||||
Supported USB device types
|
||||
--------------------------
|
||||
|
||||
As of Qubes R3.1, it is possible to attach:
|
||||
|
||||
* USB mice
|
||||
* USB keyboards (see below)
|
||||
* USB block devices (such as USB mass storage devices)
|
||||
* When attaching one of these, you should get a notification about the
|
||||
new device, then you should be able to attach it to a qube in Qubes VM
|
||||
Manager.
|
||||
|
||||
Other devices, such as USB webcams, will also work, but they will be
|
||||
accessible only from the USB qube itself, as explained above.
|
||||
|
||||
|
||||
How to use a USB keyboard
|
||||
-------------------------
|
||||
|
||||
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. Note that allowing
|
||||
keyboard access from a USB qube gives it great power. In short:
|
||||
|
||||
* It will see whatever you type on that keyboard (including passwords).
|
||||
* It will be able to inject keystrokes, which basically means that it will be
|
||||
able to enter any command. For example, if some malware catches your
|
||||
screenlocker password, it will be able to unlock the screen when you are not
|
||||
present. (For more details, see [here][input-proxy].)
|
||||
|
||||
If you are sure you wish to proceed, then you must edit the
|
||||
`qubes.InputKeyboard` policy file in dom0, which is located here:
|
||||
|
||||
/etc/qubes-rpc/policy/qubes.InputKeyboard
|
||||
|
||||
Add a line like this one to the top of the file:
|
||||
|
||||
sys-usb dom0 ask,user=root
|
||||
|
||||
(Change `sys-usb` to your desired USB qube.)
|
||||
|
||||
You can now use your USB keyboard.
|
||||
|
||||
Attaching a single USB device to a qube (USB passthrough)
|
||||
---------------------------------------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user