1USBAUTH(1) General Commands Manual USBAUTH(1)
2
6 usbauth - USB firewall against BadUSB attacks
7
10 udev mode, called by udev
11 usbauth udev-add
12 manual mode, called by notifier
14 usbauth allow DEVNUM PATH
15 usbauth deny DEVNUM PATH
16 PATH: path of USB interface, example /sys/bus/usb/devices/3-2/3-2:1.0/
17 DEVNUM: value of attribute, example 16 (from
18 /sys/bus/usb/devices/3-2/devnum)
19 init mode, does apply rules for all available devices
21 usbauth init
22
24 It is a firewall against BadUSB attacks.
25 A config file describes in which way USB interfaces would be accepted
26 or denied.
27 To the kernel an interface authorization was developed with this fire‐
28 wall.
29 The firewall sets the authorization mask according to the rules.
30
33 Attribute
34 [parameter operator value]
35 An attribute consists of a parameter, an operator and a value.
36 The allow/deny rule
38 allow|deny Attribute+
39 A allow/deny rule have at minimum one attribute.
40 That a allow/deny rule will enforced an USB interface must match all
41 attributes
42 Example: A rule describes all interfaces with the HID class 0x03.
43 The condition
45 condition Attribute+ case Attribute+
46 The first section describes the condition that must fulfilled.
47 The second section with the keyword case defines for what interfaces
48 the condition should apply.
49 Example:
50 All rules that describes HID interfaces should apply for two devices at
51 maximum.
52 Then the device counter must be fulfilled. The second section describes
53 the interface class 0x03.
54 There are default rules
56 allow|deny all
57 These rules for the generic case. If no other rule matches an inter‐
58 face.
59 Rules will checked top down. A rule at top could be overwritten by a
62 rule at down.
63
65 The following parameters are defined at device section
66 busnum: number of the USB bus
67 devpath: nummer of the USB port
68 idVendor: vendor ID, defines the vendor of the USB device
69 idProduct: product ID, defines the product from a vendor
70 bDeviceClass: USB device class
71 bDeviceSubClass: USB device sub class
72 bDeviceProtocol: USB device protocol
73 bConfigurationValue: current USB configuration
74 serial: serial number of the device
75 manufacturer: manufacturer of device
76 product: product name string
77 connect_type: hotplug: external USB device, direct: internal USB device
78 bcdDevice: USB protocol version
79 speed: USB speed value
80 bNumConfigurations: the number of available USB configurations
81 The following parameters are defined at configuration section
84 bNumInterfaces: Number of available interfaces in active configuration
85 bInterfaceNumber: interface number
86 bInterfaceClass: interface class
87 bInterfaceSubClass: current sub class of interface
88 bInterfaceProtocol: In case of HID devices with this value keyboards
89 (1) and mouses (2) could be distinct
90 bNumEndpoints: number of endpoints for the interface
91 The following parameters are specific and calculated internally by the
94 firewall. They are not available in the SysFS.
95 They count how much devices or interfaces matches an rule.
96 intfcount: Number of interfaces for an rule
97 devcount: Number of devices for an rule
98 The keyword anyChild could be used for a parameter to check not only
101 the own interfaces attribute, also check the silbings attribute. If one
102 silbing mathes the rule is valid.
103
106 The following operators are defined: ==, !=, <=, >=, <, >
107 With operators two values are compared. One frome the data structure of
108 a rule the other from an USB interface
109
112 Values are strings in the data strucures of the firewall.
113 At first a numeric compare is attempt. If failed a string comparement
114 will used.
115 When using double quotes it is possible to specify strings containing
116 spaces.
117
120 Default rule to allow everything:
121 allow all
122 Default rule to deny everything:
124 deny all
125 Every configuration file should allow hubs, only special cases should
127 limit these:
128 allow bDeviceClass==09 bInterfaceClass==09
129 Interfaces with device class 0 and interface class 08 (storage) will
131 accepted:
132 allow bDeviceClass==00 bInterfaceClass==08
133 allow bInterfaceClass==08
134 -> the device class is irrelevant in this case
135 Two USB storage devices will accepted at specific USB ports. Not more
137 then one storage device is allowed during a condition:
138 allow idVendor==0781 idProduct==5406 bInterfaceClass==08 busnum==3 dev‐
139 path==6
140 allow idVendor==8564 idProduct==1000 bInterfaceClass==08 busnum==3 dev‐
141 path==4
142 condition devcount<=1 case bInterfaceClass==08
143 -> the condition is valid for all interfaces from class 08. Interfaces
144 must comply with the condition for enforcing the two belonging allow
145 rules.
146 Allow two HID (example keyboard and mouse) devices at maximum
148 allow bInterfaceClass==03 devcount<=2
149 Allow only one Keyboard:
151 allow bInterfaceClass==03 anyChild bInterfaceProtocol==01 devcount<=1
152 Allow only one Mouse:
154 allow bInterfaceClass==03 bInterfaceProtocol==02 devcount<=1
155 → The parent device children of the interface would enumerated to check
156 for the attribute. If one matches the attribute then the rule will
157 enforced.
158 A keyboard should have two interfaces. The bInterfaceProtocol of the
159 first interface is "1", from the second "0". br With anyChild it is
160 possible to allow a rule matching for both interfaces. br
161 Allow only certain interfaces:
163 Example: A multi function device have three interfaces (0xFF, 0x07,
164 0x08).
165 0xFF is to scan, 0x07 is to print, and 0x08 is for storage devices con‐
166 nected to the multi function device.
167 With the following rules only the 0xFF and 0x07 interfaces are allowed.
168 The device class must be 0.
169 allow idVendor==04b8 idProduct==089e bDeviceClass==00 bInterface‐
170 Class==ff
171 allow idVendor==04b8 idProduct==089e bDeviceClass==00 bInterface‐
172 Class==07
173 USBAUTH(1)