神刀安全网

WebUSB API: draft spec to safely expose USB device services to the web

This document describes an API for direct access to Universal Serial Bus devices from web pages.

Introduction

The Universal Serial Bus (USB) is the de-facto standard for wired peripherals. Most USB devices implement one of roughly a dozen standard "device classes" which specify a way for the device to advertize the features it supports and commands and data formats for using those features. Standard device classes include keyboard, mice, audio, video and storage devices. Operating systems support such devices using the "class driver" provided by the OS vendor. There is however a long tail of devices that do not fit into one of the standardized device classes. These devices require hardware vendors to write native drivers and SDKs in order for developers to take advantage of them and this native code prevents these devices from being used by the web.

The WebUSB API provides a way to safely expose USB device services to the web. It provides an API familiar to developers who have used existing native USB libraries and exposes the device interfaces defined by existing specifications. With this API hardware manufacturers will have the ability to build cross-platform JavaScript SDKs for their devices. This will be good for the web because, instead of waiting for a new kind of device to be popular enough for browsers to provide a specific API, new and innovative hardware can be built for the web from day one.

Security and Privacy Considerations

USB hosts and devices historically trust each other. There are published attacks against USB devices that will accept unsigned firmware updates. These vulnerabilities permit an attacker to gain a foothold in the device and attack the original host or any other host to which they are later connected. For this reason WebUSB does not attempt to provide a mechanism for any web page to connect to arbitrary devices.

Direct access to peripherals also poses a privacy risk. Knowing the make and model of connected devices provides additional bits of entropy for fingerprinting. If devices also posess some form of serial number then they can be uniquely identifying. Additionally a device may have access to data about its environment or directly store user data.

For this reason this specification outlines two mechanisms that can be combined by the UA before a site is granted access to a device. First, so that the device can protect itself from malicious sites it can provide a set of origins that are allowed to connect to it. These are similar to the [[CORS]] mechanism and can conceptually be thought of as treating USB devices as their own origins in the "usb" scheme. For devices manufacturered before this specificiation is adopted information about allowed origins and landing pages can also be provided out of band by being published in a public registry. Second, so that the user’s privacy is protected the UA may prompt the user for authorization to allow a site to detect the presense of a device and connect to it.

To help ensure that only the entity the user approved for access actually has access, this specification requires that only secure contexts as described in [[powerful-features]] can access USB devices.

WebUSB Descriptors and Requests

This specification defines descriptors and commands the UA MAY use to gather information about the device specific to implementing this API.

WebUSB Platform Capability Descriptor

A device announces support for the WebUSB command set by including the following Platform Descriptor in its Binary Object Store :

Offset Field Size Value Description
0 bLength 1 Number Size of this descriptor. Must be set to 24.
1 bDescriptorType 1 Constant DEVICE CAPABILITY descriptor type ([[USB31]] Table 9-6).
2 bDevCapabilityType 1 Constant PLATFORM capability type ([[USB31]] Table 9-14).
3 bReserved 1 Number This field is reserved and shall be set to zero.
4 PlatformCapabilityUUID 16 UUID Must be set to {3408b638-09a9-47a0-8bfd-a0768815b665}.
20 bcdVersion 2 BCD Protocol version supported. Must be set to 0x0100.
22 bVendorCode 1 Number bRequest value used for issuing WebUSB requests.
23 iLandingPage 1 Number URL descriptor index of the device’s landing page.

WebUSB Device Requests

All control transfers defined by this specification are considered to be vendor-specific requests. The bVendorCode value found in the WebUSB Platform Capability Descriptor provides the UA with the bRequest the device expects the host to use when issuing control transfers these requests. The request type is then specified in the wIndex field.

WebUSB Request Codes
Constant Value
GET_ALLOWED_ORIGINS 1
GET_URL 2

Get Allowed Origins

This request gets the set of origins allowed to access the device. It is analogous to the Access-Control-Allow-Origin header defined by [[CORS]].

The device MUST respond with data beginning with a Allowed Origins Header or stall the transfer.

A URL descriptor referenced by the response MUST be interpreted as an origin (as defined by [[RFC6454]]) and so content beyond the scheme/host/port triple MUST be ignored.

