Add security discussion and installation guide for Qubes OS

Qubes-OS.md

@@ -0,0 +1,146 @@
+# FaceTimeHD on Qubes OS
+
+You can use the FaceTimeHD camera on [Qubes
+OS](https://en.wikipedia.org/wiki/Qubes_OS). However, there are some security
+considerations. The camera is not completely under the control of the host
+operating system. The camera subsystem consists of an [SoC with its own
+processor and
+memory](https://github.com/patjak/bcwc_pcie/wiki/Specification---Features),
+with similar capabilities to an IP camera, connected to the PCIe bus. It may be
+possible for the camera to be turned on remotely even when the system is
+powered off.  [The camera can be turned on independently of the green indicator
+light](https://www.usenix.org/system/files/conference/usenixsecurity14/sec14-paper-brocker.pdf).
+
+Because there is no guarantee that the camera is exclusively under the control
+of the user, it is recommended to physically cover it with tape or a sticker if
+you do not use it. If you need to use the camera, you can cover it with a
+removable sticker or elastic band so you can uncover it when you need to use
+it.
+
+When you are using the FaceTimeHD camera, remember that the application you use
+may not be the only program accessing the camera. Programs running outside of
+the OS may be accessing the camera.
+
+## Creating the Camera VM
+
+Create a qube (in this example, called "camera") which will allow applications
+to use the camera. Since the camera requires a kernel driver which you may not
+want to trust to be installed in all AppVMs created from the TemplateVM, create
+a StandaloneVM which will host the camera. Give network access to the VM so we
+can install packages. Finally, use the PCI pass-through feature to give the VM
+access to the camera. This can be configured with the "Devices" tab of the
+Qubes VM Manager, or by command line using the BDF address of the device shown
+by lspci. For example:
+
+```
+[dom0]$ lspci
+...
+03:00.0 Multimedia controller: Broadcom Corporation 720p FaceTime HD Camera
+...
+[dom0]$ qvm-pci -a camera 03:00.0
+```
+
+Now, following the instructions for [using the kernel installed in the
+VM](https://www.qubes-os.org/doc/managing-vm-kernel/#using-kernel-installed-in-the-vm),
+install support for PV GRUB2 in dom0:
+
+```
+[dom0]$ sudo qubes-dom0-update grub2-xen
+```
+
+
+In the Camera VM, update all packages, then install the package to enable VM
+kernels and grub2-tools:
+
+```
+[camera]$ sudo dnf update
+[camera]$ sudo dnf install qubes-kernel-vm-support grub2-tools
+```
+
+Install the kernel and kernel-devel packages. We need to make sure we get
+kernel-devel from the Fedora "updates" repo, so we disable other repos in this
+command:
+
+```
+[camera]$ sudo dnf install kernel kernel-devel --disablerepo="*" --enablerepo=updates
+```
+
+We need to ensure that the camera will have a sufficiently-sized Software IOMMU
+Translation Lookaside Buffer (swiotlb). This is set by a kernel parameter.
+
+Create or modify /etc/default/grub inside the Camera VM, adding the line:
+
+```
+GRUB_CMDLINE_LINUX='iommu=soft swiotlb=2048'
+```
+
+Regenerate the GRUB2 bootloader configuration:
+
+```
+[camera]$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
+```
+
+Stop the Camera VM. Using Qubes VM Manager, set the kernel of the Camera VM to
+"pvgrub2", or with the CLI tools:
+
+```
+[dom0]$ qvm-prefs camera -s kernel pvgrub2
+```
+
+Start the Camera VM and install the kernel driver according to [Getting
+Started](Get-Started).  You may have to find another way to obtain the firmware
+blob if the script is not able to download and extract it automatically.
+
+If the Camera VM does not boot normally, examine the logs with:
+
+```
+[dom0]$ sudo xl console camera
+```
+
+If the u2mfn kernel module is not found, the package may have failed to install
+it automatically. Install it manually with:
+
+```
+[camera]$ cd /usr/src/u2mfn-3.2.2/
+[camera]$ dkms autoinstall
+```
+
+## Loading the driver
+
+You will need to execute the following steps every time you start the Camera
+VM.
+
+Identify the BDF address of the camera with lspci. For example:
+
+```
+[dom0]$ lspci
+...
+03:00.0 Multimedia controller: Broadcom Corporation 720p FaceTime HD Camera
+...
+```
+
+Start the Camera VM. Before loading the kernel driver, put the device into
+permissive mode on dom0:
+
+```
+[dom0]$ echo 0000:03:00.0 > /sys/bus/pci/drivers/pciback/permissive
+```
+
+Load the driver:
+
+```
+[camera]$ sudo modprobe facetimehd
+```
+
+You can now launch an application that accesses the camera.
+
+If you get an error in dmesg when an application accesses the camera:
+
+```
+facetimehd 0000:00:00.0: swiotlb buffer is full
+```
+
+This may be due to [memory
+fragmentation](https://github.com/QubesOS/qubes-issues/issues/1038) causing the
+swiotlb buffer to be allocated in noncontiguous memory. You might try rebooting
+and making sure the Camera VM is started earlier.