1==============================================================
2Authorizing (or not) your USB devices to connect to the system
3==============================================================
4
5Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation
6
7This feature allows you to control if a USB device can be used (or
8not) in a system. This feature will allow you to implement a lock-down
9of USB devices, fully controlled by user space.
10
11As of now, when a USB device is connected it is configured and
12its interfaces are immediately made available to the users.  With this
13modification, only if root authorizes the device to be configured will
14then it be possible to use it.
15
16Usage
17=====
18
19Authorize a device to connect::
20
21	$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
22
23De-authorize a device::
24
25	$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
26
27Set new devices connected to hostX to be deauthorized by default (ie:
28lock down)::
29
30	$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
31
32Remove the lock down::
33
34	$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
35
36By default, Wired USB devices are authorized by default to
37connect. Wireless USB hosts deauthorize by default all new connected
38devices (this is so because we need to do an authentication phase
39before authorizing). Writing "2" to the authorized_default attribute
40causes kernel to only authorize by default devices connected to internal
41USB ports.
42
43
44Example system lockdown (lame)
45------------------------------
46
47Imagine you want to implement a lockdown so only devices of type XYZ
48can be connected (for example, it is a kiosk machine with a visible
49USB port)::
50
51  boot up
52  rc.local ->
53
54   for host in /sys/bus/usb/devices/usb*
55   do
56      echo 0 > $host/authorized_default
57   done
58
59Hookup an script to udev, for new USB devices::
60
61 if device_is_my_type $DEV
62 then
63   echo 1 > $device_path/authorized
64 done
65
66
67Now, device_is_my_type() is where the juice for a lockdown is. Just
68checking if the class, type and protocol match something is the worse
69security verification you can make (or the best, for someone willing
70to break it). If you need something secure, use crypto and Certificate
71Authentication or stuff like that. Something simple for an storage key
72could be::
73
74 function device_is_my_type()
75 {
76   echo 1 > authorized		# temporarily authorize it
77                                # FIXME: make sure none can mount it
78   mount DEVICENODE /mntpoint
79   sum=$(md5sum /mntpoint/.signature)
80   if [ $sum = $(cat /etc/lockdown/keysum) ]
81   then
82        echo "We are good, connected"
83        umount /mntpoint
84        # Other stuff so others can use it
85   else
86        echo 0 > authorized
87   fi
88 }
89
90
91Of course, this is lame, you'd want to do a real certificate
92verification stuff with PKI, so you don't depend on a shared secret,
93etc, but you get the idea. Anybody with access to a device gadget kit
94can fake descriptors and device info. Don't trust that. You are
95welcome.
96
97
98Interface authorization
99-----------------------
100
101There is a similar approach to allow or deny specific USB interfaces.
102That allows to block only a subset of an USB device.
103
104Authorize an interface::
105
106	$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
107
108Deauthorize an interface::
109
110	$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
111
112The default value for new interfaces
113on a particular USB bus can be changed, too.
114
115Allow interfaces per default::
116
117	$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
118
119Deny interfaces per default::
120
121	$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
122
123Per default the interface_authorized_default bit is 1.
124So all interfaces would authorized per default.
125
126Note:
127  If a deauthorized interface will be authorized so the driver probing must
128  be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe
129
130For drivers that need multiple interfaces all needed interfaces should be
131authorized first. After that the drivers should be probed.
132This avoids side effects.
133