If the UA chooses to enforce this policy then an origin is allowed to access a device if it matches one of the origins in the top-level Allowed Origins Header or any descriptors following it. An origin is allowed to access a configuration if it matches one of the origins in the corresponding Configuration Subset Header or in the top-level Allowed Origins Header . An origin is allowed to access an interface if it matches one of the origins in the corresponding Function Subset Header , the Configuration Subset Header containing it or the top-level Allowed Origins Header .

bmRequestType bRequest wValue wIndex wLength Data
11000000B bVendorCode Zero GET_ALLOWED_ORIGINS Descriptor Length Descriptor

Get URL

This request fetches the URL descriptor with the given index.

The device MUST respond with the URL Descriptor at the given index or stall the transfer if the index is invalid.

bmRequestType bRequest wValue wIndex wLength Data
11000000B bVendorCode Descriptor Index GET_URL Descriptor Length Descriptor

WebUSB Descriptors

These descriptor types are returned by requests defined in this specification.

WebUSB Descriptor Types
Constant Value
WEBUSB_DESCRIPTOR_SET_HEADER 0
WEBUSB_CONFIGURATION_SUBSET_HEADER 1
WEBUSB_FUNCTION_SUBSET_HEADER 2
WEBUSB_URL 3

Allowed Origins Header

This header lists the set of origins allowed to access the entire USB device. It MUST be followed by bNumConfigurations configuration subset headers that control permission to access particular configurations.

This descriptor MUST be the beginning of the response to the Get Allowed Origins request. wTotalLength MUST be the total length of the response.

Offset Field Size Value Description
0 bLength 1 Number Size of this descriptor. Must be set to N + 5 .
1 bDescriptorType 1 Constant WEBUSB_DESCRIPTOR_SET_HEADER.
2 wTotalLength 2 Number Total size of this and all following descriptors.
4 bNumConfigurations 1 Number Number of configuration subset headers following this descriptor.
5 iOrigin[ N ] N × 1 Number Set of bLength - 5 URL descriptor indicies.

Configuration Subset Header

This header lists the set of origins allowed to access the USB device configuration described by the configuration descriptor with the given bConfigurationValue . It MUST be followed by bNumFunctions function subset headers that control permission to access functions within this configuration.

This descriptor MUST follow a Allowed Origins Header .

Offset Field Size Value Description
0 bLength 1 Number Size of this descriptor. Must be set to N + 4 .
1 bDescriptorType 1 Constant WEBUSB_CONFIGURATION_SUBSET_HEADER.
2 bConfigurationValue 1 Number Configuration to which this section applies.
3 bNumFunctions 1 Number Number of function subset headers following this descriptor.
4 iOrigin[ N ] N × 1 Number Set of bLength - 4 URL descriptor indicies.

Function Subset Header

This header lists the set of origins allowed to access the USB device interface described by the interface descriptor with a bInterfaceNumber equal to bFirstInterfaceNumber or the set of interfaces defined as a function by an interface association descriptor with an equal bFirstInterfaceNumber .

This descriptor MUST follow a Configuration Subset Header .

WebUSB Function Subset Header
Offset Field Size Value Description
0 bLength 1 Number Size of this descriptor. Must be set to N + 3 .
1 bDescriptorType 1 Constant WEBUSB_FUNCTION_SUBSET_HEADER.
2 bFirstInterfaceNumber 1 Number First interface of the function to which this section applies.
3 iOrigin[ N ] N × 1 Number Set of bLength - 3 URL descriptor indicies.

URL Descriptor

This descriptor contains a single URL and is returned by the Get URL request.

Offset Field Size Value Description
0 bLength 1 Number Size of this descriptor.
1 bDescriptorType 1 Constant WEBUSB_URL.
2 bScheme 1 Number URL scheme prefix.
3 URL Variable String UTF-8 encoded URL (excluding the scheme prefix).

The bScheme field MUST be one of these values:

URL Prefixes
Value Prefix
0 "http://"
1 "https://"

Public Device Registry

The WebUSB Platform Capability Descriptor and descriptors returned by the requests defined above can be elided by publishing this information in a public registry of supported USB devices. This will allow device manufacturers to support WebUSB on existing devices.

Device Enumeration

dictionary USBDeviceFilter {           unsigned short vendorId;           unsigned short productId;           octet classCode;           octet subclassCode;           octet protocolCode;         };          dictionary USBDeviceRequestOptions {           required sequence<USBDeviceFilter> filters;         };          [NoInterfaceObject]         interface USB {           attribute EventHandler onconnect;           attribute EventHandler ondisconnect;           Promise<sequence<USBDevice>> getDevices();           Promise<USBDevice> requestDevice(USBDeviceRequestOptions options);         };         USB implements EventTarget;          partial interface Navigator {           readonly attribute USB usb;         };

