Serial WebSerial ( PR #238 )

1. Extensions to the Navigator interface

[Exposed=Window, SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute Serial serial;
};

1.1. serial attribute

When getting, the serial attribute always returns the same instance of the Serial object.

2. Extensions to the WorkerNavigator interface

[Exposed=DedicatedWorker, SecureContext]
partial interface WorkerNavigator {
  [SameObject] readonly attribute Serial serial;
};

2.1. serial attribute

When getting, the serial attribute always returns the same instance of the Serial object.

3. Serial interface

[Exposed=(DedicatedWorker, Window), SecureContext]
interface Serial : EventTarget {
  attribute EventHandler onconnect;
  attribute EventHandler ondisconnect;
  Promise<sequence<SerialPort>> getPorts();
  [Exposed=Window] Promise<SerialPort> requestPort(optional SerialPortRequestOptions options = {});
};

3.1. requestPort() method

const filter = { usbVendorId: 0x2341 };
const port = await navigator.serial.requestPort({ filters: [filter] });

const port = await navigator.serial.requestPort();

<button id="connect">Connect</button>

const connectButton = document.getElementById("connect");
connectButton.addEventListener('click', () => {
  try {
    const port = await navigator.serial.requestPort();
    // Continue connecting to the device attached to |port|.
  } catch (e) {
    // The prompt has been dismissed without selecting a device.
  }
});

A serial port is available if it is a wired serial port and the port is physically connected to the system, or if it is a wireless serial port and the wireless device hosting the port is registered with the system.

3.1.1. SerialPortRequestOptions dictionary

dictionary SerialPortRequestOptions {
  sequence<SerialPortFilter> filters;
  sequence<BluetoothServiceUUID> allowedBluetoothServiceClassIds;
};

filters member, of type sequence< SerialPortFilter >

Filters for serial ports

allowedBluetoothServiceClassIds member, of type sequence< BluetoothServiceUUID >

A list of BluetoothServiceUUID values representing Bluetooth service class IDs. Bluetooth ports with custom service class IDs are excluded from the list of ports presented to the user unless the service class ID is included in this list.

3.1.2. SerialPortFilter dictionary

dictionary SerialPortFilter {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

usbVendorId member, of type unsigned short

USB Vendor ID

usbProductId member, of type unsigned short

USB Product ID

bluetoothServiceClassId member, of type BluetoothServiceUUID

Bluetooth service class ID

3.2. getPorts() method

// Check to see what ports are available when the page loads.
document.addEventListener('DOMContentLoaded', async () => {
  let ports = await navigator.serial.getPorts();
  // Populate the UI with options for the user to select or
  // automatically connect to devices.
});
navigator.serial.addEventListener('connect', e => {
  // Add |e.target| to the UI or automatically connect.
});
navigator.serial.addEventListener('disconnect', e => {
  // Remove |e.target| from the UI. If the device was open the
  // disconnection can also be observed as a stream error.
});

3.3. onconnect attribute

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

3.4. ondisconnect attribute

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

4. SerialPort interface

[Exposed=(DedicatedWorker,Window), SecureContext]
interface SerialPort : EventTarget {
  attribute EventHandler onconnect;
  attribute EventHandler ondisconnect;
  readonly attribute boolean connected;
  readonly attribute ReadableStream? readable;
  readonly attribute WritableStream? writable;
  SerialPortInfo getInfo();
  Promise<undefined> open(SerialOptions options);
  Promise<undefined> setSignals(optional SerialOutputSignals signals = {});
  Promise<SerialInputSignals> getSignals();
  Promise<undefined> close();
  Promise<undefined> forget();
};

Methods on this interface typically complete asynchronously, queuing work on the serial port task source .

The get the parent algorithm for SerialPort returns the same Serial instance that is returned by the SerialPort ’s relevant global object ’s Navigator object’s serial getter.

Instances of SerialPort are created with the internal slots described in the following table:

4.1. onconnect attribute

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

A serial port is logically connected if it is a wired serial port and the port is physically connected to the system, or if it is a wireless serial port and the system has active connections to the wireless device (e.g. an open Bluetooth L2CAP channel).

4.2. ondisconnect attribute

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

4.3. getInfo() method

4.3.1. SerialPortInfo dictionary

dictionary SerialPortInfo {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

usbVendorId member, of type unsigned short

If the port is part of a USB device this member will be the 16-bit vendor ID of that device. Otherwise it will be undefined .

usbProductId member, of type unsigned short

If the port is part of a USB device this member will be the 16-bit product ID of that device. Otherwise it will be undefined .

bluetoothServiceClassId member, of type BluetoothServiceUUID

If the port is a service on a Bluetooth device this member will be a BluetoothServiceUUID containing the service class UUID. Otherwise it will be undefined .

4.4. open() method

await port.open({ baudRate: /* pick your baud rate */ });

4.4.1. SerialOptions dictionary

dictionary SerialOptions {
  [EnforceRange] required unsigned long baudRate;
  [EnforceRange] octet dataBits = 8;
  [EnforceRange] octet stopBits = 1;
  ParityType parity = "none";
  [EnforceRange] unsigned long bufferSize = 255;
  FlowControlType flowControl = "none";
};

baudRate member, of type unsigned long

A positive, non-zero value indicating the baud rate at which serial communication should be established.

Note: baudRate is the only required member of this dictionary. While there are common default for other connection parameters it is important for developers to consider and consult with the documentation for devices they intend to connect to determine the correct values. While some values are common there is no standard baud rate. Requiring this parameter reduces the potential for confusion if an arbitrary default were chosen by this specification.

dataBits member, of type octet , defaulting to 8

The number of data bits per frame. Either 7 or 8.

stopBits member, of type octet , defaulting to 1

The number of stop bits at the end of a frame. Either 1 or 2.

parity member, of type ParityType , defaulting to "none"

The parity mode.

bufferSize member, of type unsigned long , defaulting to 255

A positive, non-zero value indicating the size of the read and write buffers that should be created.

flowControl member, of type FlowControlType , defaulting to "none"

The flow control mode.

4.4.1.1. ParityType enum

enum ParityType {
  "none",
  "even",
  "odd"
};

none

No parity bit is sent for each data word.

even

Data word plus parity bit has even parity.

odd

Data word plus parity bit has odd parity.

4.4.1.2. FlowControlType enum

enum FlowControlType {
  "none",
  "hardware"
};

none

No flow control is enabled.

hardware

Hardware flow control using the RTS and CTS signals is enabled.

4.5. connected attribute

4.6. readable attribute

while (port.readable) {
  const reader = port.readable.getReader();
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) {
        // |reader| has been canceled.
        break;
      }
      // Do something with |value|...
    }
  } catch (error) {
    // Handle |error|...
  } finally {
    reader.releaseLock();
  }
}

