mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-02-26 09:41:13 -05:00
Merge branch 'patch-6' of git://github.com/Yethal/qubes-doc into Yethal-patch-6
This commit is contained in:
Andrew David Wong
commit
2992dc8067
@ -17,6 +17,170 @@ 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. 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. Note that allowing
|
||||
mouse access from a USB qube gives it great power. In short:
|
||||
|
||||
* It will be able to change any global and per-domain setting available within GUI
|
||||
* It will be able to attach untrusted devices to domains that should not
|
||||
have device access
|
||||
* It will be able to enable networking in network-disconnected domains
|
||||
* It will be able to initiate file transfer between domains.
|
||||
(For more details, see [here][input-proxy].)
|
||||
|
||||
If you are sure you wish to proceed, then you must 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 +266,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 +307,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…
x
Reference in New Issue
Block a user