Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-28 08:49:42 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'patch-4' of https://github.com/awokd/qubes-doc into awokd-patch-4

Browse Source
This commit is contained in:
Andrew David Wong 2018-02-11 13:17:51 -06:00
commit 244d0d4bc6
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 140 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

471
common-tasks/usb.md
View File

@ -21,211 +21,69 @@ redirect_from:
Using and Managing USB Devices Using and Managing USB Devices
============================== ==============================
Creating and Using a USB qube How to attach USB drives
----------------------------- ----------
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this with a encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23]. (**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
The connection of an untrusted USB device to dom0 is a security risk since dom0, Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller.
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:** 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 `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.
Security Warning about USB Input Devices
----------------------------------------
**Important security warning. Please read this section carefully!**
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer.
You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer.
This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube.
(**Note:** In the present context, the term "USB drive" denotes any
[USB mass storage device][mass-storage]. In addition to smaller flash memory
sticks, this includes things like USB external hard drives.)
Qubes OS supports the ability to attach a USB drive (or just one or more of its
partitions) to any qube easily, no matter which qube actually handles the USB
controller.
### R4.0 ### ### R4.0 ###
USB drive mounting is integrated into the Devices Widget. This is the tool tray USB drive mounting is integrated into the Devices Widget.
icon with a yellow square located in the top right of your screen by default. This is the tool tray icon with a yellow square located in the top right of your screen by default.
Simply insert Simply insert your USB drive and click on the widget.
your USB drive and click on the widget. You will see multiple entries for your You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example. The simplest (but slightly less secure, see note below about attaching individual partitions) option is to attach the entire block drive.
The simplest (but slightly less secure, see note below about attaching individual In our example, this is `sda`, so hover over it.
partitions) option is to attach the entire block drive. In our example, this is `sda`,
so hover over it.
This will pop up a submenu showing running VMs to which the USB drive can be connected. This will pop up a submenu showing running VMs to which the USB drive can be connected.
Click on one and your USB drive will be attached! Click on one and your USB drive will be attached!
Note that attaching individual partitions can be slightly more secure because it doesn't Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
force the target AppVM to parse the partition table. However, it often means the However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
AppVM won't detect the new partition and you will need to manually mount it inside See below for more detailed steps.
the AppVM. See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
is `qvm-block`. This tool can be used to assign a USB drive to a qube as This tool can be used to assign a USB drive to a qube as follows:
follows:
1. Insert your USB drive. 1. Insert your USB drive.
2. In a dom0 console (running as a normal user), list all available block 2. In a dom0 console (running as a normal user), list all available block devices:
devices:
qvm-block qvm-block
This will list all available block devices connected to any USB controller This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
in your system, no matter which qube hosts the controller. The name of the The name of the qube hosting the USB controller is displayed before the colon in the device name.
qube hosting the USB controller is displayed before the colon in the device The string after the colon is the name of the device used within the qube, like so:
name. The string after the colon is the name of the device used within the
qube, like so:
dom0:sdb1 Cruzer () 4GiB dom0:sdb1 Cruzer () 4GiB
usbVM:sdb1 Disk () 2GiB usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by **Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
calling from the qube to which the device is connected (typically `sys-usb`):
sudo udevadm trigger --action=change sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the 3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
device to a qube with the name `personal` like so:
qvm-block attach personal sys-usb:sdb qvm-block attach personal sys-usb:sdb
This will attach the device to the qube as `/dev/xvdi` if that name is not This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
already taken by another attached device, or `/dev/xvdj`, etc.
You may also mount one partition at a time by using the same command with You may also mount one partition at a time by using the same command with the partition number after `sdb`.
the partition number after `sdb`.
4. The USB drive is now attached to the qube. If using a default qube, you may 4. The USB drive is now attached to the qube.
open the Nautilus file manager in the qube, and your drive should be If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
visible in the **Devices** panel on the left. If you've attached a single If you've attached a single partition, you may need to manually mount before it becomes visible:
partition, you may need to manually mount before it becomes visible:
``` ```
cd ~ cd ~
mkdir mnt mkdir mnt
sudo mount /dev/xvdi mnt sudo mount /dev/xvdi mnt
``` ```
5. When you finish using your USB drive, click the eject button or right-click 5. When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
and select **Unmount**. If you've manually mounted a single partition If you've manually mounted a single partition in the above step, use:
in the above step, use:
`sudo umount mnt` `sudo umount mnt`
6. In a dom0 console, detach the stick 6. In a dom0 console, detach the stick
@ -236,75 +94,62 @@ follows:
### R3.2 ### ### R3.2 ###
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert USB drive mounting is integrated into the Qubes VM Manager GUI.
your USB drive, right-click on the desired qube in the Qubes VM Manager list, Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and device.
click **Attach/detach block devices**, and select your desired action and However, this only works for the whole device.
device. This, however, only works for the whole device. If you would like to If you would like to attach individual partitions, you must use the command-line tool.
attach individual partitions, you must use the command-line tool.
Note that attaching individual partitions can be slightly more secure because it doesn't Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
force the target AppVM to parse the partition table. However, it often means the However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
AppVM won't detect the new partition and you will need to manually mount it inside See below for more detailed steps.
the AppVM. See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
is `qvm-block`. This tool can be used to assign a USB drive to a qube as This tool can be used to assign a USB drive to a qube as follows:
follows:
1. Insert your USB drive. 1. Insert your USB drive.
2. In a dom0 console (running as a normal user), list all available block 2. In a dom0 console (running as a normal user), list all available block devices:
devices:
qvm-block qvm-block
This will list all available block devices connected to any USB controller This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
in your system, no matter which qube hosts the controller. The name of the The name of the qube hosting the USB controller is displayed before the colon in the device name.
qube hosting the USB controller is displayed before the colon in the device The string after the colon is the name of the device used within the qube, like so:
name. The string after the colon is the name of the device used within the
qube, like so:
dom0:sdb1 Cruzer () 4GiB dom0:sdb1 Cruzer () 4GiB
usbVM:sdb1 Disk () 2GiB usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by **Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
calling from the qube to which the device is connected (typically `sys-usb`):
sudo udevadm trigger --action=change sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the 3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
device to a qube with the name `personal` like so:
qvm-block -a personal sys-usb:sdb qvm-block -a personal sys-usb:sdb
This will attach the device to the qube as `/dev/xvdi` if that name is not This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
already taken by another attached device, or `/dev/xvdj`, etc.
You may also mount one partition at a time by using the same command with You may also mount one partition at a time by using the same command with the partition number after `sdb`.
the partition number after `sdb`. This is slightly more secure because it This is slightly more secure because it does not force the target AppVM to parse the partition table.
does not force the target AppVM to parse the partition table.
**Warning:** when working with single partitions, it is possible to assign **Warning:** when working with single partitions, it is possible to assign the same partition to multiple qubes.
the same partition to multiple qubes. For example, you could attach `sdb1` For example, you could attach `sdb1` to qube1 and then `sdb` to qube2.
to qube1 and then `sdb` to qube2. It is up to the user not to make this It is up to the user not to make this mistake.
mistake. The Xen block device framework currently does not provide an easy The Xen block device framework currently does not provide an easy way around this.
way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives Point 2 of [this comment on issue 1072][1072-comm2] gives details about this.
details about this.
4. The USB drive is now attached to the qube. If using a default qube, you may 4. The USB drive is now attached to the qube.
open the Nautilus file manager in the qube, and your drive should be If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
visible in the **Devices** panel on the left. If you've attached a single If you've attached a single partition, you may need to manually mount before it becomes visible:
partition, you may need to manually mount before it becomes visible:
``` ```
cd ~ cd ~
mkdir mnt mkdir mnt
sudo mount /dev/xvdi mnt sudo mount /dev/xvdi mnt
``` ```
5. When you finish using your USB drive, click the eject button or right-click 5. When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
and select **Unmount**. If you've manually mounted a single partition If you've manually mounted a single partition in the above step, use:
in the above step, use:
`sudo umount mnt` `sudo umount mnt`
6. In a dom0 console, detach the stick 6. In a dom0 console, detach the stick
@ -318,84 +163,69 @@ follows:
7. You may now remove the device. 7. You may now remove the device.
**Warning:** Do not remove the device before detaching it from the VM! **Warning:** Do not remove the device before detaching it from the VM!
Otherwise, you will not be able to attach it anywhere later. See issue [1082] Otherwise, you will not be able to attach it anywhere later.
for details. See issue [1082] for details.
If 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.
manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is 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).
already one device attached -- if two, `/dev/xvdk`, and so on).
### What if I removed the device before detaching it from the VM? (R3.2) ### ### What if I removed the device before detaching it from the VM? (R3.2) ###
Currently (until issue [1082] gets implemented), if you remove the device Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
think that the device is still attached to the qube and will not allow attaching If this isn't an option, you can manually recover from the situation by following these steps:
further devices under the same name. The easiest way to recover from such a
situation is to reboot the qube to which the device was attached, but if this
isn't an option, you can manually recover from the situation by following these
steps:
1. Physically connect the device back. You can use any device as long as it 1. Physically connect the device back.
will be detected under the same name (for example, `sdb`). You can use any device as long as it will be detected under the same name (for example, `sdb`).
2. Attach the device manually to the same VM using the `xl block-attach` 2. Attach the device manually to the same VM using the `xl block-attach` command.
command. It is important to use the same "frontend" device name (by default, It is important to use the same "frontend" device name (by default, `xvdi`).
`xvdi`). You can get it from the `qvm-block` listing: You can get it from the `qvm-block` listing:
[user@dom0 ~]$ qvm-block [user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi') sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
In above example, all `xl block-attach` parameters can be deduced from the In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
output of `qvm-block`. In order: In order:
* `testvm` - name of target qube to which device was attached - listed in * `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command
brackets by `qvm-block` command * `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output)
* `phy:/dev/sda` - physical path at which device appears in source qube
(just after source qube name in `qvm-block` output)
* `backend=sys-usb` - name of source qube, can be omitted in the case of dom0 * `backend=sys-usb` - name of source qube, can be omitted in the case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` * `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output)
output)
3. Now properly detach the device, either using Qubes VM Manager or the 3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command.
`qvm-block -d` command.
Attaching a single USB device to a qube (USB passthrough) Attaching a single USB device to a qube (USB passthrough)
--------------------------------------------------------- ---------------------------------------------------------
Starting with Qubes 3.2, it is possible to attach a single USB device to any Starting with Qubes 3.2, it is possible to attach a single USB device to any Qube.
Qube. While this is a useful feature, it should be used with care, because there While this is a useful feature, it should be used with care, because there are [many security implications][usb-challenges] from using USB devices and USB passthrough will **expose your target qube** to most of them.
are [many security implications][usb-challenges] from using USB devices and USB If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
passthrough will **expose your target qube** for most of them. If possible, use
a method specific for particular device type (for example block devices described
above), instead of this generic one.
### Installation of qubes-usb-proxy ### ### Installation of qubes-usb-proxy ###
[installation]: #installation-of-qubes-usb-proxy [installation]: #installation-of-qubes-usb-proxy
To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the templates used for the USB qube and qubes you want to connect USB devices to.
templates used for the USB qube and qubes you want to connect USB devices to. Note Note you cannot pass through devices from dom0 (in other words: USB VM is required).
you cannot pass through devices from dom0 (in other words: USB VM is required).
`qubes-usb-proxy` should be installed by default in the template VM. `qubes-usb-proxy` should be installed by default in the template VM.
However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
you can install the `qubes-usb-proxy` with the package manager in the VM
you want to attach the USB device to.
- Fedora: `sudo dnf install qubes-usb-proxy` - Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy` - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Usage of qubes-usb-proxy (R4.0) ### ### Usage of qubes-usb-proxy (R4.0) ###
This feature is also available from the Devices Widget. This is the tool tray This feature is also available from the Devices Widget.
icon with a yellow square located in the top right of your screen by default. This is the tool tray icon with a yellow square located in the top right of your screen by default.
Simply insert Simply insert your USB device and click on the widget.
your USB device and click on the widget. You will see an entry for your device You will see an entry for your device such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
Hover over it. Hover over it.
This will pop up a submenu showing running VMs to which the USB device can be connected. This will pop up a submenu showing running VMs to which the USB device can be connected.
Click on one and your device will be attached! You may also use the command line: Click on one and your device will be attached!
You may also use the command line:
Listing available USB devices: Listing available USB devices:
@ -414,16 +244,16 @@ Attaching selected USB device:
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Now, you can use your USB device (camera in this case) in the `conferences` qube. Now, you can use your USB device (camera in this case) in the `conferences` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
please refer to the [Installation Section][installation].
When you finish, detach the device. This can be done in the GUI by When you finish, detach the device.
clicking on the Devices Widget. You will see an entry in bold for your device This can be done in the GUI by clicking on the Devices Widget.
such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**. You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover over it. Hover over it.
This will pop up a submenu showing running VMs. The one which your device is This will pop up a submenu showing running VMs.
connected to will have an Eject button next to it. Click that and your device The one to which your device is connected will have an Eject button next to it.
will be detached. You may also use the command line: Click that and your device will be detached.
You may also use the command line:
[user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5 [user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5
[user@dom0 ~]$ qvm-usb [user@dom0 ~]$ qvm-usb
@ -450,8 +280,7 @@ Attaching selected USB device:
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Now, you can use your USB device (camera in this case) in the `conferences` qube. Now, you can use your USB device (camera in this case) in the `conferences` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
please refer to the [Installation Section][installation].
When you finish, detach the device: When you finish, detach the device:
@ -466,76 +295,62 @@ This feature is not available in Qubes Manager.
Creating and Using a USB qube Creating and Using a USB qube
----------------------------- -----------------------------
**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][2270-comm23]. **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][2270-comm23].
Connecting an untrusted USB device to dom0 is a security risk since dom0, The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically.
like almost every OS, reads partition tables automatically. The whole 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.
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. 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. 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, 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).
preventing them from coming into contact with dom0 (which could otherwise be 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).
fatal to the security of the whole system). With a USB qube, every time you 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][Assigning Devices] command.
connect an untrusted USB drive to a USB port managed by that USB controller, you For guidance on finding the correct USB controller, see [here][usb-controller].
will have to attach it to the qube in which you wish to use it (if different You can create a USB qube using the management stack by performing the following steps as root in dom0:
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][Assigning Devices] command. For guidance on finding the correct USB
controller, see [here][usb-controller].
You can create a USB qube using the management stack by performing the following
as root in dom0:
sudo qubesctl state.sls qvm.sys-usb sudo qubesctl state.sls qvm.sys-usb
Alternatively, you can create a USB qube manually as follows: Alternatively, you can create a USB qube manually as follows:
1. Read the [Assigning Devices] page to learn how to list and identify your 1. Read the [Assigning Devices] page to learn how to list and identify your USB controllers.
USB controllers. Carefully check whether you have a USB controller that Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
would be appropriate to assign to a USB qube. Note that it should have no Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
input devices, programmable devices, and any other devices that must be If you find a free controller, note its name and proceed to step 2.
directly available to dom0. If you find a free controller, note its name 2. Create a new qube.
and proceed to step 2. Give it an appropriate name and color label (recommended: `sys-usb`, red).
2. Create a new qube. Give it an appropriate name and color label If you need to attach a networking device, it might make sense to create a NetVM.
(recommended: `sys-usb`, red). If you need to attach a networking device, If not, an AppVM might make more sense.
it might make sense to create a NetVM. If not, an AppVM might make more (The default `sys-usb` is a NetVM.)
sense. (The default `sys-usb` is a NetVM.) 3. In the qube's settings, go to the "Devices" tab.
3. In the qube's settings, go to the "Devices" tab. Find the USB controller Find the USB controller that you identified in step 1 in the "Available" list.
that you identified in step 1 in the "Available" list. Move it to the Move it to the "Selected" list.
"Selected" list.
**Caution:** By assigning a USB controller to a USB qube, it will no longer **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
be available to dom0. This can make your system unusable if, for example, 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.
you have only one USB controller, and you are running Qubes off of a USB
drive.
4. Click "OK." Restart the qube. 4. Click `OK`.
5. Recommended: Check the box on the "Basic" tab which says "Start VM Restart the qube.
automatically on boot." (This will help to mitigate attacks in which 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
someone forces your system to reboot, then plugs in a malicious USB (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
device.)
If the USB qube will not start, see [here][faq-usbvm]. If the USB qube will not start, see [here][faq-usbvm].
How to hide all USB controllers from dom0 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 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).
boot process during which dom0 will be exposed to your USB controllers (and any This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised.
attached devices). This is a potential security risk, since even brief exposure There are two approaches to this problem:
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. 1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0. 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 **Warning:** If you use a USB [AEM] device, do not use the second option.
a USB AEM device requires dom0 to have access to the USB controller to which Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM If dom0 cannot read your USB AEM device, AEM will hang.
will hang.
The procedure to hide all USB controllers from dom0 is as follows: The procedure to hide all USB controllers from dom0 is as follows:
@ -556,23 +371,19 @@ The procedure to hide all USB controllers from dom0 is as follows:
4. Save and close the file. 4. Save and close the file.
5. Reboot. 5. Reboot.
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you (Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
opt to create a USB qube during installation. This also occurs automatically if This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.) first pair of steps in the linked section.)
**Warning:** A USB keyboard cannot be used to type the disk passphrase **Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
if USB controllers were hidden from dom0. Before hiding USB controllers 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).
make sure your laptop keyboard is not internally connected via USB Failure to do so will render your system unusable.
(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 Removing a USB qube
------------------- -------------------
**Warning:** This procedure will result in your USB controller(s) being attached **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
directly to dom0.
* GRUB2 * GRUB2
@ -602,7 +413,7 @@ Security Warning about USB Input Devices
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system. If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube. Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard). In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
@ -664,11 +475,9 @@ How to use a USB mouse
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB mouse, you must first attach it to a USB qube, then give that 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.
qube permission to pass mouse input to dom0. The following steps are already done by default if you created the sys-usb qube with `qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot.
The following steps are already done by default if you created the sys-usb qube with However, if you've created the USB qube manually:
`qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. However,
if you've created the USB qube manually:
Edit the `qubes.InputMouse` policy file in dom0, which is located here: Edit the `qubes.InputMouse` policy file in dom0, which is located here: