Web Serial API (original) (raw)

Abstract

The Serial API provides a way for websites to read and write from a serial device through script. Such an API would bridge the web and the physical world, by allowing documents to communicate with devices such as microcontrollers, 3D printers, and other serial devices. There is also a companion explainer document.

Status of This Document

This specification was published by theWeb Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under theW3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more aboutW3C Community and Business Groups.

This is a work in progress. All contributions welcome.

GitHub Issues are preferred for discussion of this specification.

Abstract
Status of This Document
1. Extensions to the Navigator interface
1. 1.1 serial attribute
2. Extensions to the WorkerNavigator interface
1. 2.1 serial attribute
3. Serial interface
4. SerialPort interface
5. Blocklist
6. Integrations
1. 6.1 Permissions Policy
7. Security considerations
8. Privacy considerations
9. Conformance
A. Acknowledgements
B. References
B.1 Normative references
B.2 Informative references

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

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

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

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

[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 = {});
};

The requestPort() method steps are:

Let promise be a new promise.
If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "serial", reject promise with a "SecurityError" DOMException and returnpromise.
If the relevant global object of this does not havetransient activation, reject promise with a "SecurityError" DOMException and return promise.
If options["filters"] is present, then for each filter inoptions["filters"] run the following steps:
1. If filter["bluetoothServiceClassId"] is present:
  1. If filter["usbVendorId"] is present,reject promise with a TypeError and return promise.
  2. If filter["usbProductId"] is present,reject promise with a TypeError and return promise.
2. If filter["usbVendorId"] is not present, reject promise with a TypeError and returnpromise.
  Note
  This check implements the combined rule that aSerialPortFilter cannot be empty and ifusbProductId is specified thenusbVendorId must also be specified.
Run the following steps in parallel:
1. Let allPorts be an empty list.
2. For each Bluetooth device registered with the system:
  1. For each BluetoothServiceUUID uuid supported by the device:
    1. If uuid is not a blocked Bluetooth service class UUID:
    * If uuid is equal to the Serial Port Profile service class ID, or
    * options["allowedBluetoothServiceClassIds"] is present and contains uuid:
    1. Let port be a SerialPort representing the service on the Bluetooth device.
    2. Append port to allPorts.
3. For each available non-Bluetooth serial port:
  1. Let port be a SerialPort representing the port.
  2. Append port to allPorts.
4. Prompt the user to grant the site access to a serial port by presenting them with a list of ports in allPorts that match any filter in options["filters"] if present and allPorts otherwise.
5. If the user does not choose a port, queue a global task on the relevant global object of this using the serial port task source to reject promise with a "NotFoundError" DOMException and abort these steps.
6. Let port be a SerialPort representing the port chosen by the user.
7. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with port.
Return promise.

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.

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

filters member

Filters for serial ports

allowedBluetoothServiceClassIds member

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.

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

usbVendorId member

USB Vendor ID

usbProductId member

USB Product ID

bluetoothServiceClassId member

Bluetooth service class ID

A serial port port matches the filter filter if these steps return true:

Let info be the result of callingport.getInfo().
If filter["bluetoothServiceClassId"] is present:
1. If the serial port is not part of a Bluetooth device, return false.
2. If filter["bluetoothServiceClassId"] is equal toinfo["bluetoothServiceClassId"], returntrue.
3. Otherwise, return false.
If filter["usbVendorId"] is not present, return true.
If the serial port is not part of a USB device, return false.
If info["usbVendorId"] is not equal tofilter["usbVendorId"], return false.
If filter["usbProductId"] is not present, return true.
If info["usbProductId"] is not equal tofilter["usbProductId"], return false.
Otherwise, return true.

A serial port port matches any filter in a sequence ofSerialPortFilter if these steps return true:

For each filter in the sequence, run these sub-steps:
1. If port matches the filter filter, return true.
Return false.

The getPorts() method steps are:

Let promise be a new promise.
If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "serial", reject promise with a "SecurityError" DOMException and return promise.
Run the following steps in parallel:
1. Let availablePorts be the sequence of available serial ports which the user has allowed the site to access as the result of a previous call to requestPort().
2. Let ports be the sequence of the SerialPorts representing the ports in availablePorts.
3. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with ports.
Return promise.

onconnect is an event handler IDL attribute for theconnect event type.

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

[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 sameSerial 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:

Internal slot	Initial value	Description (non-normative)
[[state]]	"closed"	Tracks the active state of the SerialPort
[[bufferSize]]	undefined	The amount of data to buffer for transmit and receive
[[connected]]	false	A flag indicating the logical connection state of serial port
[[readable]]	null	A ReadableStream that receives data from the port
[[readFatal]]	false	A flag indicating that the port has encountered a fatal read error
[[writable]]	null	A WritableStream that transmits data to the port
[[writeFatal]]	false	A flag indicating that the port has encountered a fatal write error
[[pendingClosePromise]]	null	A Promise used to wait for readable andwritable to close

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

When a serial port that the user has allowed the site to access as the result of a previous call to requestPort() becomeslogically connected, run the following steps:

Let port be a SerialPort representing the port.
Set port.[[connected]] to true.
Fire an event named connect at port with itsbubbles attribute initialized to true.

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).

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

When a serial port that the user has allowed the site to access as the result of a previous call to requestPort() is no longerlogically connected, run the following steps:

Let port be a SerialPort representing the port.
Set port.[[connected]] to false.
Fire an event named disconnect at port with itsbubbles attribute initialized to true.

The getInfo() method steps are:

Let info be an empty ordered map.
If the port is part of a USB device, perform the following steps:
1. Set info["usbVendorId"] to the vendor ID of the device.
2. Set info["usbProductId"] to the product ID of the device.
If the port is a service on a Bluetooth device, perform the following steps:
1. Set info["bluetoothServiceClassId"] to the service class UUID of the Bluetooth service.
Return info.

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

usbVendorId member

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

usbProductId member

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

bluetoothServiceClassId member

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.

The open() method steps are:

Let promise be a new promise.
If this.[[state]] is not "closed", rejectpromise with an "InvalidStateError" DOMException and returnpromise.
If options["dataBits"] is not 7 or 8, rejectpromise with TypeError and return promise.
If options["stopBits"] is not 1 or 2, rejectpromise with TypeError and return promise.
If options["bufferSize"] is 0, rejectpromise with TypeError and return promise.
Optionally, if options["bufferSize"] is larger than the implementation is able to support, reject promise with a TypeError and return promise.
Set this.[[state]] to "opening".
Perform the following steps in parallel.
1. Invoke the operating system to open the serial port using the connection parameters (or their defaults) specified in options.
2. If this fails for any reason, queue a global task on therelevant global object of this using the serial port task source to reject promise with a "NetworkError"DOMException and abort these steps.
3. Set this.[[state]] to "opened".
4. Set this.[[bufferSize]] tooptions["bufferSize"].
5. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with undefined.
Return promise.

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

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

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

stopBits member

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

parity member

The parity mode.

bufferSize member

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

flowControl member

The flow control mode.

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.

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

none

No flow control is enabled.

hardware

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

The connected getter steps are:

Return this.[[connected]].

The readable getter steps are:

If this.[[readable]] is not null, returnthis.[[readable]].
If this.[[state]] is not "opened", returnnull.
If this.[[readFatal]] is true, returnnull.
Let stream be a new ReadableStream.
Let pullAlgorithm be the following steps:
1. Let desiredSize be the desired size to fill up to the high water mark forthis.[[readable]].
2. If this.[[readable]]'scurrent BYOB request view is non-null, then set desiredSize to this.[[readable]]'scurrent BYOB request view'sbyte length.
3. Run the following steps in parallel:
  1. Invoke the operating system to read up to desiredSize bytes from the port, putting the result in the byte sequence bytes.
    Note
    this.[[state]] becoming "forgotten" must be treated as if the port was disconnected.
  2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
    1. If no errors were encountered, then:
    1. If this.[[readable]]'scurrent BYOB request view is non-null, then write bytes intothis.[[readable]]'scurrent BYOB request view, and setview to this.[[readable]]'scurrent BYOB request view.
    2. Otherwise, set view to the result ofcreating a Uint8Array from bytes in this's relevant Realm.
    3. Enqueue view intothis.[[readable]].
    2. If a buffer overrun condition was encountered, invokeerror onthis.[[readable]] with a "BufferOverrunError" DOMException and invoke the steps to handle closing the readable stream.
    3. If a break condition was encountered, invokeerror onthis.[[readable]] with a "BreakError" DOMException and invoke the steps to handle closing the readable stream.
    4. If a framing error was encountered, invokeerror onthis.[[readable]] with a "FramingError" DOMException and invoke the steps to handle closing the readable stream.
    5. If a parity error was encountered, invokeerror onthis.[[readable]] with a "ParityError" DOMException and invoke the steps to handle closing the readable stream.
    6. If an operating system error was encountered, invokeerror onthis.[[readable]] with an "UnknownError" DOMException and invoke the steps to handle closing the readable stream.
    7. If the port was disconnected, run the following steps:
    1. Set this.[[readFatal]] totrue,
    2. Invoke error onthis.[[readable]] with a "NetworkError" DOMException.
    3. Invoke the steps to handle closing the readable stream.
4. Return a promise resolved with undefined.
  Note
  The Promise returned by this algorithm is immediately resolved so that it does not block canceling the stream. [STREAMS] specifies that this algorithm will not be invoked again until a chunk is enqueued.
Let cancelAlgorithm be the following steps:
1. Let promise be a new promise.
2. Run the following steps in parallel.
  1. Invoke the operating system to discard the contents of all software and hardware receive buffers for the port.
  2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
    1. Invoke the steps to handle closing the readable stream.
    2. Resolve promise with undefined.
3. Return promise.
Set up with byte reading support stream with_pullAlgorithm_ set to pullAlgorithm,cancelAlgorithm set to cancelAlgorithm, and_highWaterMark_ set tothis.[[bufferSize]].
Set this.[[readable]] to stream.
Return stream. To handle closing the readable stream perform the following steps:
Set this.[[readable]] to null.
If this.[[writable]] is null andthis.[[pendingClosePromise]] is not null,resolve this.[[pendingClosePromise]] withundefined.

The writable getter steps are:

If this.[[writable]] is not null, returnthis.[[writable]].
If this.[[state]] is not "opened", returnnull.
If this.[[writeFatal]] is true, returnnull.
Let stream be a new WritableStream.
Let signal be stream's signal.
Let writeAlgorithm be the following steps, given chunk:
1. Let promise be a new promise.
2. Assert: signal is not aborted.
3. If chunk cannot be converted to an IDL value of typeBufferSource, reject promise with a TypeError and return promise. Otherwise, save the result of the conversion insource.
4. Get a copy of the buffer source source and save the result in bytes.
5. In parallel, run the following steps:
  1. Invoke the operating system to write bytes to the port. Alternately, store the chunk for future coalescing.
    Note
    The operating system may return from this operation oncebytes has been queued for transmission rather than after it has been transmitted.
    Note
    this.[[state]] becoming "forgotten" must be treated as if the port was disconnected.
  2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
    1. If the chunk was successfully written, or was stored for future coalescing, resolve promise withundefined.
    Note
    [STREAMS] specifies that writeAlgorithm will only be invoked after the Promise returned by a previous invocation of this algorithm has resolved. For efficiency an implementation is allowed to resolve this Promise early in order to coalesce multiple chunks waiting in the WritableStream's internal queue into a single request to the operating system.
    2. If an operating system error was encountered,reject promise with an "UnknownError"DOMException.
    3. If the port was disconnected, run the following steps:
    1. Set this.[[writeFatal]] totrue.
    2. Reject promise with a "NetworkError"DOMException.
    3. Invoke the steps to handle closing the writable stream.
    4. If signal is aborted, reject promise with signal's abort reason.
