6b94e65a95
Issue #1987 Issue #3125 |
||
---|---|---|
.. | ||
main.cc | ||
README | ||
target.mk |
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.