On Thu, Apr 06, 2023 at 02:00:30PM -0500, Allen Webb wrote: > There is a user-facing USB authorization document, but it is midding > details a driver should have developer, so add them in a new document. I'm sorry, but I can not parse this sentence :( Can you rephrase it? > Signed-off-by: Allen Webb <allenwebb@xxxxxxxxxx> > --- > .../driver-api/usb/authorization.rst | 71 +++++++++++++++++++ > Documentation/driver-api/usb/index.rst | 1 + > 2 files changed, 72 insertions(+) > create mode 100644 Documentation/driver-api/usb/authorization.rst > > diff --git a/Documentation/driver-api/usb/authorization.rst b/Documentation/driver-api/usb/authorization.rst > new file mode 100644 > index 000000000000..383dcc037a15 > --- /dev/null > +++ b/Documentation/driver-api/usb/authorization.rst > @@ -0,0 +1,71 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +==================== > +Device Authorization > +==================== > + > +This document is intended for driver developers. See > +Documentation/usb/authorization.rst if you are looking for how to use > +USB authorization. > + > +Authorization provides userspace a way to allow or block configuring > +devices early during enumeration before any modules are probed for the > +device. While it is possible to block a device by not loading the > +required modules, this also prevents other devices from using the > +module as well. For example someone might have an unattended computer > +downloading installation media to a USB drive. Presumably this computer > +would be locked to make it more difficult for a bad actor to access the > +computer. Since USB storage devices are not needed to interact with the > +lock screen, the authorized_default sysfs attribute can be set to not > +authorize new USB devices by default. A userspace tool like USBGuard > +can then vet the devices. Mice, keyboards, etc can be allowed by > +writing to their authorized sysfs attribute so that the lock screen can > +still be used (this important in cases like suspend+resume or docks) > +while other devices can be blocked as long as the lock screen is shown. > + > +Sysfs Attributes > +================ > + > +Userspace can control USB device authorization through the > +authorized_default and authorized sysfs attributes. > + > +authorized_default > +------------------ > + > +Defined in ``drivers/usb/core/hcd.c`` > + > +The authorized_default sysfs attribute is only present for host > +controllers. It determines the initial state of the authorized sysfs > +attribute of USB devices newly connected to the corresponding host > +controller. It can take on the following values: > + > ++---------------------------------------------------+ > +| Value | Behavior | > ++=======+===========================================+ > +| -1 | Authorize all devices except wireless USB | > ++-------+-------------------------------------------+ > +| 0 | Do not authorize new devices | > ++-------+-------------------------------------------+ > +| 1 | Authorize new devices | > ++-------+-------------------------------------------+ > +| 2 | Authorize new internal devices only | > ++---------------------------------------------------+ > + > +Note that firmware platform code determines if a device is internal or > +not and this is reported as the connect_type sysfs attribute of the USB > +port. This is currently supported by ACPI, but device tree still needs > +an implementation. Authorizing new internal devices only can be useful > +to work around issues with devices that misbehave if there are delays > +in probing their module. > + > +authorized > +---------- > + > +Defined in ``drivers/usb/core/sysfs.c`` > + > +Every USB device has an authorized sysfs attribute which can take the > +values 0 and 1. When authorized is 0, the device still is present in > +sysfs, but none of its interfaces can be associated with drivers and > +modules will not be probed. When authorized is 1 (or set to one) a > +configuration is chosen for the device and its interfaces are > +registered allowing drivers to bind to them. Why would a driver author care about any of this? It's all user-facing, so shouldn't it go into the other document? thanks, greg k-h