6. Return promise.
Let abortAlgorithm be the following steps:
1. Let promise be a new promise.
2. Run the following steps in parallel.
  1. Invoke the operating system to discard the contents of all software and hardware transmit buffers for the port.
  2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
    1. Invoke the steps to handle closing the writable stream.
    2. Resolve promise with undefined.
3. Return promise.
Let closeAlgorithm be the following steps:
1. Let promise be a new promise.
2. Run the following steps in parallel.
  1. Invoke the operating system to flush the contents of all software and hardware transmit buffers for the port.
  2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
    1. Invoke the steps to handle closing the writable stream.
    2. If signal is aborted, reject promise with signal's abort reason.
    3. Otherwise, resolve promise with undefined.
3. Return promise.
Set up stream with writeAlgorithm set to writeAlgorithm, abortAlgorithm set to abortAlgorithm, closeAlgorithm set to closeAlgorithm, highWaterMark set to this.[[bufferSize]], and sizeAlgorithm set to a byte-counting size algorithm.
Add the following abort steps to signal:
Cause any invocation of the operating system to write to the port to return as soon as possible no matter how much data has been written.
Set this.[[writable]] to stream.
Return stream. To handle closing the writable stream perform the following steps:
Set this.[[writable]] to null.
If this.[[readable]] is null andthis.[[pendingClosePromise]] is not null,resolve this.[[pendingClosePromise]] withundefined.

