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