Skip to content

Commit

Permalink
Merge pull request #146 from jyasskin/blacklists
Browse files Browse the repository at this point in the history 
Add the GATT blacklist.
  • Loading branch information
@jyasskin
jyasskin committed Jul 28, 2015
2 parents 009e66b + 7489ff7 commit 2fb7588
Showing 1 changed file with 163 additions and 0 deletions.
163 changes: 163 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 @@ -592,6 +603,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 @@ -605,6 +621,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 @@ -1611,6 +1630,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 @@ -1638,6 +1662,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 @@ -1743,6 +1772,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 @@ -1769,6 +1803,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 @@ -1796,6 +1835,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 @@ -1821,6 +1865,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 @@ -1933,6 +1982,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 @@ -1959,6 +2013,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 @@ -1980,6 +2039,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 @@ -2023,6 +2087,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 @@ -2081,6 +2150,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 @@ -2316,6 +2389,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 @@ -2349,6 +2427,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 @@ -2940,6 +3023,86 @@ <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>,
let <var>uuid</var> be that UUID and
let <var>token</var> be "<code>exclude</code>".
</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>",
let <var>uuid</var> be that UUID and
let <var>token</var> be that token.
</li>
<li>
Otherwise, return an error and abort these steps.
</li>
<li>
If <var>uuid</var> is already in <var>result</var>,
return an error and abort these steps.
</li>
<li>
Add a mapping in <var>result</var> from <var>uuid</var> to <var>token</var>.
</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 2fb7588

Please sign in to comment.