Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-13 00:09:47 -05:00
Code Issues Packages Projects Releases Wiki Activity

Changes requested /w obvious solution

Browse Source
This commit is contained in:
GammaSQ 2019-01-09 11:54:47 +01:00
parent f4fa25d6bf
commit 0d6f5c2248
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
6 changed files with 54 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
common-tasks/block-devices.md
View File

@ -43,11 +43,11 @@ If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linu
where `xvdi2` needs to be replaced with the partition you want to mount.
This will make your drive content accessible under `~/mnt`.
Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. <!--TODO: really? Didn't have a drive to test this quickly.-->
Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*.
If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on.
To specify this device node name, you can pass `--option frontend-dev=[custom-node-name]` to `qvm-block attach`.
To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev].
#Command Line Tool Guide
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`.
@ -60,7 +60,7 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s
qvm-block
This will list all available block devices in your system across all VMs, no matter whether hosted by a USB controller or `losetup`.
This will list all available block devices in your system across all VMs.
The name of the qube hosting the block device is displayed before the colon in the device ID.
The string after the colon is the ID of the device used within the qube, like so:
@ -95,16 +95,26 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s
qvm-block detach work sys-usb:sdb
6. You may now remove the device or attach it to another qube.
<!--TODO: what happens if USB-device removed before detaching? How about attaching a blockdevice to two qubes?-->
#Recovering From Premature Device Destruction
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
To recover from this error state, in dom0 run
virsh detach-disk targetVM xvdi
(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].)
However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device].
#Attaching a File
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
1. In the linux sourceVM run
sudo losetup /dev/loop0 /path/to/file
sudo losetup -f --show /path/to/file
(increase the trailing integer if `loop0` is already in use or use other name. This is just a generic device-id.)
[This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found.
2. If you want to use the GUI, you're done. Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube.
@ -165,4 +175,8 @@ This option accepts `cdrom` and `disk`, default is `disk`.
[device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png <!--TODO: find actual icon used in qubes!-->
[USB]:/dock/usb-devices-in-qubes-R4.0/
[frontend-dev]: #frontend-dev
[premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082
[detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm
[losetup]: https://linux.die.net/man/8/losetup
[USB]:/dock/usb-devices-in-qubes-R4.0/

19
common-tasks/device-handling.md
View File

@ -23,10 +23,7 @@ There are currently four categories of devices Qubes understands:
- USB devices
- PCI devices
Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices require the command line tool.
#Security Considerations
Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot.
#General Qubes Device Widget Behavior And Handling
When clicking on the tray icon (looking similar to this: ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
@ -40,7 +37,9 @@ Click the tray icon. Hover on a device you want to attach to a VM. A list of run
To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: ![eject icon]
##Attaching a Device to Several VMs
<!--TODO: This seems like a very bad idea, but it's possible? When would I want to do that? What are the security-implications?-->
Only `mic` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that!
#General `qvm-device` Command Line Tool Behavior
All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools.
@ -78,7 +77,7 @@ A full command consists of one DEVICE_CLASS and one action. If no action is give
Actions are applicable to every DEVICE_CLASS and expose some additional options.
###Listing Devices
The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. <!--TODO: are specified VMs searched for AVAILABLE or also attached devices? Would after `qvm-usb a work sys-usb:1-1` the command `qvm-usb l work` yield any result?-->
The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
`list` accepts two options:
@ -102,11 +101,12 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava
###Detaching Devices
The `detach` action removes an assigned device from a targetVM. It won't be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.*
`detach` accepts no options.
**SYNOPSIS**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM sourceVM:deviceID`
<!--TODO: Is sourceVM:deviceID still required? -->
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/block-devices-in-qubes-R4.0/
@ -115,4 +115,5 @@ The `detach` action removes an assigned device from a targetVM. It won't be avai
[security considerations]: /doc/device-considerations/
[device manager icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png <!--TODO: find actual icon used in qubes!-->
[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png
[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png
[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692

3
common-tasks/pci-devices.md
View File

@ -132,7 +132,6 @@ or
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
<!--TODO: Is this still needed?-->
[device handling in qubes]: /doc/device-handling/
@ -145,4 +144,4 @@ or
[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack
[ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3
[ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI
[PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough
[PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough

16
common-tasks/usb-devices.md
View File

@ -24,7 +24,7 @@ Examples for valid cases for USB-passthrough:
#Attaching And Detaching a USB Device
##With Qubes Device Manager
Click the device-manager-icon: ![device manager icon]
A list of available devices appears. USB-devices have a USB-icon to their right. <!--TODO: Where is that icon????-->
A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon]
Hover on one device to display a list of VMs you may attach it to.
@ -42,6 +42,7 @@ In dom0, you can use `qvm-usb` from the commandline to attach and detach devices
Listing available USB devices:
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
@ -50,10 +51,10 @@ Attaching selected USB device:
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
work:2-1 058f:3822 058f_USB_2.0_Camera
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to work)
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
Now, you can use your USB device (camera in this case) in the `work` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section].
@ -62,9 +63,10 @@ When you finish, detach the device.
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
#Maintenance And Customisation
@ -90,7 +92,6 @@ Mouse and keyboard setup are part of [setting up a USB-qube][keyboard setup].
##Finding The Right USB Controller
<!--TODO: This looks super old. Somebody please have a look! -->
Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
@ -131,6 +132,7 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to
[block device]: /doc/block-devices-in-qubes-R4.0/
[security considerations]: /doc/device-considerations/#usb-security
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[usb icon]: https://raw.githubusercontent.com/QubesOS/qubes-desktop-linux-manager/master/icons/22x22/generic-usb.png
[microcontroller programming]: https://www.arduino.cc/en/Main/Howto
[external audio devices]: /doc/external-audio/
[optical drives]: /doc/recording-optical-discs/
@ -141,4 +143,4 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to
[Installation Section]:#installation-of-qubes-usb-proxy
[USB-qube howto]: /doc/usb-qube-howto/
[keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login
[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/
[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/

13
configuration/usb-qube-howto.md
View File

@ -17,13 +17,7 @@ Creating and Using a USB qube
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue][2270-comm23].
The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically.
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).
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] 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][PCI Devices] command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
@ -120,9 +114,9 @@ which will ask for conformation each time a USB mouse is attached. If the file i
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:
sys-usb dom0 allow,user=root
sys-usb dom0 allow
(Change `sys-usb` to your desired USB qube.) <!--TODO: Why user=root?-->
(Change `sys-usb` to your desired USB qube.)
How to hide all USB controllers from dom0
@ -197,6 +191,7 @@ Removing a USB qube
[remove your USB-qube]: #removing-a-usb-qube
[security implications]: /doc/device-considerations/#usb-security
[enable your keyboard for login]: #enable-a-usb-keyboard-for-login
[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
[PCI Devices]: /doc/pci-devices-in-qubes-R4.0/

12
security/device-considerations.md
View File

@ -17,7 +17,8 @@ Attaching a full block device (e.g. `sda`) again offers more attack surface than
PCI Security
------------
Attaching a PCI device to a qube gives it full control of that device and is vulnerable to any bug or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.)
Attaching a PCI device to a qube has serious security implications. It exposes the device driver running in the qube to an external device (and sourceVM, which contains the device - e.g. `sys-usb`). In many cases a malicious device can choose what driver will be loaded (for example by manipulating device metadata like vendor and product identifiers) - even if the intended driver is sufficiently secure, the device may try to attack a different, less secure driver.
Furthermore that VM has full controll of the device and may be able to exploit bugs or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.)
By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.)
@ -28,7 +29,11 @@ See [Software Attacks on Intel VT-d] (page 7) for more details.
USB Security
------------
While PCI devices generally are part of your computer and thereby hard to manipulate physically, USB devices are attached all the time on the fly and thereby pose a much easier accessible attack vector.
The connection of an untrusted USB device to dom0 is a security risk since the device can attack an arbitrary USB driver (which are included in the linux kernel), exploit bugs during partition-table-parsing or simply pretend to be a keyboard. There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky][rubber duck].
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, use a [USB qube].
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues][USB security] associated with the USB-stack.
If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
@ -36,7 +41,7 @@ If possible, use a method specific for particular device type (for example, bloc
**Security Warning On USB Input Devices**
-----------------------------------------
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.<!--TODO: what's the difference? What is meant by "USB qube" vs. "fully untrusted USB qube"?-->
Because of this, the benefits of using a [USB qube] entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
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.
@ -53,6 +58,7 @@ One way to achieve this is to use a [YubiKey], or some other hardware token, or
Support for [two factor authentication][qubes u2f proxy] was recently added, though there are [issues][4661].
[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "invisiblethings blog on USB security"
[rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe
[USB qube]: /doc/usb-qube-how-to/
[YubiKey]: /doc/YubiKey/
[qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/