Engineering:WebUSB

Short description: JavaScript application programming interface specification

WebUSB is a JavaScript application programming interface (API) specification for securely providing access to USB devices from web applications.

It was published by the Web Platform Incubator Community Group. As of July 2021, it is in Draft Community status, and is supported by Google Chrome, Microsoft Edge, QQ, Opera, and Samsung Internet.

Introduction

A Universal Serial Bus, or a USB is an industry standard communication protocol used to communicate data across connectors, and cables from computers to peripheral devices and/or other computers. WebUSB is a set of API calls that enable access to these hardware devices from web pages. WebUSB is developed by the World Wide Web Consortium (W3C). The WebUSB API provides a safe, and developer familiar means of communication to edges devices from web pages. The WebUSB API integrates into existing USB libraries and shortens the development cycle for integrating new devices into the web environment by not needing to wait for browser support for these devices.

Early versions of WebUSB came out around as an alternative to Flash, Chrome Serial, and other custom approaches to connecting browsers to hardware. WebUSB aims to solve the four goals of any interface being; fast to make, cross platform, look good, accessibility.

Application to Internet of Things (IoT) architecture

WebUSB API's are able to bridge hardware protocols to internet protocols, enabling the creating of uniform gateways linking edge devices to a centralised networks.

The explosion in computing ability over the last few decades has led to an increase in edge devices. Devices such as lights, thermometers, HVAC, motors are increasingly integrated into centralised internet control servers. These devices have evolved from isolated and previously non-integrated development environments. Consequently, they lack the uniform and consistent communication protocol necessary to develop robust networks. The WebUSB's API framework standardises disparate protocols and is able to expose non-standard Universal Serial Bus (USB) compatible devices to the web.

The WebUSB looks to sit between the perception layer and the network layer. The main goals of software in this gateway are; Scalability, Cost and reliability. The cloud-based deployment of WebUSB libraries enables it to cover scalability, its low overhead deployment significantly lowers cost, and its continual in use development over its lifetime has enabled the framework to attain a high degree of reliability.

WebUSB has formed a cornerstone of the BIPES (Block based Integrated Platform for Embedded Systems) architecture framework. This systems architecture model aims to reduce complexity of IoT systems development by aggregating relevant software into 'Blocks' that are complete units of code and can be deployed to an edge device from a centralised cloud infrastructure. As already mentioned the role of WebUSB is critically tied to its ability to communicate to embedded software through the USB communication protocol. Once the information is inside WebUSB's JavaScript environment it can be transposed and communicated through a variety of software protocols. In this particular architecture model WebUSB bridges the gap between embedded software, and the web browser. The web browser then communicates to the cloud environment using uniform WebUSB constructed data.

Security considerations

WebUSB provides a web page access to a connector to an edge device. The exposure of any device to the internet carries inherent risks and security concerns. By product of design USB ports are designed to trust the device they are connected to. Connecting such a port to an internet facing application introduced a new set of security risks and massively expanding the attack surface for would be malicious actors.

For instance a malicious host web page could request data from a peripheral device, which the device would happily fulfil thinking it was communicating through a standard USB connector. To mitigate this type of attack WebUSB developed a requestDevice() function call. This would notify the user that the site was requesting access to the edge device. This is similar to the access requests browser control for when a web page would like to access the inbuilt camera or microphone. Depending on the wariness of the user this protocol can be enough to prevent certain attacks. A second protocol that was developed is the specification of a request originating from a secure context. This ensures that both the code to be executed and the data returned is not intercepted or modified in transit. This security is implemented through the claimInterface() function. This is an OS supported function, and ensures that only a single execution instance can have user space or kernel space driver access to the device, preventing malicious code on a web page from opening a second channel of communication to the device. Other security considerations included created a public registry of approved connections, but this idea was ultimately scrapped as it required vendors to develop devices with WebUSB in mind.

The threat surface of a USB however is bi-directional and a malicious peripheral device could attack the host. An infected edge device cannot easily be mitigated by WebUSB API's. In many device configurations trusted USB ports are used to deliver firmware upgrades and a malicious edge device could grant attackers persistence in a system.

In light of the security concerns posed by WebUSB, it is only supported by an estimated 76% of browsers. Also notably is that support for WebUSB at a browser level has been volatile over time, with stretches of time where certain browsers turned off access after the discovery of particular security threats. It is these security concerns that have plagued alternatives to WebUSB. Particularly Flash and Google Serial failed to take off because they were unable to be used with adequate answers to these fundamental security risks.

Use in multi-factor authentication

The ability to own and verify a digital identity on the internet is critical to interaction with internet facing infrastructure. WebUSB in combination with special purpose devices and public identification registries can be used as key piece in an infrastructure scale solution to digital identity on the internet. WebUSB API library is able to standardise the connection of peripheral devices to web pages. The security investment in WebUSB makes it a suitable software component in connecting identifiable devices to the internet. Recent research has shown the fallibility of SMS based authentication highlighting how key pieces of the infrastructure can be subverted. Alternative proposals for securing a digital identity involve the use of biometric sensors and/or personal identifiers. However, while these are good at identifying an individual, it is only through WebUSB that they can adequately be integrated into the existing internet tech stack. Cryptographically secure solutions for personal identification exist with support from government and specialised hardware. However, these solutions lack generalised specification for web based infrastructure and are generally hard to support. Gateway support for such a communication protocol can be supported by software middlemen, such as WebUSB.

