Intent to Implement and Ship: WebUSB Interface Class Filtering

4187 views
Skip to first unread message

Reilly Grant

unread,
Mar 20, 2018, 4:01:43 PM3/20/18
to blink-dev

Contact emails

rei...@chromium.org


Summary

The following set of USB interface classes, which should not be claimed using the WebUSB API, will be explicitly blocked by Blink: Audio, Video, HID, Mass Storage, Smart Card, Wireless Controller (Bluetooth and Wireless USB). These interface classes are already mostly blocked by an operating system’s built-in class drivers. This change establishes consistency across platforms.


Motivation

The WebUSB API is designed to provide a mechanism for device manufacturers and developers to build applications supporting novel hardware on the web instead of through native apps. As explained in the original Intent to Ship for WebUSB, most USB devices fall into one of a number of standardized device classes for which there are already high-level APIs provided by the Web Platform. For each of these interface classes the high-level API is the supported path and WebUSB is the unsupported path.


Risks


Interoperability and Compatibility

Developers may have implemented workarounds at an operating system level to allow devices of these classes to be claimed by web content using WebUSB. For example, on Windows, a specially crafted INF file can override the system default driver for a particular device with the WinUSB driver. Or, on Linux, udev rules can be configured so that the Linux kernel does not bind a driver to the device. After this change such workarounds will not be possible.


Web developers who have deployed any of the workarounds above will likely be negative on this change however the overall benefit to developers of continuing to provide this API for the scenarios in which it is fully supported outweighs this loss of functionality.


Ergonomics

Not applicable.


Activation

Not applicable.


Debuggability

To avoid developer confusion, a specific SecurityError message will be used when the claimInterface() method fails due to this filtering and a message will be logged to the console.


Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

All platforms other than Android WebView, which currently does not support WebUSB.


Is this feature fully tested by web-platform-tests?

This feature is currently tested by LayoutTests while it is decided to what extent the list of blocked interface classes should be part of the specification or Chrome-specific policy. Moving these tests into web-platform-tests is a trivial change once this question is resolved.


Link to entry on the feature dashboard

This is a small change that fits under the existing entry in the feature dashboard for WebUSB.

https://www.chromestatus.com/feature/5651917954875392


Requesting approval to ship?

Yes.


Jochen Eisinger

unread,
Mar 20, 2018, 4:03:04 PM3/20/18
to Reilly Grant, blink-dev
lgtm1

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAEmk%3DMZoYWMqMPsqqEHYqXtRjSY-ngKBpJyxFrupSvhBvVTkjg%40mail.gmail.com.

mk...@chromium.org

unread,
Mar 21, 2018, 5:38:44 AM3/21/18
to blink-dev, rei...@chromium.org
lgtm2. Developers already need to deal with `claimInterface` rejecting (because the user removed the device, for instance), so I'm hopeful that this won't cause any user-visible breakage.

Reilly Grant

unread,
Mar 23, 2018, 4:49:56 PM3/23/18
to Yoav Weiss, blink-dev
On Fri, Mar 23, 2018 at 1:25 PM Yoav Weiss <yo...@yoav.ws> wrote:
On Tue, Mar 20, 2018 at 9:01 PM Reilly Grant <rei...@chromium.org> wrote:

Contact emails

rei...@chromium.org


Summary

The following set of USB interface classes, which should not be claimed using the WebUSB API, will be explicitly blocked by Blink: Audio, Video, HID, Mass Storage, Smart Card, Wireless Controller (Bluetooth and Wireless USB). These interface classes are already mostly blocked by an operating system’s built-in class drivers. This change establishes consistency across platforms.


Motivation

The WebUSB API is designed to provide a mechanism for device manufacturers and developers to build applications supporting novel hardware on the web instead of through native apps. As explained in the original Intent to Ship for WebUSB, most USB devices fall into one of a number of standardized device classes for which there are already high-level APIs provided by the Web Platform. For each of these interface classes the high-level API is the supported path and WebUSB is the unsupported path.


Risks


Interoperability and Compatibility

Developers may have implemented workarounds at an operating system level to allow devices of these classes to be claimed by web content using WebUSB. For example, on Windows, a specially crafted INF file can override the system default driver for a particular device with the WinUSB driver. Or, on Linux, udev rules can be configured so that the Linux kernel does not bind a driver to the device. After this change such workarounds will not be possible.


Web developers who have deployed any of the workarounds above will likely be negative on this change however the overall benefit to developers of continuing to provide this API for the scenarios in which it is fully supported outweighs this loss of functionality.


IIUC, these workarounds require *users* to change their OS (either willingly or through social engineering). Is that correct?

Correct. These workarounds could be deployed through a standard native application installer.

Yoav Weiss

unread,
Mar 23, 2018, 4:52:48 PM3/23/18
to Reilly Grant, blink-dev
Thanks! I agree that while this may prevent some tinkering, it seems like the benefits of blocking this outweigh the loss.

LGTM3

ha...@thorenz.net

