Skip to content

Commit

Permalink
Add the GATT blacklist.
Browse files Browse the repository at this point in the history 
Fixes #24.
  • Loading branch information
@jyasskin
jyasskin committed Jul 26, 2015
1 parent b35e737 commit 10b153d
Showing 1 changed file with 154 additions and 0 deletions.
154 changes: 154 additions & 0 deletions index.html
View file
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.
</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

0 comments on commit 10b153d

Please sign in to comment.