The setSignals() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", rejectpromise with an "InvalidStateError" DOMException and returnpromise.
If all of the specified members of signals are not present reject promise with TypeError and return promise.
Perform the following steps in parallel:
1. If signals["dataTerminalReady"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "data terminal ready" or "DTR" signal on the serial port.
2. If signals["requestToSend"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "request to send" or "RTS" signal on the serial port.
3. If signals["break"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "break" signal on the serial port.
  Note
  The "break" signal is typically implemented as an in-band signal by holding the transmit line at the "mark" voltage and thus prevents data transmission for as long as it remains asserted.
4. If the operating system fails to change the state of any of these signals for any reason, queue a global task on therelevant global object of this using the serial port task source to reject promise with a "NetworkError"DOMException.
5. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with undefined.
Return promise.

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

dataTerminalReady

Data Terminal Ready (DTR)

requestToSend

Request To Send (RTS)

break

Break

The getSignals() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", rejectpromise with an "InvalidStateError" DOMException and returnpromise.
Perform the following steps in parallel:
1. Query the operating system for the status of the control signals that may be asserted by the device connected to the serial port.
2. If the operating system fails to determine the status of these signals for any reason, queue a global task on therelevant global object of this using the serial port task source to reject promise with a "NetworkError"DOMException and abort these steps.
3. Let dataCarrierDetect be true if the "data carrier detect" or "DCD" signal has been asserted by the device, andfalse otherwise.
4. Let clearToSend be true if the "clear to send" or "CTS" signal has been asserted by the device, and false otherwise.
5. Let ringIndicator be true if the "ring indicator" or "RI" signal has been asserted by the device, and false otherwise.
6. Let dataSetReady be true if the "data set ready" or "DSR" signal has been asserted by the device, and false otherwise.
7. Let signals be the ordered map «[ "dataCarrierDetect" → dataCarrierDetect, "clearToSend" → clearToSend, "ringIndicator" → ringIndicator, "dataSetReady" → dataSetReady ]».
8. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with signals.
Return promise.

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

dataCarrierDetect member

Data Carrier Detect (DCD)

clearToSend member

Clear To Send (CTS)

ringIndicator member

Ring Indicator (RI)

dataSetReady member

Data Set Ready (DSR)

The close() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", rejectpromise with an "InvalidStateError" DOMException and returnpromise.
Let cancelPromise be the result of invokingcancel on this.[[readable]] ora promise resolved with undefined ifthis.[[readable]] is null.
Let abortPromise be the result of invokingabort on this.[[writable]] ora promise resolved with undefined ifthis.[[writable]] is null.
Let pendingClosePromise be a new promise.
If this.[[readable]] andthis.[[writable]] are null, resolve pendingClosePromise with undefined.
Set this.[[pendingClosePromise]] topendingClosePromise.
Let combinedPromise be the result of getting a promise to wait for all with «cancelPromise, abortPromise,pendingClosePromise».
Set this.[[state]] to "closing".
React to combinedPromise.

If combinedPromise was fulfilled, then:
1. Run the following steps in parallel:
1. Invoke the operating system to close the serial port and release any associated resources.
2. Set this.[[state]] to "closed".
3. Set this.[[readFatal]] andthis.[[writeFatal]] to false.
4. Set this.[[pendingClosePromise]] to null.
5. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with undefined.
If combinedPromise was rejected with reason r, then:
1. Set this.[[pendingClosePromise]] tonull.
2. Queue a global task on the relevant global object of this using the serial port task source toreject promise with r.

Return promise.

The forget() method steps are:

If the user agent can't perform this action (e.g. permission was granted by administrator policy), return a promise resolved with undefined.
Run the following steps in parallel:
1. Set this.[[state]] to "forgetting".
2. Remove this from the sequence of serial ports on the system which the user has allowed the site to access as the result of a previous call to requestPort().
3. Set this.[[state]] to "forgotten".
4. Queue a global task on the relevant global object ofthis using the serial port task source to resolve promise with undefined.
Return promise.

This specification relies on a blocklist file in the https://github.com/WICG/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 aBluetoothServiceUUID with value "00001101-0000-1000-8000-00805f9b34fb".

A {{BluetoothServiceUUID} serviceUuid is ablocked Bluetooth service class UUID if the following steps return true:

Let uuid be the result of callingBluetoothUUID.getService() with serviceUuid.
Let blocklist be the result ofparsing the Bluetooth service class ID blocklist at https://github.com/WICG/serial/blob/main/blocklist.txt.
If blocklist contains uuid, return true.
If uuid is the Serial Port Profile service class ID, return false.
If uuid ends with "-0000-1000-8000-00805f9b34fb", return true.
Otherwise, return false.

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

The feature name for this feature is "serial"`.

The default allowlist for this feature is 'self'.

This section is non-normative.

This API poses similar a security risk to [WEB-BLUETOOTH] 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 therequestPort() 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 callingrequestPort() 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 [WEB-BLUETOOTH] 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.

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 in7. 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.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The following people contributed to the development of this document.

[dom]

DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/

[html]

HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/

[infra]

Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/

[PERMISSIONS-POLICY]

Permissions Policy. Ian Clelland. W3C. 10 February 2025. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/

[STREAMS]

Streams Standard. Adam Rice; Domenic Denicola; Mattias Buelens; 吉野剛史 (Takeshi Yoshino). WHATWG. Living Standard. URL: https://streams.spec.whatwg.org/

[WEB-BLUETOOTH]

Web Bluetooth. Jeffrey Yasskin. W3C Web Bluetooth Community Group. Draft Community Group Report. URL: https://webbluetoothcg.github.io/web-bluetooth/

[WEBIDL]

Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

[CSP3]

Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 24 March 2025. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/

[WEBUSB]

WebUSB API. W3C. Draft Community Group Report. URL: https://wicg.github.io/webusb/

Web Serial API (original) (raw)

Abstract

Status of This Document

Table of Contents