The vendorId and productId field will cause the filter to match any device with the given vendor and (optionally) product identifiers.

The classCode , subclassCode and protocolCode fields will cause the filter to match any device that implements the given class, class and subclass, or class, subclass and protocol tuple and any composite device with an interface implementing the same. A subclass MUST NOT be specified unless a class is provided and a protocol MUST NOT be specified unless a subclass is also provided.

The UA MUST be able to enumerate all devices attached to the system . It is, however NOT required to perform this work each time an algorithm requests an enumeration. The UA MAY cache the result of the first enumeration it performs and then begin monitoring for device connection and disconnection events, adding connected devices to its cached enumeration and removing disconnected devices. This mode of operation is preferred as it reduces the number of operating system calls made and amount of bus traffic generated by the getDevices() and requestDevice() methods.

The UA MUST maintain an allowed devices set for each script execution environment. Once a device is added to this set it SHALL remain in the set for a period of time determined by the UA’s ability to identify the device.

  • For a device with a unique identifier such as a serial number or container ID the device SHALL remain in the allowed devices set until explicitly removed by the user. Vendor and product IDs MUST NOT be considered uniquely identifying.
  • For a device without a unique identifier the device SHALL remain in the allowed devices set until it becomes uncertain whether the device connected to the host is still the device originally added to the set. This MAY happen when the device is disconnected from the host, when the UA exits or, if tracked by the host operating system, when the host is shut down.

The onconnect attribute is an Event handler IDL attribute for the connect event type.

The ondisconnect attribute is an Event handler IDL attribute for the disconnect event type.

The getDevices() method, when invoked, MUST return a new promise and run the following steps in parallel:

  1. If the incumbent settings object is not a secure context, reject promise with a SecurityError and abort these steps.
  2. Enumerate all devices attached to the system . Let this result be enumerationResult .
  3. Remove all devices from enumerationResult that are not in the current script execution environment’s allowed devices set .
  4. For each remaining device in enumerationResult get the USBDevice object representing device , and add the result to devices .
  5. Resolve promise with devices .

The requestDevice(options) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the incumbent settings object is not a secure context, reject promise with a SecurityError and abort these steps.
  2. If the algorithm is not allowed to show a popup, reject promise with a SecurityError and abort these steps.
  3. Enumerate all devices attached to the system . Let this result be enumerationResult .
  4. Remove all devices from enumerationResult that do not match at least one of the filters in options.filters

    .

    The UA MAY apply additional origin-based filtering of available devices by consulting an authoritative list of device-origin mappings or referring to the origin list returned by the Get Allowed Origins request.

    The UA MAY provide additional mechanisms for blacklisting or whitelisting specific devices for arbitrary origins.

  5. Even if enumerationResult is empty, display a prompt to the user requesting that the user select a device from it. The UA SHOULD show a human-readable name of each device.
  6. Wait for the user to have selected a device or cancelled the prompt.
  7. If the user cancels the prompt, reject promise with a NotFoundError and abort these steps.
  8. Add device to the current script execution environment’s allowed devices set .
  9. Get the USBDevice object representing device and resolve promise with that object.

Events

interface USBConnectionEvent : Event {             readonly attribute USBDevice device;           };

When the UA detects a new USB device connected to the host it MUST perform the following steps for each script execution environment:

  1. Let device be the USBDevice object representing the device.
  2. If device is not in the allowed devices set for the current script execution environment abort these steps.
  3. Let event be a new USBConnectionEvent , with the device attribute set to device .
  4. Fire an event named connect on navigator.usb , using event as the event object.

When the UA detects a previously connected USB device has been disconnected from the host it MUST perform the following steps for each script execution environment:

  1. Let device be the USBDevice object representing the device.
  2. If device is not in the allowed devices set for the current script execution environment abort these steps.
  3. Let event be a new USBConnectionEvent , with the device attribute set to device .
  4. Fire an event named disconnect on navigator.usb , using event as the event object.
  5. Consider removing device from the allowed devices set .

Device Usage

