Documentation/usb/authorization.rst

   1 ==============================================================
   2 Authorizing (or not) your USB devices to connect to the system
   3 ==============================================================
   4
   5 Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation
   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
  12 its interfaces are immediately made available to the users.  With this
  13 modification, only if root authorizes the device to be configured will
  14 then it be possible to use it.
  15
  16 Usage
  17 =====
  18
  19 Authorize a device to connect::
  20
  21         $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
  22
  23 De-authorize a device::
  24
  25         $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
  26
  27 Set new devices connected to hostX to be deauthorized by default (ie:
  28 lock down)::
  29
  30         $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
  31
  32 Remove the lock down::
  33
  34         $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
  35
  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.
  39
  40
  41 Example system lockdown (lame)
  42 ------------------------------
  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
  46 USB port)::
  47
  48   boot up
  49   rc.local ->
  50
  51    for host in /sys/bus/usb/devices/usb*
  52    do
  53       echo 0 > $host/authorized_default
  54    done
  55
  56 Hookup an script to udev, for new USB devices::
  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
  69 could be::
  70
  71  function device_is_my_type()
  72  {
  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
  85  }
  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
  94
  95 Interface authorization
  96 -----------------------
  97
  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
 101 Authorize an interface::
 102
 103         $ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
 104
 105 Deauthorize an interface::
 106
 107         $ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
 108
 109 The default value for new interfaces
 110 on a particular USB bus can be changed, too.
 111
 112 Allow interfaces per default::
 113
 114         $ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
 115
 116 Deny interfaces per default::
 117
 118         $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
 119
 120 Per default the interface_authorized_default bit is 1.
 121 So all interfaces would authorized per default.
 122
 123 Note:
 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
 126
 127 For drivers that need multiple interfaces all needed interfaces should be
 128 authorized first. After that the drivers should be probed.
 129 This avoids side effects.