class LineBreakTransformer {
  constructor() {
    this.container = '';
  }
  transform(chunk, controller) {
    this.container += chunk;
    const lines = this.container.split('\r\n');
    this.container = lines.pop();
    lines.forEach(line => controller.enqueue(line));
  }
  flush(controller) {
    controller.enqueue(this.container);
  }
}
const decoder = new TextDecoderStream();
const streamClosed = port.readable.pipeTo(decoder.writable);
const lineReader = decoder.readable
    .pipeThrough(new TransformStream(new LineBreakTransformer()))
    .getReader();

lineReader.cancel();
await streamClosed;
await port.close();

async function readWithTimeout(port, timeout) {
  const reader = port.readable.getReader();
  const timer = setTimeout(() => {
    reader.releaseLock();
  }, timeout);
  const result = await reader.read();
  clearTimeout(timer);
  reader.releaseLock();
  return result;
}

4.7. writable attribute

const encoder = new TextEncoder();
const writer = port.writable.getWriter();
await writer.write(encoder.encode("PING"));
writer.releaseLock();

4.8. setSignals() method

await port.setSignals({ dataTerminalReady: false });
await new Promise(resolve => setTimeout(resolve, 200));
await port.setSignals({ dataTerminalReady: true });

4.8.1. SerialOutputSignals dictionary

dictionary SerialOutputSignals {
  boolean dataTerminalReady;
  boolean requestToSend;
  boolean break;
};

dataTerminalReady , of type boolean

Data Terminal Ready (DTR)

requestToSend , of type boolean