interface USBDevice {           readonly attribute DOMString guid;           readonly attribute octet usbVersionMajor;           readonly attribute octet usbVersionMinor;           readonly attribute octet usbVersionSubminor;           readonly attribute octet deviceClass;           readonly attribute octet deviceSubclass;           readonly attribute octet deviceProtocol;           readonly attribute unsigned short vendorId;           readonly attribute unsigned short productId;           readonly attribute octet deviceVersionMajor;           readonly attribute octet deviceVersionMinor;           readonly attribute octet deviceVersionSubminor;           readonly attribute DOMString? manufacturerName;           readonly attribute DOMString? productName;           readonly attribute DOMString? serialNumber;           readonly attribute USBConfiguration? configuration;           readonly attribute FrozenArray<USBConfiguration> configurations;           readonly attribute boolean opened;           Promise<void> open();           Promise<void> close();           Promise<void> selectConfiguration(octet configurationValue);           Promise<void> claimInterface(octet interfaceNumber);           Promise<void> releaseInterface(octet interfaceNumber);           Promise<void> selectAlternateInterface(octet interfaceNumber, octet alternateSetting);           Promise<USBInTransferResult> controlTransferIn(USBControlTransferParameters setup, unsigned short length);           Promise<USBOutTransferResult> controlTransferOut(USBControlTransferParameters setup, optional BufferSource data);           Promise<void> clearHalt(octet endpointNumber);           Promise<USBInTransferResult> transferIn(octet endpointNumber, unsigned long length);           Promise<USBOutTransferResult> transferOut(octet endpointNumber, BufferSource data);           Promise<USBIsochronousInTransferResult> isochronousTransferIn(octet endpointNumber, sequence<unsigned long> packetLengths);           Promise<UsbIsochronousOutTransferResult> isochronousTransferOut(octet endpointNumber, BufferSource data, sequence<unsigned long> packetLengths);           Promise<void> reset();         };

The guid attribute indicates a unique identifier string for the device. This identifier SHALL remain consistent for the lifetime of a device’s connection to the USB host.

The usbVersionMajor , usbVersionMinor and usbVersionSubminor attributes declare the USB protocol version supported by the device. They SHALL correspond to the value of the bcdUSB field of the device descriptor such that a value of 0xJJMN has major version JJ , minor version M and subminor version N .

The deviceClass , deviceSubclass and deviceProtocol attributes declare the communication interface supported by the device. They MUST correspond respectively to the values of the bDeviceClass , bDeviceSubClass and bDeviceProtocol fields of the device descriptor .

The vendorId and productId attribute declares the vendor ID of the device manufacturer and product ID assigned by the device manufacturer. They SHALL correspond to the values of the idVendor and idProduct fields of the device descriptor .

The deviceVersionMajor , deviceVersionMinor and deviceVersionSubminor attributes declare the device release number as defined by the device manufacturer. It SHALL correspond to the value of the bcdDevice field of the device descriptor such that a value of 0xJJMN has major version JJ , minor version M and subminor version N .

The configuration attribute contains the currently selected configuration for the device and SHALL be one of the configurations listed in configurations . It MAY be null if the device is in an unconfigured state and MUST be updated by selectConfiguration .

The configurations attribute contains a list of configurations supported by the device. These configurations SHALL be populated from the configuration descriptors reported by the device and the number of elements in this list SHALL match the value of the bNumConfigurations field of the device descriptor .

The manufacturerName , productName and serialNumber attributes SHOULD contain the values of the string descriptors referenced by the iManufacturer , iProduct and iSerialNumber fields of the device descriptor if each is available.

The open() method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. If device.opened is true resolve promise and abort these steps.
  4. Perform the necessary platform-specific steps to begin a session with the device. If these fail for any reason reject promise with a NetworkError and abort these steps.
  5. Set device.opened to true and resolve promise .

The close() method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. If device.opened is false resolve promise and abort these steps.
  4. Abort all other algorithms currently running against this device and reject their associated promises with an AbortError .
  5. Perform the necessary platform-specific steps to release any claimed interfaces as if releaseInterface(interfaceNumber) had been called for each claimed interface.
  6. Perform the necessary platform-specific steps to end the session with the device.
  7. Set device.opened to false and resolve promise .

