Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add steps for parsing the blocklist and testing blocklistedness #239

Merged
merged 6 commits into from
Oct 12, 2023
Merged

Add steps for parsing the blocklist and testing blocklistedness #239

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7f28ba6
Add steps for parsing the blocklist and testing blocklistedness
nondebug Aug 4, 2023
00ee632
Remove Exposed=() and change invocation style
nondebug Aug 4, 2023
528592a
simplify blocklist parsing steps
nondebug Oct 10, 2023
39c50be
Replace ECMAscript String with infra string algorithms
nondebug Oct 10, 2023
0c7ace0
Replace Number.parseInt
nondebug Oct 10, 2023
a256a3a
set bcdDevice default value
nondebug Oct 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -631,6 +631,7 @@ run the following steps <a>in parallel</a>:
|enumerationResult|.
2. Let |devices| be a new empty {{Array}}.
3. For each |device| in |enumerationResult|:
1. If |device| is [=blocklisted=], [=iteration/continue=].
1. If this is the first call to this method, <a>check permissions for
|device|</a> with |storage|.
2. Search for an element |allowedDevice| in
Expand Down Expand Up @@ -676,6 +677,7 @@ steps <a>in parallel</a>:
4. Set <code>|status|.{{PermissionStatus/state}}</code> to <code>"ask"</code>.
5. <a>Enumerate all devices attached to the system</a>. Let this result be
|enumerationResult|.
1. Remove devices from |enumerationResult| if they are [=blocklisted=].
6. Remove devices from |enumerationResult| if they do not <a>match a device
filter</a> in <code>|options|.{{USBPermissionDescriptor/filters}}</code>.
7. Remove devices from |enumerationResult| if they <a>match a device filter</a>
Expand Down Expand Up @@ -2300,6 +2302,75 @@ slots</a> described in the following table:
1. Return <code>wMaxPacketSize</code> of |endpointDescriptor|.
</dl>

# The USB Blocklist # {#blocklist}

<xmp class="idl">
// USBBlocklistEntry is never exposed.
dictionary USBBlocklistEntry {
required unsigned short idVendor;
required unsigned short idProduct;
required unsigned short bcdDevice;
};
</xmp>

This specification relies on a <a href="https://raw.githubusercontent.com/WICG/webusb/main/blocklist.txt">blocklist.txt</a>
file in this repository to restrict the set of devices a website can access.

The result of <dfn>parsing the blocklist</dfn> at a {{URL}} |url| is a [=list=]
of {{USBBlocklistEntry}} objects produced by the following algorithm:

1. Fetch |url| and let |contents| be its body, decoded as UTF-8.
1. Let |lines| be the result of invoking
{{String/split(separator, limit)}} on |contents| with separator
<code>'\n'</code>.
nondebug marked this conversation as resolved.
Show resolved Hide resolved
1. Let |blocklist| be an empty [=list=].
1. [=list/For each=] |line| of |lines|:
1. Let |commentBegin| be the result of invoking
|line|.{{String/indexOf()}} with <code>'#'</code>.
1. If |commentBegin| is not -1, set |line| to the result of invoking
|line|.{{String/substring()}} with 0 and |commentBegin|.
nondebug marked this conversation as resolved.
Show resolved Hide resolved
1. Set |line| to the result of |line|.{{String/trimEnd()}}.
1. Let |components| be the result of invoking
|line|.{{String/split(separator, limit)}} with separator
<code>':'</code>.
nondebug marked this conversation as resolved.
Show resolved Hide resolved
1. If the [=list/size=] of |components| is not 2 or 3,
[=iteration/continue=].
1. Let |idVendor| be the result of invoking
{{Number}}.{{Number/parseInt(string, radix)}} with |components|[0]
and 16, or [=iteration/continue=] if a {{TypeError}} is thrown.
nondebug marked this conversation as resolved.
Show resolved Hide resolved
1. Let |idProduct| be the result of invoking
{{Number}}.{{Number/parseInt(string, radix)}} with |components|[1]
and 16, or [=iteration/continue=] if a {{TypeError}} is thrown.
1. If the [=list/size=] of |components| is:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. If the [=list/size=] of |components| is:
1. If the [=list/size=] of |components| is 3:

* 2: Let |bcdDevice| be <code>0xFFFF</code>.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is no longer necessary.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is still needed, otherwise bcdDevice will be uninitialized when we create the USBBlocklistEntry.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, then this needs to be swapped with the "if" above so that it is set to this default when components only has 2 elements.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand the issue. If we move the if lower then |components|[1] will be an OOB access if the line doesn't have any ':' code points.

How about:

      1. Let |components| be the result of [=strictly splitting=] |line|
         starting from the beginning of |line| on code point <code>':'</code>.
      1. If the [=list/size=] of |components| is not 2 or 3,
         [=iteration/continue=].
      1. Let |idVendor| be the result of interpreting |components|[0] as a
         hexadecimal number.
      1. Let |idProduct| be the result of interpreting |components|[1] as a
         hexadecimal number.
      1. Let |bcdDevice| be <code>0xFFFF</code>.
      1. If the [=list/size=] of |components| is 3, set |bcdDevice| to the
         result of interpreting |components|[2] as a hexadecimal number.
      1. [=list/Append=] a new {{USBBlocklistEntry}} with |idVendor|,
         |idProduct|, and |bcdDevice| to |blocklist|.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That LGTM.

* 3: Let |bcdDevice| be the result of invoking
{{Number}}.{{Number/parseInt(string, radix)}} with
|components|[2] and 16, or [=iteration/continue=] if a
{{TypeError}} is thrown.
1. [=list/Append=] a new {{USBBlocklistEntry}} with |idVendor|,
|idProduct|, and |bcdDevice| to |blocklist|.
1. Return |blocklist|.

The <dfn>USB blocklist</dfn> is the result of [=parsing the blocklist=] at
<a href="https://raw.githubusercontent.com/WICG/webusb/main/blocklist.txt">https://raw.githubusercontent.com/WICG/webusb/main/blocklist.txt</a>.
The UA should re-fetch the blocklist periodically, but it’s unspecified how
often.

A {{USBDevice}} |device| is <dfn>blocklisted</dfn> if the following steps return
"blocked":

1. [=list/For each=] |entry| of the [=USB blocklist=]:
1. If |device|.{{USBDevice/vendorId}} is not equal to
|entry|.{{USBBlocklistEntry/idVendor}}, [=iteration/continue=].
1. If |device|.{{USBDevice/productId}} is not equal to
|entry|.{{USBBlocklistEntry/idProduct}}, [=iteration/continue=].
1. Let |bcdDevice| be |device|.{{USBDevice/deviceVersionMajor}} << 8 +
|device|.{{USBDevice/deviceVersionMinor}} << 4 +
|device|.{{USBDevice/deviceVersionSubminor}}.
1. If |bcdDevice| is less than or equal to
|entry|.{{USBBlocklistEntry/bcdDevice}}, return "blocked".
1. Return "not blocked".

# Integrations # {#integrations}

<h3 id="permissions-policy" oldids="feature-policy">Permissions Policy</h3>
Expand Down Expand Up @@ -2561,4 +2632,5 @@ spec:infra; type:dfn; for:list; text:for each
spec:infra; type:dfn; for:list; text:append
spec:infra; type:dfn; for:list; text:empty
spec:infra; type:dfn; for:list; text:size
spec:url; type:interface; text:URL
</pre>
Loading