Request To Send (RTS)

break , of type boolean

Break

4.9. getSignals() method

4.9.1. SerialInputSignals dictionary

dictionary SerialInputSignals {
  required boolean dataCarrierDetect;
  required boolean clearToSend;
  required boolean ringIndicator;
  required boolean dataSetReady;
};

dataCarrierDetect member, of type boolean

Data Carrier Detect (DCD)

clearToSend member, of type boolean

Clear To Send (CTS)

ringIndicator member, of type boolean

Ring Indicator (RI)

dataSetReady member, of type boolean

Data Set Ready (DSR)

4.10. close() method

const encoder = new TextEncoder();
const writer = port.writable.getWriter();
writer.write(encoder.encode("A long message that will take..."));
await writer.close();
await port.close();

const encoder = new TextEncoderStream();
const writableStreamClosed = encoder.readable.pipeTo(port.writable);
const writer = encoder.writable.getWriter();
writer.write("A long message that will take...");
writer.close();
await writableStreamClosed;
await port.close();

let keepReading = true;
let reader;
async function readUntilClosed() {
  while (port.readable && keepReading) {
    reader = port.readable.getReader();
    try {
      while (true) {
        const { value, done } = await reader.read();
        if (done) {
          // |reader| has been canceled.
          break;
        }
        // Do something with |value|...
      }
    } catch (error) {
      // Handle |error|...
    } finally {
      reader.releaseLock();
    }
  }
  await port.close();
}
const closed = readUntilClosed();
// Sometime later...
keepReading = false;
reader.cancel();
await closed;

4.11. forget() method

// Request a serial port.
const port = await navigator.serial.requestPort();
// Then later... revoke permission to the serial port.
await port.forget();

5. Blocklist

This specification relies on a blocklist file in the https://github.com/whatwg/serial repository to restrict the set of ports a website can access.

The result of parsing the Bluetooth service class ID blocklist at a URL url is a list of UUID values representing custom service IDs.

The Serial Port Profile service class ID is a BluetoothServiceUUID with value " 00001101-0000-1000-8000-00805f9b34fb ".

6. Integrations

6.1. Permissions Policy

This specification defines a feature that controls whether the methods exposed by the serial attribute on the Navigator object may be used.

The feature name for this feature is " serial ".

The default allowlist for this feature is 'self' .

7. Security considerations

This section is non-normative.

This API poses similar a security risk to [WEBBLUETOOTH] and [WEBUSB] and so lessons from those are applicable here. The primary threats are:

• A malicious site that has tricked the user into granting it access to a device using the device’s intended capabilities for malicious purposes. For example, a robot causing physical damage.

• A malicious site that has tricked the user into granting it access to a device installing its own firmware into the device in order to modify the device’s intended capabilities for malicious purposes or to attack the host to which it is connected. For example, triggering a buffer overflow in other host software which communicates with the device.

• Malicious code injected into a trusted site which has been granted access to the device doing any of the above. For example, an online firmware update utility being hacked to deliver malicious firmware.

• An attacker convincing the user to connect a malicious device to their system which colludes with a malicious or exploited site to create a web-based channel for communicating back to the attacker.

The primary mitigation to all of these attacks is the requestPort() pattern, which requires user interaction and only supports granting access to a single device at a time. This prevents drive-by attacks because a site cannot enumerate all connected devices to determine whether a vulnerable device exists and must instead proactively inform the user that it desires access. Implementations may also provide a visual indication that a site is currently communicating with a device and controls for revoking that permission at any time.

This specification requires the site to be served from a secure context in order to prevent malicious code from being injected by a network-based attacker. This ensures that the site identity shown to the user when making permission decisions is accurate. This specification also requires top-level documents to opt-in through [PERMISSIONS-POLICY] before allowing a cross-origin iframe to use the API. When combined with [CSP3] these mechanisms provide protection against malicious code injection attacks.

The remaining concern is the exploitation of a connected device through a phishing attack that convinces the user to grant a malicious site access to a device. These attacks can be used to either exploit the device’s capabilities as designed or to install malicious firmware on the device that will in turn attack the host computer. Host software may be vulnerable to attack because it improperly validates input from connected devices. Security research in this area has encouraged software vendors to treat connected devices as untrustworthy.