A model system for multi-factor authentication uses WebUSB in tandem with an identifying hardware such as an ID card built to ISO/IEC 7810:2003 ID-1 standards. This card would constitute a physical representation of an individual's identity. WebUSB would then act as a middle man in facilitating the transfer of data stored on the hardware to a given web server. The number card would be digitally signed by an authorised party and would digitally connect to a server. This connection would require a device capable of reading ISO/IEC 14443 type B connections. In order to make this digital connection valid, WebUSB would serve as software connector.

Usage

WebUSB will only work on supported browsers, for example Chrome. Due to privacy and security concerns it will also only work in a secure context i.e.; over HTTPS, and can only be called through a user actions. For instance in order to instantiate a connection navigator.usb.requestDevice() can only be called through user gesture, such as touch or mouse click. Similarly protection from WebUSB can be provided using a feature policy. For instance Feature-Policy: fullscreen "*"; usb "none"; payment "self" https://payment.example.com would prevent WebUSB from running.

To get access to devices visible to the browser two options are available. navigator.usb.requestDevice() will prompt the user to select which USB access is to be given, or navigator.usb.getDevices() will return a list of USB devices that the origin has access to.

To better search for devices, WebUSB has a number of filtering options. These filters are passed into navigator.usb.requestDevice() as a JavaScript filtering object. These filters are; vendorId,productId,classCode, protocolCode, serialNumber, and subclassCode.

For example, imagine connecting to an Arduino device, this could be done in the following way. Where 0x2341 is Arduino in the list of USB ID's

navigator.usb.requestDevice({ filters: [{ vendorId: 0x2341 }] })
.then(device => {
  console.log(device.productName);      
  console.log(device.manufacturerName); 
})
.catch(error => { console.error(error); });

The USB device descriptor returned from the above snippet will contain all important information about the device such as; version, packet size, configuration options etc.

The alternative call to navigator.usb.getDevices() will instead look like this;

navigator.usb.getDevices().then(devices => {
  devices.forEach(device => {
    console.log(device.productName);      
    console.log(device.manufacturerName); 
  });
})

In order to talk to the device there are a few important function calls to run through. device.open() will run through all the required steps of setting up the device, device.selectConfiguration() sets up the configuration, importantly how it is powered, and the number of interfaces. It is then important to claim the interface. This can be done through the device.claimInterface function call. This will simulate a real wired connection and ensure that this web page is the only one able to read and write to the device until the connection is released. Finally the call device.controlTransferOut() will set up the device to communicate through the WebUSB Serial API. Once the set up is all done, data can be transferred to the device using device.transferIn() to transfer bulk data to the device, similarly its sister function device.transferOut() to read data from the device.

Interfaces

In order to generalise interaction with hardware devices WebUSB supports a number of interfaces than abstract away the specific hardware functionality.

Interfaces

Interface Name	Description
USB	Provides attributes and methods for finding and connecting USB devices from a web page. This interface inherits from EventTarget.
USBConnectionEvent	This connection event is passed to USB.onconnect or USB.ondisconnect when the agent detects a change in the connection status.
USBDevice	Interface that provides metadata about the connected device and methods for controlling it. Importantly this is the main interface the developer will use for interacting with the device.
USBInTransferResult	A representation of the results from a data transfer event from the device to the host. Including field for the data and the status of the transfer. There are three options for status fields; 'ok' meaning the transfer was a success, 'stall' indicating an error producing a stall on the endpoint, or 'babble' which indicates more than expected data was transferred.
USBIsochronousInTransferResult	Similar to USBInTransferResult this is a representation of a data transfer from the device to the host when done across an isochronous endpoint. Has no status field, only the packets.
USBIsochronousInTransferPacket	Represents the status of an individual packet from a request to transfer data from the device to the host over an isochronous endpoint. Can return the status of either 'ok' or 'stall'.
USBIsochronousOutTransferResult	Similar to USBInTransferResult this is a representation of a data transfer from the host to the device when done across an isochronous endpoint.
USBIsochronousOutTransferPacket	Represents the status of an individual packet from a request to transfer data from the host to the device over an isochronous endpoint. Same status fields as USBIsochronousInTransferPacket.
USBConfiguration	Provides information about a particular configuration of a USB device . This includes information about device version, maximum packet size and supported interfaces.
USBInterface	Provides information about an interface provided by the USB device. This includes information on whether it is claimed, as well as its communication protocol.
USBAlternateInterface	Provides information about a particular configuration of an interface and the particular modes the device can operate in.
USBEndPoint	The USBEndPoint is a unidirectional data stream either into or out of the device.

External links

• WebUSB API - Draft Community Group Report, 7 July 2020