unread,
Jun 18, 2018, 11:11:14 AM6/18/18
to blink-dev
Actually, I do think this a too strict.

In my case I use an Arduino, which reports itself as a HID, since I want it to enter some Keys. Wich keys to enter is defined using a WebApp. As you can see I won't be able to make any settings, unless I find a way to switch of the HID functionality at runtime.

My suggestion is to block devices that ONLY implement the named classes. In other words: As soon as a device has a class that is not in the list, I should be able to claim it.

Reilly Grant

unread,
Jun 18, 2018, 12:45:33 PM6/18/18
to ha...@thorenz.net, blink-dev
On Mon, Jun 18, 2018 at 8:11 AM <ha...@thorenz.net> wrote:
Actually, I do think this a too strict.

In my case I use an Arduino, which reports itself as a HID, since I want it to enter some Keys. Wich keys to enter is defined using a WebApp. As you can see I won't be able to make any settings, unless I find a way to switch of the HID functionality at runtime.

I don't see how this follows. The operating system claims the HID interface, allowing the device to enter key events. The device also defines a non-HID endpoint which can be accessed by the WebApp to provide configuration to the device. Why does the WebApp also need to claim the HID interface? If events from the HID interface must always be mediated through the WebApp because they aren't signaling the right keys then why is it a HID interface at all?
 
My suggestion is to block devices that ONLY implement the named classes. In other words: As soon as a device has a class that is not in the list, I should be able to claim it.

I am concerned that this would make reasoning about the consequences of this change substantially more difficult and thus accidentally expose more sensitive devices.

tbra...@netflix.com

unread,
Jul 3, 2018, 3:20:15 AM7/3/18
to blink-dev
Not sure if you're still looking for feedback, but I've been experimenting with a video editing USB device which is now blocked. Use cases are numerous, but right now I'm working on cloud software that would greatly benefit from this integration. Would it be unreasonable to appeal specific vendor ids or loosen for non-keyboard HIDs?

Reilly Grant

unread,
Jul 3, 2018, 11:13:40 AM7/3/18
to tbra...@netflix.com, blink-dev
On Tue, Jul 3, 2018 at 12:20 AM tbranyen via blink-dev <blin...@chromium.org> wrote:
Not sure if you're still looking for feedback, but I've been experimenting with a video editing USB device which is now blocked. Use cases are numerous, but right now I'm working on cloud software that would greatly benefit from this integration. Would it be unreasonable to appeal specific vendor ids or loosen for non-keyboard HIDs?

Can you elaborate on the interface layout of this device so I can understand what it's functions are and why your application needs to access protected interfaces?
 
--
You received this message because you are subscribed to the Google Groups "blink-dev" group.

Tim Branyen

