lkml.org 
[lkml]   [2023]   [Apr]   [6]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    Subject[PATCH v10 11/11] Documentation: add USB authorization document to driver-api
    From
    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

    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
    --
    2.39.2
    \
     
     \ /
      Last update: 2023-04-06 21:02    [W:4.831 / U:0.056 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site