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

Jump to bottom

Add the GATT blacklist. #146

Merged
merged 2 commits into from Jul 28, 2015
Merged

Add the GATT blacklist. #146

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10b153d
Add the GATT blacklist.
jyasskin Jul 24, 2015
7489ff7
Address (ban) duplicated UUIDs in the blacklist.
jyasskin Jul 27, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
154 changes: 154 additions & 0 deletions index.html
View file
Open in desktop
Expand Up @@ -325,6 +325,17 @@ <h2>Device access is powerful</h2>
<section class="informative">
<h2>Attacks on devices</h2>

<p>
Communication from websites can break the security model of some devices,
which assume they only receive messages from
the trusted operating system of a remote device.
Human Interface Devices are a prominent example,
where allowing a website to communicate would allow that site to log keystrokes.
This specification includes a blacklist of
such vulnerable services, characteristics, and descriptors
to prevent websites from taking advantage of them.
</p>

<p>
We expect that many devices are vulnerable to unexpected data delivered to their radio.
In the past, these devices had to be exploited one-by-one,
Expand Down Expand Up @@ -587,6 +598,11 @@ <h2>Device Discovery</h2>
If any of the <a>BluetoothUUID.getService</a> calls threw an exception,
<a>reject</a> <var>promise</var> with that exception and abort these steps.
</li>
<li>
If any <var>service</var> in <var>services</var> is <a>blacklisted</a>,
<a>reject</a> <var>promise</var> with a <a>SecurityError</a>
and abort these steps.
</li>
<li>Append <code>{services: <var>services</var>}</code> to <var>uuidFilters</var>.</li>
<li>Add the elements of <var>services</var> to <var>requiredServiceUUIDs</var>.</li>
</ol>
Expand All @@ -600,6 +616,9 @@ <h2>Device Discovery</h2>
If any of the <a>BluetoothUUID.getService</a> calls threw an exception,
<a>reject</a> <var>promise</var> with that exception and abort these steps.
</li>
<li>
Remove from <var>optionalServiceUUIDs</var> any UUIDs that are <a>blacklisted</a>.
</li>
</ol>
</li>
<li>
Expand Down Expand Up @@ -1606,6 +1625,11 @@ <h2><dfn>BluetoothGATTRemoteServer</dfn></h2>
If <a>BluetoothUUID.getService</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>service</var> is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the first primary GATT service
Expand Down Expand Up @@ -1633,6 +1657,11 @@ <h2><dfn>BluetoothGATTRemoteServer</dfn></h2>
If <a>BluetoothUUID.getService</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>service</var> is present and is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for the primary GATT services
on <code>this@[[\representedDevice]]</code>
Expand Down Expand Up @@ -1738,6 +1767,11 @@ <h2><dfn>BluetoothGATTService</dfn></h2>
If <a>BluetoothUUID.getCharacteristic</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>characteristic</var> is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the first GATT characteristic within this Service
Expand All @@ -1764,6 +1798,11 @@ <h2><dfn>BluetoothGATTService</dfn></h2>
If <a>BluetoothUUID.getCharacteristic</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>characteristic</var> is present and is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the GATT characteristics that are within this Service and,
Expand Down Expand Up @@ -1791,6 +1830,11 @@ <h2><dfn>BluetoothGATTService</dfn></h2>
If <a>BluetoothUUID.getService</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>service</var> is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for the first GATT included service
within this Service whose UUID is <var>service</var>,
Expand All @@ -1816,6 +1860,11 @@ <h2><dfn>BluetoothGATTService</dfn></h2>
If <a>BluetoothUUID.getService</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>service</var> is present and is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the GATT Included Services that are within this Service and,
Expand Down Expand Up @@ -1928,6 +1977,11 @@ <h2><dfn>BluetoothGATTCharacteristic</dfn></h2>
If <a>BluetoothUUID.getDescriptor</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>descriptor</var> is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the first GATT descriptor within this Characteristic
Expand All @@ -1954,6 +2008,11 @@ <h2><dfn>BluetoothGATTCharacteristic</dfn></h2>
If <a>BluetoothUUID.getDescriptor</a> threw an exception,
return <a>a promise rejected with</a> that exception and abort these steps.
</li>
<li>
If <var>descriptor</var> is present and is <a>blacklisted</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
<a>Query the Bluetooth cache</a> for
the GATT descriptors that are within this Characteristic and,
Expand All @@ -1975,6 +2034,11 @@ <h2><dfn>BluetoothGATTCharacteristic</dfn></h2>
and run the following steps <a>in parallel</a>:
</p>
<ol>
<li>
If <code>this.uuid</code> is <a>blacklisted for reads</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
Let <var>characteristic</var> be the <a>Characteristic</a>
that <code>this</code> represents.
Expand Down Expand Up @@ -2018,6 +2082,11 @@ <h2><dfn>BluetoothGATTCharacteristic</dfn></h2>
MUST run the following steps:
</p>
<ol>
<li>
If <code>this.uuid</code> is <a>blacklisted for writes</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
Let <var>characteristic</var> be the <a>Characteristic</a>
that <code>this</code> represents.
Expand Down Expand Up @@ -2076,6 +2145,10 @@ <h2><dfn>BluetoothGATTCharacteristic</dfn></h2>
See <a href="#notification-events"></a> for details of receiving notifications.
</p>
<ol>
<li>
If <code>this.uuid</code> is <a>blacklisted for reads</a>,
<a>reject</a> <var>promise</var> with a <a>SecurityError</a> and abort these steps.
</li>
<li>
Let <var>characteristic</var> be
the GATT <a>Characteristic</a> that <code>this</code> represents.
Expand Down Expand Up @@ -2311,6 +2384,11 @@ <h2><dfn>BluetoothGATTDescriptor</dfn></h2>
and run the following steps <a>in parallel</a>:
</p>
<ol>
<li>
If <code>this.uuid</code> is <a>blacklisted for reads</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
Let <var>descriptor</var> be the <a>Descriptor</a>
that <code>this</code> represents.
Expand Down Expand Up @@ -2344,6 +2422,11 @@ <h2><dfn>BluetoothGATTDescriptor</dfn></h2>
MUST run the following steps:
</p>
<ol>
<li>
If <code>this.uuid</code> is <a>blacklisted for writes</a>,
return <a>a promise rejected with</a> a <a>SecurityError</a>
and abort these steps.
</li>
<li>
Let <var>descriptor</var> be the <a>Descriptor</a>
that <code>this</code> represents.
Expand Down Expand Up @@ -2935,6 +3018,77 @@ <h2>Standardized UUIDs</h2>
</section>
</section>

