| Message ID | 20230406190030.968972-12-allenwebb@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Generate modules.builtin.alias from match ids | expand |
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@google.com> > --- > .../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
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. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index cfa8797ea614..ffe37916f99f 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -7,6 +7,7 @@ Linux USB API usb gadget anchors + authorization bulk-streams callbacks dma
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. Signed-off-by: Allen Webb <allenwebb@google.com> --- .../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