There is no mechanism that will completely prevent this type of attack because data sent from a page to the device is an opaque sequence of bytes. Efforts to block a particular type of data from being sent are likely be met by workarounds on the part of device manufacturers who nevertheless want to send this type of data to their devices.

User agents can implement additional mechanisms to control access to devices:

• A setting which prevents sites from calling requestPort() unless added to an explicit allow list.

  Systems administrators could apply such a setting across their managed fleet using enterprise policy controls. Such controls may allow the administrator to automatically grant selected sites access to particular devices and no others.

• A list of device IDs for hardware which is known to be exploitable could be deployed with the user agent. Connections to listed devices would be blocked. An implementation could use its automatic update or experiment management system to deploy updates to this list on the fly to block an active attack.

Implementations of [WEBBLUETOOTH] and [WEBUSB] have experimented with these mitigations however there are limits to their effectiveness. First, it is difficult to define whether a device is exploitable. For example, this API will allow a site to upload firmware to a microcontroller development board. This is a key use case for this API as these devices are common in the educational and hobbyist markets. These boards do not implement firmware signature verification and so can easily be turned into a malicious device. These boards are clearly exploitable but should not be blocked.

In addition, maintaining a list of vulnerable devices works well for USB and Bluetooth because those protocols define out-of-band mechanisms to gather device metadata. The make and model of such devices can thus be easily identified even if they present themselves to the host as a virtual serial ports. However, there are generic USB- or Bluetooth-to-serial adapters as well as systems with "real" serial ports using a DB-25, DE-9 or RJ-45 connector. For these there is no metadata that can be read to determine the identity of the device connected to the port and so blocking access to these is not possible.

8. Privacy considerations

This section is non-normative.

Serial ports and serial devices contain two kinds of sensitive information. When a port is a USB or Bluetooth device there are identifiers such as the vendor and product IDs (which identify the make and model) as well as a serial number or MAC address. The serial device itself may also have its own identifier that is available through commands sent via the serial port. The device may also store other private information which may or may not be identifying.

In order to manage device permissions an implementation will likely store device identifiers such as the USB vendor ID, product ID and serial number in its user preferences file to be used as stable identifiers for devices the user has granted sites access to. These would not be shared directly with sites and would be cleared when permission is revoked or site data in general is cleared.

Commands a page can send to the device after it has been granted access a page may also be able to access any of the other sensitive information stored by the device. For the reasons mentioned in § 7 Security considerations it is impractical and undesirable to attempt to prevent a page from accessing this information.

Implementations should provide users with complete control over which devices a site can access and not grant device access without user interaction. This is the intention of the requestPort() method. This prevents a site from silently enumerating and collecting data from all connected devices. This is similar to the file picker UI. A site has no knowledge of the filesystem, only the files or directories that have been chosen by the user. An implementation could notify the user when a site is using these permissions with an indicator icon appearing in the tab or address bar.

Implementations that provide a "private" or "incognito" browsing mode should ensure that permissions from the user’s normal profile do not carry over to such a session and permissions granted in this session are not persisted when the session ends. An implementation may warn the user when granting access to a device in such as session as, similar to entering identifying information by hand, device identifiers and other unique properties available from communicating with the device mentioned previously can be used to identify the user between sessions.

Users may be surprised by the capabilities granted by this API if they do not understand the ways in which granting access to a device breaks traditional isolation boundaries in the web security model. Security UI and documentation should explain that granting a site access to a device could give the site full control over the device and any data contained within.

Acknowledgments

Thanks to Anatol Ulrich, Chris Mumford, Clément Menard, Domenic Denicola, Dominique Hazael-Massieux, Florian Loitsch, Florian Scholz, Francis Gulotta, François Beaufort, Jack Hsieh, Keavon Chambers, Kenneth Rohde Christiansen, Marcos Cáceres, Matt Reynolds, Jesse Melhuish, Michael Kohler, Ms2ger, Rick Waldron, Sankha Narayan Guria, Simon Pieters, Suz Hinton, Travis Leithead, and Vincent Scheib for being awesome.

This standard is written by Reilly Grant ( Google , reillyg@google.com ).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License . To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.