[v10,11/11] Documentation: add USB authorization document to driver-api

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

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