81 lines
2.8 KiB
Plaintext
81 lines
2.8 KiB
Plaintext
This directory contains a USB device report filter component. It filters the
|
|
device report coming from the USB driver by checking each device reported
|
|
against the given list of devices. Only approved devices are reported to a
|
|
consumer of the report coming from the filter component.
|
|
|
|
|
|
Configuration
|
|
~~~~~~~~~~~~~
|
|
|
|
A typical example configuration looks as follows:
|
|
|
|
!<config>
|
|
! <client label="component_xyz"/>
|
|
! <device vendor_id="0x13fe" product_id="0x5200"/>
|
|
! <device vendor_id="0x148f" product_id="0x2573"/>
|
|
! <device vendor_id="0x04f9" product_id="0x0051"/>
|
|
! <device vendor_id="0x1b1c" product_id="0x1a09"/>
|
|
</config>
|
|
|
|
The component that may use the devices is identified by the 'client' node.
|
|
In addition to the 'vendor_id' and 'product_id' attribute a 'device' node
|
|
can contain a 'bus' and 'dev' attribute. If these attributes are present they
|
|
have a stronger significance than the 'vendor_id' and the 'product_id'.
|
|
|
|
Whenever the 'usb_report_filter' component receives a new USB device report
|
|
from the driver it will generate a new driver configuration that contains
|
|
a policy entry for each matching device. After the driver's configuration has
|
|
been updated, the filter component will generate a new USB device report that
|
|
only contains the devices the component is allowed to access.
|
|
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
In the following example we will give a VirtualBox instance access to a
|
|
Corsair Voyager USB stick:
|
|
|
|
!<start name="usb_report_filter">
|
|
![...]
|
|
! <config>
|
|
! <client label="vbox"
|
|
! <device vendor_id="0x1b1c" product_id="0x1a09"/>
|
|
! </config>
|
|
!</start>
|
|
|
|
!<start name="report_rom">
|
|
! <resource name="RAM" quantum="1M"/>
|
|
! <provides> <service name="Report"/> <service name="ROM"/> </provides>
|
|
! <config>
|
|
! <policy label="usb_report_filter -> devices" report="usb_drv -> devices"/>
|
|
! <policy label="usb_report_filter -> usb_drv_config" report="usb_drv -> config"/>
|
|
! <policy label="vbox -> usb_devices" report="usb_report_filter -> usb_devices"/>
|
|
! </config>
|
|
!</start>
|
|
|
|
After the USB stick has been plugged in, the filter will generate the
|
|
following USB driver configuration:
|
|
|
|
!<start name="usb_drv">
|
|
![...]
|
|
! <config uhci="yes" ehci="yes" xhci="yes">
|
|
! <hid/>
|
|
! <raw>
|
|
! <report devices="yes"/>
|
|
! <policy label="vbox -> usb-1-3" vendor_id="0x1b1c" product_id="0x1a09" bus="0x0001" device="0x0003"/>
|
|
! </raw>
|
|
! </config>
|
|
!</start>
|
|
|
|
After the driver has reloaded its configuration it will send a config report
|
|
that provokes the filter component to send the following USB device report to
|
|
VirtualBox:
|
|
|
|
!<devices>
|
|
! <device label="usb-1-3" vendor_id="0x1b1c" product_id="0x1a09" bus="0x0001" device="0x0003"/>
|
|
!</device>
|
|
|
|
In return, VirtualBox will try to access the USB device. Since the configuration
|
|
of the USB driver contains a matching policy entry the access attempt will
|
|
succeed.
|