1USBAUTH(8) System Manager's Manual USBAUTH(8)
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 /sys/bus/usb/de‐
18 vices/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 The configured value will be compared with the default value type from
113 sysfs.
114 If not specified the type of the configured value is assumed to be in
115 sysfs value type.
116 Using \x as value prefix will set the configured value type as hexadec‐
117 imal.
118 Using \d as value prefix will set the configured value type as decimal.
119 With an explicit integer value a type conversion will be done if the
120 value type does not match the sysfs value type.
121 Using double quotes for the configured value foces a string comparisa‐
122 tion. It allows to specify strings containing spaces, too.
123 Point separated integer values like 1.2.3 (e.g. for devpath) are possi‐
124 ble, they allow also explicit type prefixing like \x1.2.3
125
128 Default rule to allow everything:
129 allow all
130 Default rule to deny everything:
132 deny all
133 Every configuration file should allow hubs, only special cases should
135 limit these:
136 allow bDeviceClass==09 bInterfaceClass==09
137 Interfaces with device class 0 and interface class 08 (storage) will
139 accepted:
140 allow bDeviceClass==00 bInterfaceClass==08
141 allow bInterfaceClass==08
142 -> the device class is irrelevant in this case
143 Two USB storage devices will accepted at specific USB ports. Not more
145 then one storage device is allowed during a condition:
146 allow idVendor==0781 idProduct==5406 bInterfaceClass==08 busnum==3 dev‐
147 path==6
148 allow idVendor==8564 idProduct==1000 bInterfaceClass==08 busnum==3 dev‐
149 path==4
150 condition devcount<=1 case bInterfaceClass==08
151 -> the condition is valid for all interfaces from class 08. Interfaces
152 must comply with the condition for enforcing the two belonging allow
153 rules.
154 Allow two HID (example keyboard and mouse) devices at maximum
156 allow bInterfaceClass==03 devcount<=2
157 Allow only one Keyboard:
159 allow bInterfaceClass==03 anyChild bInterfaceProtocol==01 devcount<=1
160 Allow only one Mouse:
162 allow bInterfaceClass==03 bInterfaceProtocol==02 devcount<=1
163 → The parent device children of the interface would enumerated to check
164 for the attribute. If one matches the attribute then the rule will en‐
165 forced.
166 A keyboard should have two interfaces. The bInterfaceProtocol of the
167 first interface is "1", from the second "0". br With anyChild it is
168 possible to allow a rule matching for both interfaces. br
169 Allow only certain interfaces:
171 Example: A multi function device have three interfaces (0xFF, 0x07,
172 0x08).
173 0xFF is to scan, 0x07 is to print, and 0x08 is for storage devices con‐
174 nected to the multi function device.
175 With the following rules only the 0xFF and 0x07 interfaces are allowed.
176 The device class must be 0.
177 allow idVendor==04b8 idProduct==089e bDeviceClass==00 bInterface‐
178 Class==ff
179 allow idVendor==04b8 idProduct==089e bDeviceClass==00 bInterface‐
180 Class==07
181 USBAUTH(8)