The selectConfiguration(configurationValue) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. Let configuration be the device configuration with bConfigurationValue equal to configurationValue . If no such configuration exists, reject promise with a NotFoundError and abort these steps.
  4. If device.opened is not equal to true reject promise with an InvalidStateError and abort these steps.
  5. The UA MAY check that the caller is allowed to access configuration , and if not reject promise with a SecurityError and abort these steps.
  6. Abort all transfers currently scheduled on endpoints other than the default control pipe and reject their associated promises with a AbortError .
  7. Issue a SET_CONFIGURATION control transfer to the device to set configurationValue as its active configuration . If this step fails reject promise with a NetworkError and abort these steps.
  8. Set device.configuration to configuration and resolve promise .

The claimInterface(interfaceNumber) method, when invoked, MUST return a new promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber . If no such interface exists, reject promise with a NotFoundError and abort these steps.
  3. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  4. The UA MAY check that the caller is allowed to access interface , and if not reject promise with a SecurityError and abort these steps.
  5. Perform the necessary platform-specific steps to request exclusive control over interface . If this fails, reject promise with a NetworkError and abort these steps.
  6. Set interface.claimed to true and resolve promise .

The releaseInterface(interfaceNumber) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber . If no such interface exists, reject promise with a NotFoundError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. Perform the necessary platform-specific steps to reliquish exclusive control over interface .
  6. Set interface.claimed to false and resolve promise .

The selectAlternateInterface(interfaceNumber, alternateSetting) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber . If no such interface exists, reject promise with a NotFoundError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. Abort all transfers currently scheduled on endpoints associated with the previously selected alternate setting of interface and reject their associated promises with a AbortError .
  6. Issue a SET_INTERFACE control transfer to the device to set alternateSetting as the current configuration of interface . If this step fails reject promise with a NetworkError and abort these steps.
  7. Resolve promise .

The controlTransferIn(setup, length) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. If device.opened is not equal to true reject promise with an InvalidStateError and abort these steps.
  4. Check the validity of the control transfer parameters and abort these steps if promise is rejected.
  5. If length is greater than the wMaxPacketSize0 field of the device’s device descriptor , reject promise with a TypeError and abort these steps.
  6. Let result be a new USBInTransferResult and let buffer be a new ArrayBuffer of length bytes.
  7. Issue a control transfer with the setup packet parameters provided in setup and the data transfer direction in bmRequestType set to "device to host" and wLength set to length .
  8. If the device responds with data, store the first length bytes of this data in buffer and set result.data to a new DataView constructed over buffer .
  9. If the device responds by stalling the default control pipe set result.status to "stall" .
  10. If more than length bytes are received set result.status to "babble" and otherwise set it to "ok" .
  11. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  12. Resolve promise with result .

The controlTransferOut(setup, data) method, when invoked, must return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. If device.opened is not equal to true reject promise with an InvalidStateError and abort these steps.
  3. Check the validity of the control transfer parameters and abort these steps if promise is rejected.
  4. If data.length is greater than the wMaxPacketSize0 field of the device’s device descriptor , reject promise with a TypeError and abort these steps.
  5. Issue a control transfer with the setup packet populated by setup and the data transfer direction in bmRequestType set to "host to device" and wLength set to data.length . Transmit data in the data stage of the transfer.
  6. Let result be a new USBOutTransferResult .
  7. If the device responds by stalling the default control pipe set result.status to "stall" .
  8. If the device acknowledges the transfer set result.status to "ok" and result.bytesWritten to data.length .
  9. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  10. Resolve promise with result .

The clearHalt(direction, endpointNumber) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let endpoint be the endpoint in the active configuration with bEndpointAddress corresponding to direction and endpointNumber . If no such endpoint exists reject promise and abort these steps.
  3. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  4. Issue a CLEAR_FEATURE control transfer to the device to clear the stall condition on endpoint .
  5. On failure reject promise with a NetworkError , otherwise resolve promise .

The transferIn(endpointNumber, length) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let endpoint be the IN endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber . If there is no such endpoint reject promise with a NotFoundError and abort these steps.
  3. If endpoint is not a bulk or interrupt endpoint reject promise with an InvalidAccessError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. As appropriate for endpoint enqueue a bulk or interrupt IN transfer on endpoint with a buffer sufficient to receive length bytes of data from the device.
  6. Let result be a new USBInTransferResult .
  7. If data is returned as part of this transfer let buffer be a new ArrayBuffer of exactly the length of the data received and set result.data to a new DataView constructed over buffer .
  8. If the device responds with more than length bytes of data set result.status to "babble" .
  9. If the transfer ends because endpoint is stalled set result.status to "stall" .
  10. If the device acknowledges the complete transfer set result.status to "ok" .
  11. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  12. Resolve promise with result .

