qusal/salt/sys-usb/README.md

sys-usb

PCI handler of USB devices in Qubes OS.

Table of Contents

• Description
• Installation
  • Keyboard installation
  • AudioVM installation
  • Client installation
    • Client USB proxy installation
    • Client cryptsetup installation
    • Client CTAP installation
• Access control
• Usage
  • How to use audio devices
• Credits

Description

Setup named disposables for USB qubes. During creation, it tries to separate the USB controllers to different qubes is possible.

Installation

• Top:

sudo qubesctl top.enable sys-usb
sudo qubesctl --targets=tpl-sys-usb state.apply
sudo qubesctl top.disable sys-usb
sudo qubesctl state.apply sys-usb.appmenus

• State:

sudo qubesctl state.apply sys-usb.create
sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-usb.install
sudo qubesctl state.apply sys-usb.appmenus

Keyboard installation

If you use an USB keyboard, also run:

sudo qubesctl state.apply sys-usb.keyboard

AudioVM installation

If you plan to use disp-sys-usb as an AudioVM:

sudo qubesctl --skip-dom0 --targets=tpl-sys-usb state.apply sys-audio.install
sudo qubesctl --skip-dom0 --targets=dvm-sys-usb state.apply sys-audio.configure-dvm
qvm-tags disp-sys-usb add audiovm
qvm-features disp-sys-usb service.audiovm 1

And set the qube preference audiovm to disp-sys-usb:

qvm-prefs QUBE audiovm disp-sys-usb

Client installation

Client USB proxy installation

Install the proxy on the client template:

sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-proxy

Client cryptsetup installation

If the client requires decrypting a device, install on the client template:

sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-cryptsetup

Client CTAP installation

If the client requires a CTAP device, install on the client template:

sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-usb.install-client-fido

And enable the CTAP Proxy service for the client qubes:

qvm-features QUBE service.qubes-ctap-proxy 1

Access control

No extra services are implemented, consult upstream to learn how to use the following services:

• qubes.InputMouse, qubes.InputKeyboard, qubes.InputTablet;
• ctap.GetInfo, ctap.ClientPin, u2f.Register, u2f.Authenticate, policy.RegisterArgument.

Usage

Depending on you system, one or more USB qubes will be created to hold the different controllers. The qube names are disp-sys-usb, disp-sys-usb-left, disp-sys-usb-dock.

Start a USB qube an connect a device to it. USB PCI devices will appear on the system tray icon qui-devices. From there, assign it to the intended qube.

How to use audio devices

Bluetooth and Camera are normally integrated in laptops, but they still are USB devices internally. They will be held by (disp-)sys-usb or (disp-)sys-net, else dom0.

To use these devices, evaluate the following options:

1. Attaching the device (USB passthrough) to the audio client:

   • Advantages:
     • Easier setup as it doesn't require an AudioVM.
   • Disadvantages:
     • Increased latency;
     • Only one qube can use the device; and
     • Less secure as it exposes the Audio stack to the client.

2. Leaving devices to the AudioVM ((disp-)sys-usb as AudioVM):

   • Advantages:
     • More secure as the devices are not on the client;
     • Less latency; and
     • All audio clients will have the same audio capabilities.
   • Disadvantages:
     • Some applications might not work due to not finding the device.

3. Using video-companion to access webcam:

   • Advantages:
     • The most secure for client and server as the physical devices are unmanaged;
     • Least latency.
   • Disadvantages:
     • Can't use video-companion to screen share and share webcam at the same time; and
     • Does not cover audio.

Credits

• Unman