unread,
Jul 5, 2018, 11:52:23 PM7/5/18
to Reilly Grant, blink-dev
The device is a X-keys XK-12 Jog & Shuttle (http://xkeys.com/xkeys/xk12JSH.php). Although this company has many hacker-friendly input devices that could be whitelisted. The vendor id I use is 0x05F3. 

Here is the C driver: https://github.com/piengineering/xkeys/blob/master/piehid/hid-libusb.c

My use case is for pairing with Media Source Extensions to provide a video editor-like experience in a web application.
--
- Tim Branyen

Reilly Grant

unread,
Jul 6, 2018, 11:48:42 AM7/6/18
to tbra...@netflix.com, blink-dev
On Thu, Jul 5, 2018 at 8:52 PM Tim Branyen <tbra...@netflix.com> wrote:
The device is a X-keys XK-12 Jog & Shuttle (http://xkeys.com/xkeys/xk12JSH.php). Although this company has many hacker-friendly input devices that could be whitelisted. The vendor id I use is 0x05F3. 

Here is the C driver: https://github.com/piengineering/xkeys/blob/master/piehid/hid-libusb.c

My use case is for pairing with Media Source Extensions to provide a video editor-like experience in a web application.

Thank you for the additional information. I assumed from your original message that this was a video class device but I see now that it is an HID class device offering additional keys and control types not normally found on a keyboard or mouse. It perhaps could be modeled as a gamepad but that would require firmware changes.

Tim Branyen

unread,
Jul 16, 2018, 4:32:19 PM7/16/18
to Reilly Grant, blink-dev
Is the problem with the HID class that it would not be possible to differentiate this device from a keyboard? I briefly Googled and it does not seem possible, but this is not my area of expertise. I think the current filtering is a good first step, but I hope for the benefit of WebUSB adoption that the restrictions are loosened or an alternative approach is explored such as a whitelist registry.
--
- Tim Branyen

joem...@gmail.com

unread,
Oct 18, 2018, 12:39:43 PM10/18/18
to blink-dev, rei...@chromium.org
It should be possible to filter against keyboards, mice, and other boot devices with the interface subclass. I'm referencing the HID class definition section 4.3. I would think that this would satisfy any concerns of HID class devices claimed by the OS being misused while allowing other HID class-compliant devices to be used with WebUSB.

Reilly Grant

unread,
Oct 22, 2018, 12:25:01 PM10/22/18
to joem...@gmail.com, blin...@chromium.org
A better solution for accessing these kinds of HID devices is coming in the form of WebHID: https://www.chromestatus.com/feature/5172464636133376
Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

laurent....@gmail.com

unread,
Oct 22, 2018, 6:49:11 PM10/22/18
to blink-dev
Is there any hope for a seamless smart card experience in the future ? Are you considering a WebCCID interface ? Allowing smart card access on webapps, for the user to sign documents on administrative platform, without having to install buggy drivers, would be a dream come true.

christoph...@gmail.com

unread,
Nov 27, 2018, 8:26:11 PM11/27/18
to blink-dev, tbra...@netflix.com
I'm in the same position where I'm trying to access/control Exposure/Aperture/Brightness/Contrast/etc... for cameras. There are no Web API to control cameras in such a way beside WebUSB but it's just impossible to claim the right interface now.

Christophe

Harald Alvestrand

unread,
Nov 28, 2018, 3:58:16 AM11/28/18
to christoph...@gmail.com, blin...@chromium.org, tbra...@netflix.com
There is exposure/brightness etc exposed on the Image Capture API: https://w3c.github.io/mediacapture-image/


To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/3e25eb63-f1dc-42ce-87d5-203397e25fca%40chromium.org.

Christophe Balestra

unread,
Nov 28, 2018, 3:29:43 PM11/28/18
to h...@google.com, blin...@chromium.org, tbra...@netflix.com
In practice it doesn't really work though. For example I can control my FaceTime camera exposure using node-usb in Electron, but the exposure isn't available using the Image Capture API in Chrome. And actually none of the controls I mentioned earlier are available...

Reilly Grant

unread,
Nov 28, 2018, 4:59:39 PM11/28/18
to christoph...@gmail.com, Harald Alvestrand, blin...@chromium.org
Adding support in the Image Capture API for the FaceTime camera is tracked by issue 817805.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Bhaumik, Rijubrata

unread,
Nov 29, 2018, 4:03:29 AM11/29/18
to rei...@chromium.org, christoph...@gmail.com, Harald Alvestrand, blin...@chromium.org

If you are on Android or Linux/CrOS, Chrome Dev channel should have the support for exposure Time[1] and focus Distance[2].
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAEmk%3DMaTRhR3EK%2BbpMRZ7V6TAc7rQo08sNzsrMEbtk0cmhk7Rw%40mail.gmail.com.

---------------------------------------------------------------------
Intel Finland Oy
Registered Address: PL 281, 00181 Helsinki
Business Identity Code: 0357606 - 4
Domiciled in Helsinki

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Jordi M

unread,
Feb 8, 2019, 12:06:04 PM2/8/19
to blink-dev
I am quite new around here but started playing with the WebUSB API few days ago and I feel this as a too strict rule, if I am understanding it correctly, setting a considerably high limitation to the technology. I found this issue while I was trying to prepare a demo with a USB NFC card reader and writer. With this Interface Class Flitering enabled, which is the standard / proposed approach blink gives to surpass this limitations, or how we need to interact with it from the web? Is there any specification that explains how this must be approached, if chrome extensions are the way to go, ... ?
I saw there is a WebNFC implementation but only available for mobile devices (couldn't deep into it) but I feel this is a more generic topic to other devices.

Thanks,


On Tuesday, 20 March 2018 21:01:43 UTC+1, Reilly Grant wrote:

lewi...@gmail.com

unread,
Apr 24, 2019, 12:25:13 PM4/24/19
to blink-dev
Totally agree with Laurent.
Usb smartcard reader (interface class = 0x0B)have a really stronger security level than others like audio/mouse/keyboard usb interfaces.
They have:
- crypted serial communication (like secure messaging https://github.com/OpenSC/OpenSC/wiki/Secure-Messaging)
- smartcard with standard ISO 7816, https://en.wikipedia.org/wiki/ISO/IEC_7816, which implement all security features of EMV, crypto, etc.

Hi,
Lewix

mirr...@gmail.com

unread,
May 24, 2019, 12:14:35 PM5/24/19
to blink-dev
вторник, 20 марта 2018 г., 23:01:43 UTC+3 пользователь Reilly Grant написал:

Motivation

The WebUSB API is designed to provide a mechanism for device manufacturers and developers to build applications supporting novel hardware on the web instead of through native apps. As explained in the original Intent to Ship for WebUSB, most USB devices fall into one of a number of standardized device classes for which there are already high-level APIs provided by the Web Platform. For each of these interface classes the high-level API is the supported path and WebUSB is the unsupported path.


 Couldn't you make it a bit clearer: with WebUSB blocking access is there any built-in high-level javascript API to access smart cards? Is there any being in development? Or the motivation to block the access to smart cards is different from the stated one?
Reply all
Reply to author
Forward
0 new messages