The transferOut(endpointNumber, data) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let endpoint be the OUT endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber . If there is no such endpoint reject promise with a NotFoundError and abort these steps.
  3. If endpoint is not a bulk or interrupt endpoint reject promise with an InvalidAccessError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. As appropriate for endpoint enqueue a bulk or interrupt OUT transfer on endpoint to transmit data to the device.
  6. Let result be a new USBOutTransferResult .
  7. Set result.bytesWritten to the amount of data successfully sent to the device.
  8. If the endpoint is stalled set result.status to "stall" .
  9. If the device acknowledges the complete transfer set result.status to "ok" .
  10. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  11. Resolve promise with result .

The isochronousTransferIn(endpointNumber, packetLengths) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let endpoint be the IN endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber . If there is no such endpoint reject promise with a NotFoundError and abort these steps.
  3. If endpoint is not an isochronous endpoint reject promise with an InvalidAccessError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. Let length be the sum of the elements of packetLengths .
  6. Let buffer be a new ArrayBuffer of length bytes.
  7. Let result be a new USBIsochronousInTransferResult and set result.data to a new DataView constructed over buffer .
  8. Enqueue an isochronous IN transfer on endpoint that will write up to length bytes of data from the device into buffer .
  9. For each packet i from 0 to packetLengths.length – 1 :
    1. Let packet be a new USBIsochronousInTransferPacket and set result.packets[i] to packet .
    2. Let view be a new DataView over the portion of buffer containing the data received from the device for this packet and set packet.data to view .
    3. If the device responds with more than packetLengths[i] bytes of data set packet.status to "babble" .
    4. If the transfer ends because endpoint is stalled set packet.status to "stall" .
    5. If the device acknowledges the complete transfer set packet.status to "ok" .
    6. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  10. Resolve promise with result .

The isochronousTransferOut(endpointNumber, data, packetLengths) method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  2. Let endpoint be the OUT endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber . If there is no such endpoint reject promise with a NotFoundError and abort these steps.
  3. If endpoint is not an isochronous endpoint reject promise with an InvalidAccessError and abort these steps.
  4. If device.opened or interface.claimed is not true , reject promise with an InvalidStateError and abort these steps.
  5. Let length be the sum of the elements of packetLengths .
  6. Let result be a new USBIsochronousOutTransferResult .
  7. Enqueue an isochronous OUT transfer on endpoint that will write buffer to the device, divided into packetLength.length packets of packetLength[i] bytes (for packets i from 0 to packetLengths.length – 1 ).
  8. For each packet i from 0 to packetLengths.length – 1 the host attempts to send to the device:
    1. Let packet be a new USBIsochronousOutTransferPacket and set result.packets[i] to packet .
    2. Let packet.bytesWritten be the amount of data successfully sent to the device as part of this packet.
    3. If the transfer ends because endpoint is stalled set packet.status to "stall" .
    4. If the device acknowledges the complete transfer set packet.status to "ok" .
    5. If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
  9. Resolve promise with result .

The reset() method, when invoked, MUST return a new promise promise and run the following steps in parallel:

  1. Let device be the target USBDevice object.
  2. If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
  3. If device.opened is not equal to true reject promise with an InvalidStateError and abort these steps.
  4. Abort all operations on the device and reject their associated promises with an AbortError .
  5. Perform the necessary platform-specific operation to soft reset the device.
  6. On failure reject promise with a NetworkError , otherwise resolve promise .
  7. What configuration is the device in after it resets?

Transfers

enum USBRequestType {             "standard",             "class",             "vendor"           };            enum USBRecipient {             "device",             "interface",             "endpoint",             "other"           };            enum USBTransferStatus {             "ok",             "stall",             "babble"           };            dictionary USBControlTransferParameters {             required USBRequestType requestType;             required USBRecipient recipient;             required octet request;             required unsigned short value;             required unsigned short index;           };            interface USBInTransferResult {             readonly attribute DataView data;             readonly attribute USBTransferStatus status;           };            interface USBOutTransferResult {             readonly attribute unsigned long bytesWritten;             readonly attribute USBTransferStatus status;           };            interface USBIsochronousInTransferPacket {             readonly attribute DataView data;             readonly attribute USBTransferStatus status;           };            interface USBIsochronousInTransferResult {             readonly attribute DataView data;             readonly attribute FrozenArray<USBIsochronousInTransferPacket> packets;           };            interface USBIsochronousOutTransferPacket {             readonly attribute unsigned long bytesWritten;             readonly attribute USBTransferStatus status;           };            interface USBIsochronousOutTransferResult {             readonly attribute FrozenArray<USBIsochronousOutTransferPacket> packets;           };