<section>
<h2>The GATT Blacklist</h2>

<p>
This specification relies on a blacklist file in the
<a href="https://github.com/WebBluetoothCG/registries"
>https://github.com/WebBluetoothCG/registries</a> repository
to restrict the set of GATT attributes a website can access.
</p>

<p>
The result of <dfn>parsing the blacklist</dfn> at a URL <var>url</var>
is a map from <a>valid UUID</a>s to tokens, or an error,
produced by the following algorithm:
</p>
<ol>
<li>Fetch <var>url</var>, and let <var>contents</var> be its body, decoded as UTF-8.</li>
<li>Let <var>lines</var> be <var>contents</var> split on <code>'\n'</code>.</li>
<li>
Let <var>result</var> be an empty map.
</li>
<li>
For each <var>line</var> in <var>lines</var>, do the following sub-steps:
<ol>
<li>
If <var>line</var> is empty or its first character is <code>'#'</code>,
continue to the next line.
</li>
<li>
If <var>line</var> consists of just a <a>valid UUID</a>,
add a mapping from that UUID to "<code>exclude</code>" in <var>result</var>.
</li>
<li>
If <var>line</var> consists of a <a>valid UUID</a>, a space (U+0020),
and one of the tokens "<code>exclude-reads</code>" or "<code>exclude-writes</code>",
add a mapping from that UUID, to the token.
Copy link
Contributor

Choose a reason for hiding this comment

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

Previous block mentions adding a mapping to result. This block likely should mention 'result' as well, or perhaps have 3 maps. To be very precise language should indicate what happens when a UUID appears multiple times with different tokens.

Copy link
Member Author

Choose a reason for hiding this comment

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

Done, still with a single map.

</li>
<li>
Otherwise, return an error and abort these steps.
</li>
</ol>
</li>
<li>Return <var>result</var>.</li>
</ol>

<p>
The <dfn>GATT blacklist</dfn> is the result of <a>parsing the blacklist</a> at
<a href="https://github.com/WebBluetoothCG/registries/blob/master/gatt_blacklist.txt"
>https://github.com/WebBluetoothCG/registries/blob/master/gatt_blacklist.txt</a>.
The UA should re-fetch the blacklist periodically, but it's unspecified how often.
</p>

<p>
A <a>UUID</a> is <dfn>blacklisted</dfn> if either
the <a>GATT blacklist</a>'s value is an error,
or the UUID maps to "<code>exclude</code>" in the <a>GATT blacklist</a>.
</p>
<p>
A <a>UUID</a> is <dfn>blacklisted for reads</dfn> if either
the <a>GATT blacklist</a>'s value is an error,
or the UUID maps to either "<code>exclude</code>" or "<code>exclude-reads</code>"
in the <a>GATT blacklist</a>.
</p>
<p>
A <a>UUID</a> is <dfn>blacklisted for writes</dfn> if either
the <a>GATT blacklist</a>'s value is an error,
or the UUID maps to either "<code>exclude</code>" or "<code>exclude-writes</code>"
in the <a>GATT blacklist</a>.
</p>
</section>

<section>
<h2>Extensions to the Navigator Interface</h2>

Expand Down