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