A control transfer is a special class of USB traffic most commonly used for configuring a device. It consists of three stages: setup, data and status. In the setup stage a setup packet is transmitted to the device containing request parameters including the transfer direction and size of the data to follow. In the data stage that data is either sent to or received from the device. In the status stage successful handling of the request is acknowledged or a failure is signaled.

All USB devices MUST have a default control pipe which is endpointNumber 0 .

The requestType attribute populates part of the bmRequestType field of the setup packet to indicate whether this request is part of the USB standard, a particular USB device class specification or a vendor-specific protocol.

The recipient attribute populates part of the bmRequestType field of the setup packet to indicate whether the control transfer is addressed to the entire device, or a specific interface or endpoint.

The request attribute populates the bRequest field of the setup packet . Valid requests are defined by the USB standard, USB device class specifications or the device vendor.

The value and index attributes populate the wValue and wIndex fields of the setup packet respectively. The meaning of these fields depends on the request being made.

To check the validity of the control transfer parameters perform the following steps:

  1. Let setup be the USBControlTransferParameters created for the transfer.
  2. Let promise be the promise created for the transfer.
  3. Let configuration be the active configuration . If the device is not configured abort these steps.
  4. If setup.recipient is "device" or "other" the UA MAY check that the caller is allowed to access configuration , and if not reject promise with a SecurityError and abort these steps.
  5. If setup.recipient is "interface" , perform the following steps:
    1. Let interfaceNumber be the lower 8 bits of setup.wIndex .
    2. Let interface be the interface in the configuration with bInterfaceNumber equal to interfaceNumber . If no such interface exists, reject promise with a NotFoundError and abort these steps.
    3. If interface.claimed is not equal to true , reject promise with an InvalidStateError and abort these steps.
    4. The UA MAY check that the caller is allowed to access interface , and if not reject promise with a SecurityError .
  6. If setup.recipient is "endpoint" , run the following steps:
    1. Let endpointNumber be defined as the lower 4 bits of setup.wIndex .
    2. Let direction be defined as "in" if the 8th bit of setup.wIndex is 1 and "out" otherwise.
    3. Let endpoint be the endpoint in the active configuration with bEndpointAddress corresponding to direction and endpointNumber . If no such endpoint exists, reject promise with a NotFoundError and abort these steps.
    4. Let interface be the interface in which endpoint is defined. If interface.claimed is not equal to true , reject promise with an InvalidStateError .
    5. The UA MAY check that the caller is allowed to access interface , and if not reject promise with a SecurityError .

Configurations

[Constructor(USBDevice device, octet configurationValue)]           interface USBConfiguration {             readonly attribute octet configurationValue;             readonly attribute DOMString? configurationName;             readonly attribute FrozenArray<USBInterface> interfaces;           };

Each device configuration SHALL have a unique configurationValue that matches the bConfigurationValue fields of the configuration descriptor that defines it.

The configurationName attribute SHOULD contain the value of the string descriptor referenced by the iConfiguration field of the configuration descriptor , if available.

The interfaces attribute SHALL contain a list of interfaces exposed by this device configuration. These interfaces SHALL by populated from the interface descriptors contained within this configuration descriptor .

Include some non-normative information about device configurations

Interfaces
[Constructor(USBConfiguration configuration, octet interfaceNumber)]           interface USBInterface {             readonly attribute octet interfaceNumber;             readonly attribute USBAlternateInterface alternate;             readonly attribute FrozenArray<USBAlternateInterface> alternates;             readonly attribute boolean claimed;           };            [Constructor(USBInterface deviceInterface, octet alternateSetting)]           interface USBAlternateInterface {             readonly attribute octet alternateSetting;             readonly attribute octet interfaceClass;             readonly attribute octet interfaceSubclass;             readonly attribute octet interfaceProtocol;             readonly attribute DOMString? interfaceName;             readonly attribute FrozenArray<USBEndpoint> endpoints;           };

