0001 ==============================================================
0002 Authorizing (or not) your USB devices to connect to the system
0003 ==============================================================
0004
0005 Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation
0006
0007 This feature allows you to control if a USB device can be used (or
0008 not) in a system. This feature will allow you to implement a lock-down
0009 of USB devices, fully controlled by user space.
0010
0011 As of now, when a USB device is connected it is configured and
0012 its interfaces are immediately made available to the users. With this
0013 modification, only if root authorizes the device to be configured will
0014 then it be possible to use it.
0015
0016 Usage
0017 =====
0018
0019 Authorize a device to connect::
0020
0021 $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
0022
0023 De-authorize a device::
0024
0025 $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
0026
0027 Set new devices connected to hostX to be deauthorized by default (ie:
0028 lock down)::
0029
0030 $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
0031
0032 Remove the lock down::
0033
0034 $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
0035
0036 By default, Wired USB devices are authorized by default to
0037 connect. Wireless USB hosts deauthorize by default all new connected
0038 devices (this is so because we need to do an authentication phase
0039 before authorizing). Writing "2" to the authorized_default attribute
0040 causes kernel to only authorize by default devices connected to internal
0041 USB ports.
0042
0043
0044 Example system lockdown (lame)
0045 ------------------------------
0046
0047 Imagine you want to implement a lockdown so only devices of type XYZ
0048 can be connected (for example, it is a kiosk machine with a visible
0049 USB port)::
0050
0051 boot up
0052 rc.local ->
0053
0054 for host in /sys/bus/usb/devices/usb*
0055 do
0056 echo 0 > $host/authorized_default
0057 done
0058
0059 Hookup an script to udev, for new USB devices::
0060
0061 if device_is_my_type $DEV
0062 then
0063 echo 1 > $device_path/authorized
0064 done
0065
0066
0067 Now, device_is_my_type() is where the juice for a lockdown is. Just
0068 checking if the class, type and protocol match something is the worse
0069 security verification you can make (or the best, for someone willing
0070 to break it). If you need something secure, use crypto and Certificate
0071 Authentication or stuff like that. Something simple for an storage key
0072 could be::
0073
0074 function device_is_my_type()
0075 {
0076 echo 1 > authorized # temporarily authorize it
0077 # FIXME: make sure none can mount it
0078 mount DEVICENODE /mntpoint
0079 sum=$(md5sum /mntpoint/.signature)
0080 if [ $sum = $(cat /etc/lockdown/keysum) ]
0081 then
0082 echo "We are good, connected"
0083 umount /mntpoint
0084 # Other stuff so others can use it
0085 else
0086 echo 0 > authorized
0087 fi
0088 }
0089
0090
0091 Of course, this is lame, you'd want to do a real certificate
0092 verification stuff with PKI, so you don't depend on a shared secret,
0093 etc, but you get the idea. Anybody with access to a device gadget kit
0094 can fake descriptors and device info. Don't trust that. You are
0095 welcome.
0096
0097
0098 Interface authorization
0099 -----------------------
0100
0101 There is a similar approach to allow or deny specific USB interfaces.
0102 That allows to block only a subset of an USB device.
0103
0104 Authorize an interface::
0105
0106 $ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
0107
0108 Deauthorize an interface::
0109
0110 $ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
0111
0112 The default value for new interfaces
0113 on a particular USB bus can be changed, too.
0114
0115 Allow interfaces per default::
0116
0117 $ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
0118
0119 Deny interfaces per default::
0120
0121 $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
0122
0123 Per default the interface_authorized_default bit is 1.
0124 So all interfaces would authorized per default.
0125
0126 Note:
0127 If a deauthorized interface will be authorized so the driver probing must
0128 be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe
0129
0130 For drivers that need multiple interfaces all needed interfaces should be
0131 authorized first. After that the drivers should be probed.
0132 This avoids side effects.