Each interface provides a collection of alternates identified by a single bInterfaceNumber field found in their interface descriptors . The interfaceNumber attribute MUST match this field.

The alternate attribute SHALL be set to the USBAlternateInterface that is currently selected for this interface, which by default SHALL be the one with bAlternateSetting equal to 0 .

Each alternative interface configuration SHALL have a unique alternateSetting within a given interface that matches the bAlternateSetting field of the interface descriptor that defines it.

The interfaceClass , interfaceSubclass and interfaceProtocol attributes declare the communication interface supported by the interface. They MUST correspond respectively to the values of the bInterfaceClass , bInterfaceSubClass and bInterfaceProtocol fields of the interface descriptor .

The interfaceName attribute SHOULD contain the value of the string descriptor referenced by the iInterface field of the interface descriptor , if available.

The endpoints attribute SHALL contain a list of endpoints exposed by this interface. These endpoints SHALL by populated from the endpoint descriptors contained within this interface descriptor and the number of elements in this sequence SHALL match the value of the bNumEndpoints field of the interface descriptor .

A device’s active configuration is the combination of the USBConfiguration selected by calling selectConfiguration(configurationValue) and the set of UsbAlternateInterface s selected by calling selectAlternateInterface(interfaceNumber, alternateSetting) . A device MAY, by default, be left in an unconfigured state, referred to as configuration 0 or may automatically be set to whatever configuration has bConfigurationValue equal to 1 . When a configuration is set all interfaces within that configuration automatically have the USBAlternateInterface with bAlternateSetting equal to 0 selected by default. It is therefore unnecessary to call selectAlternateInterface(interfaceNumber, 0) for each interface when opening a device.

Endpoints
enum USBDirection {             "in",             "out"           };            enum USBEndpointType {             "bulk",             "interrupt",             "isochronous"           };            [Constructor(USBAlternateInterface alternate, octet endpointNumber, USBDirection direction)]           interface USBEndpoint {             readonly attribute octet endpointNumber;             readonly attribute USBDirection direction;             readonly attribute USBEndpointType type;             readonly attribute unsigned long packetSize;           };

Each endpoint within a particular device configuration SHALL have a unique combination of endpointNumber and direction . The endpointNumber MUST equal the 4 least significant bits of the bEndpointAddress field of the endpoint descriptor defining the endpoint.

The direction attribute declares the transfer direction supported by this endpoint and is equal to "in" if the most significant bit of the bEndpointAddress is set and "out" otherwise. An endpoint may either carry data IN from the device to host or OUT from host to device.

The type attribute declares the type of data transfer supported by this endpoint.

The packetSize attribute declares the packet size employed by this endpoint and MUST be equal to the value of the wMaxPacketSize of the endpoint descriptor defining it. In a High-Speed, High-Bandwidth endpoint this value will include the multiplication factor provided by issuing multiple transactions per microframe. In a SuperSpeed device this value will include the multiplication factor provided by the bMaxBurst field of the SuperSpeed Endpoint Companion descriptor.

Terminology

This specification uses several terms taken from [[USB31]]. While reference is made to version 3.1 of the Universal Serial Bus many of these concepts exist in previous versions as well. Significant differences between USB versions that have bearing on this specification will be called out explicitly.

Descriptors are binary data structures that can be read from a device and describe its properties and function:

  • The device descriptor contains information applicable to the entire devices and is described in section 9.6.1 of [[USB31]].
  • A configuration descriptor describes a particular set of device interfaces and endpoints that can be selected by the host. Its fields are described in section 9.6.3 of [[USB31]].
  • An interface descriptor describes the interface of a particular functional component of a device including its protocol and communication endpoints. Its fields are described in section 9.6.5 of [[USB31]].
  • An interface association descriptor creates an association between multiple interfaces that are part of a single functional unit of a device. Its fields are described in section 9.6.4 of [[USB31]].
  • An endpoint descriptor describes a channel through which data is either sent to or received from the device. Its fields are described in section 9.6.6 of [[USB31]].

The Binary Object Store ( BOS ) is an additional set of descriptors that are more free-form than the standard device descriptors. Of note is the Platform Descriptor type which allows third parties (such as this specification) to declare their own types of descriptors. Each of these is identified by a UUID. The Binary Object Store is described in section 9.6.2 of [[USB31]].

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » WebUSB API: draft spec to safely expose USB device services to the web

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
分享按钮