Skip to content

Commit

Permalink
Discuss the [SecureContext] attribute.
Browse files Browse the repository at this point in the history 
Relies on whatwg/webidl#65
  • Loading branch information
@mikewest
mikewest committed Dec 11, 2015
1 parent 1bd4ef2 commit 6ad8e91
Show file tree
Hide file tree
Showing 2 changed files with 151 additions and 12 deletions.
108 changes: 98 additions & 10 deletions index.html
View file
Expand Up @@ -1096,11 +1096,12 @@ <h2 class="no-num no-toc no-ref heading settled" id="contents"><span class="cont
<li>
<a href="#framework"><span class="secno">2</span> <span class="content">Framework</span></a>
<ul class="toc">
<li><a href="#monkey-patching-idl"><span class="secno">2.1</span> <span class="content">Modifications to WebIDL</span></a>
<li>
<a href="#monkey-patching"><span class="secno">2.1</span> <span class="content">Modifications to HTML</span></a>
<a href="#monkey-patching-html"><span class="secno">2.2</span> <span class="content">Modifications to HTML</span></a>
<ul class="toc">
<li><a href="#monkey-patching-shared-workers"><span class="secno">2.1.1</span> <span class="content">Shared Workers</span></a>
<li><a href="#monkey-patching-global-object"><span class="secno">2.1.2</span> <span class="content">Feature Detection</span></a>
<li><a href="#monkey-patching-shared-workers"><span class="secno">2.2.1</span> <span class="content">Shared Workers</span></a>
<li><a href="#monkey-patching-global-object"><span class="secno">2.2.2</span> <span class="content">Feature Detection</span></a>
</ul>
</ul>
<li>
Expand Down Expand Up @@ -1160,6 +1161,7 @@ <h2 class="no-num no-toc no-ref heading settled" id="contents"><span class="cont
<li><a href="#informative"><span class="secno"></span> <span class="content">Informative References</span></a>
</ul>
<li><a href="#idl-index"><span class="secno"></span> <span class="content">IDL Index</span></a>
<li><a href="#issues-index"><span class="secno"></span> <span class="content">Issues Index</span></a>
</ul>
</div>
<main>
Expand Down Expand Up @@ -1544,9 +1546,34 @@ <h2 class="heading settled" data-level="2" id="framework"><span class="secno">2.
the algorithm in <a href="#settings-object">§3.1 Is settings object a secure context?</a> returns "<code>Secure</code>". The <a data-link-type="dfn" href="http://www.w3.org/TR/html5/webappapis.html#settings-object">settings
object</a> is otherwise <dfn data-dfn-type="dfn" data-export="" data-lt="non-secure context" id="non-secure-context">non-secure<a class="self-link" href="#non-secure-context"></a></dfn>.</p>
<p>Likewise, a <a data-link-type="dfn" href="http://www.w3.org/TR/html5/webappapis.html#global-object">global object</a> is considered a <a data-link-type="dfn" href="#secure-context">secure context</a> if its <a data-link-type="dfn" href="http://www.w3.org/TR/html5/webappapis.html#relevant-settings-object-for-a-global-object">relevant settings object</a> is a <a data-link-type="dfn" href="#secure-context">secure context</a>.</p>
<h3 class="heading settled" data-level="2.1" id="monkey-patching"><span class="secno">2.1. </span><span class="content">Modifications to HTML</span><a class="self-link" href="#monkey-patching"></a></h3>
<h4 class="heading settled" data-level="2.1.1" id="monkey-patching-shared-workers"><span class="secno">2.1.1. </span><span class="content">Shared Workers</span><a class="self-link" href="#monkey-patching-shared-workers"></a></h4>
<p>The <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/workers/#dom-sharedworker">SharedWorker()</a></code> constructor will throw a <code>SecurtyError</code> exception if
<h3 class="heading settled" data-level="2.1" id="monkey-patching-idl"><span class="secno">2.1. </span><span class="content">Modifications to WebIDL</span><a class="self-link" href="#monkey-patching-idl"></a></h3>
<p>A new <code>[SecureContext]</code> attribute is available for operators, which ensures
that they will only be <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-exposed">exposed</a> into secure contexts. The following
example should help:</p>
<div class="example" id="example-bb4ea7aa">
<a class="self-link" href="#example-bb4ea7aa"></a>
<pre class="idl">interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="examplefeature">ExampleFeature<a class="self-link" href="#examplefeature"></a></dfn> {
// This call will succeed in all contexts.
Promise &lt;double> <dfn class="idl-code" data-dfn-for="ExampleFeature" data-dfn-type="method" data-export="" data-lt="calculateNotSoSecretResult()" id="dom-examplefeature-calculatenotsosecretresult">calculateNotSoSecretResult<a class="self-link" href="#dom-examplefeature-calculatenotsosecretresult"></a></dfn>();

// This operation will not be exposed to a non-secure context. If such a context
// is somehow able to call it despite this precaution, the Promise will be
// immedietely rejected with a 'SecurityError' exception.
[SecureContext] Promise&lt;double> <dfn class="idl-code" data-dfn-for="ExampleFeature" data-dfn-type="method" data-export="" data-lt="calculateSecretResult()" id="dom-examplefeature-calculatesecretresult">calculateSecretResult<a class="self-link" href="#dom-examplefeature-calculatesecretresult"></a></dfn>();

// The same applies here: the operation will not be exposed to a non-secure context,
// and if somehow called from a non-secure context, a 'SecurityError'
// exception will be thrown.
[SecureContext] boolean <dfn class="idl-code" data-dfn-for="ExampleFeature" data-dfn-type="method" data-export="" data-lt="getSecretBoolean()" id="dom-examplefeature-getsecretboolean">getSecretBoolean<a class="self-link" href="#dom-examplefeature-getsecretboolean"></a></dfn>();
};
</pre>
</div>
<p>Specification authors are encouraged to use this attribute when defining new
features.</p>
<p class="issue" id="issue-020b0dc4"><a class="self-link" href="#issue-020b0dc4"></a> This addition is currently under review. <a href="https://github.com/heycam/webidl/issues/65">&lt;https://github.com/heycam/webidl/issues/65></a></p>
<h3 class="heading settled" data-level="2.2" id="monkey-patching-html"><span class="secno">2.2. </span><span class="content">Modifications to HTML</span><a class="self-link" href="#monkey-patching-html"></a></h3>
<h4 class="heading settled" data-level="2.2.1" id="monkey-patching-shared-workers"><span class="secno">2.2.1. </span><span class="content">Shared Workers</span><a class="self-link" href="#monkey-patching-shared-workers"></a></h4>
<p>The <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/workers/#dom-sharedworker">SharedWorker()</a></code> constructor will throw a <code>SecurityError</code> exception if
a <a data-link-type="dfn" href="#secure-context">secure context</a> attempts to attach to an Worker which is not a <a data-link-type="dfn" href="#secure-context">secure context</a>, and if a non-secure context attempts to attach to a
Worker which is a <a data-link-type="dfn" href="#secure-context">secure context</a>. The constructor is modified as
follows:</p>
Expand All @@ -1564,7 +1591,7 @@ <h4 class="heading settled" data-level="2.1.1" id="monkey-patching-shared-worker
these steps.</p>
</ol>
</ol>
<h4 class="heading settled" data-level="2.1.2" id="monkey-patching-global-object"><span class="secno">2.1.2. </span><span class="content">Feature Detection</span><a class="self-link" href="#monkey-patching-global-object"></a></h4>
<h4 class="heading settled" data-level="2.2.2" id="monkey-patching-global-object"><span class="secno">2.2.2. </span><span class="content">Feature Detection</span><a class="self-link" href="#monkey-patching-global-object"></a></h4>
<p>To determine whether a context is capable of making use of features which
require <a data-link-type="dfn" href="#secure-context">secure contexts</a>, a simple boolean attribute is added to the
global object:</p>
Expand Down Expand Up @@ -1859,6 +1886,22 @@ <h3 class="heading settled" data-level="7.3" id="new"><span class="secno">7.3. <
</ol>
</ol>
</div>
<p>Authors should also ensure that sensitive APIs are only exposed to <a data-link-type="dfn" href="#secure-context">secure
contexts</a> by guarding them with the <code>[SecureContext]</code> attribute:</p>
<div class="example" id="example-63db205d">
<a class="self-link" href="#example-63db205d"></a>
<pre class="idl">[SecureContext]
interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="sensitivefeature">SensitiveFeature<a class="self-link" href="#sensitivefeature"></a></dfn> {
Promise&lt;double> <dfn class="idl-code" data-dfn-for="SensitiveFeature" data-dfn-type="method" data-export="" data-lt="getTheSecretDouble()" id="dom-sensitivefeature-getthesecretdouble">getTheSecretDouble<a class="self-link" href="#dom-sensitivefeature-getthesecretdouble"></a></dfn>();
};

// Or:

interface <dfn class="idl-code" data-dfn-type="interface" data-export="" id="anothersensitivefeature">AnotherSensitiveFeature<a class="self-link" href="#anothersensitivefeature"></a></dfn> {
[SecureContext] void <dfn class="idl-code" data-dfn-for="AnotherSensitiveFeature" data-dfn-type="method" data-export="" data-lt="doThatPowerfulThing()" id="dom-anothersensitivefeature-dothatpowerfulthing">doThatPowerfulThing<a class="self-link" href="#dom-anothersensitivefeature-dothatpowerfulthing"></a></dfn>();
};
</pre>
</div>
<h3 class="heading settled" data-level="7.4" id="legacy"><span class="secno">7.4. </span><span class="content">Restricting Legacy Features</span><a class="self-link" href="#legacy"></a></h3>
<p><em>This section is non-normative.</em></p>
<p>The list above clearly includes some existing functionality that is currently
Expand Down Expand Up @@ -1953,15 +1996,23 @@ <h3 class="no-ref no-num heading settled" id="conformant-algorithms"><span class
<h2 class="no-num heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2>
<h3 class="no-num heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3>
<ul class="indexlist">
<li><a href="#anothersensitivefeature">AnotherSensitiveFeature</a><span>, in §7.3</span>
<li><a href="#dom-examplefeature-calculatenotsosecretresult">calculateNotSoSecretResult()</a><span>, in §2.1</span>
<li><a href="#dom-examplefeature-calculatesecretresult">calculateSecretResult()</a><span>, in §2.1</span>
<li><a href="#dom-anothersensitivefeature-dothatpowerfulthing">doThatPowerfulThing()</a><span>, in §7.3</span>
<li><a href="#examplefeature">ExampleFeature</a><span>, in §2.1</span>
<li><a href="#dom-examplefeature-getsecretboolean">getSecretBoolean()</a><span>, in §2.1</span>
<li><a href="#dom-sensitivefeature-getthesecretdouble">getTheSecretDouble()</a><span>, in §7.3</span>
<li>
isSecureContext
<ul>
<li><a href="#dom-window-issecurecontext">attribute for Window</a><span>, in §2.1.2</span>
<li><a href="#dom-workerglobalscope-issecurecontext">attribute for WorkerGlobalScope</a><span>, in §2.1.2</span>
<li><a href="#dom-window-issecurecontext">attribute for Window</a><span>, in §2.2.2</span>
<li><a href="#dom-workerglobalscope-issecurecontext">attribute for WorkerGlobalScope</a><span>, in §2.2.2</span>
</ul>
<li><a href="#non-secure-context">non-secure context</a><span>, in §2</span>
<li><a href="#potentially-trustworthy-origin">potentially trustworthy origin</a><span>, in §3.2</span>
<li><a href="#secure-context">secure context</a><span>, in §2</span>
<li><a href="#sensitivefeature">SensitiveFeature</a><span>, in §7.3</span>
</ul>
<h3 class="no-num heading settled" id="index-defined-elsewhere"><span class="content">Terms defined by reference</span><a class="self-link" href="#index-defined-elsewhere"></a></h3>
<ul class="indexlist">
Expand Down Expand Up @@ -2026,6 +2077,11 @@ <h3 class="no-num heading settled" id="index-defined-elsewhere"><span class="con
<ul>
<li><a href="http://www.w3.org/2014/Process-20140801/#rec-modify">modify a specification</a>
</ul>
<li>
<a data-link-type="biblio" href="#biblio-webidl">[WebIDL]</a> defines the following terms:
<ul>
<li><a href="https://heycam.github.io/webidl/#dfn-exposed">exposed</a>
</ul>
<li>
<a data-link-type="biblio" href="#biblio-workers">[workers]</a> defines the following terms:
<ul>
Expand All @@ -2050,6 +2106,8 @@ <h3 class="no-num heading settled" id="normative"><span class="content">Normativ
<dd>Mike West. <a href="http://www.w3.org/TR/mixed-content/">Mixed Content</a>. 8 October 2015. CR. URL: <a href="http://www.w3.org/TR/mixed-content/">http://www.w3.org/TR/mixed-content/</a>
<dt id="biblio-w3c-process"><a class="self-link" href="#biblio-w3c-process"></a>[W3C-PROCESS]
<dd>Charles McCathie Nevile. <a href="http://www.w3.org/2014/Process-20140801/">World Wide Web Consortium Process Document</a>. URL: <a href="http://www.w3.org/2014/Process-20140801/">http://www.w3.org/2014/Process-20140801/</a>
<dt id="biblio-webidl"><a class="self-link" href="#biblio-webidl"></a>[WebIDL]
<dd>Cameron McCormack; Boris Zbarsky. <a href="http://www.w3.org/TR/WebIDL-1/">WebIDL Level 1</a>. 4 August 2015. WD. URL: <a href="http://www.w3.org/TR/WebIDL-1/">http://www.w3.org/TR/WebIDL-1/</a>
<dt id="biblio-dom"><a class="self-link" href="#biblio-dom"></a>[DOM]
<dd>Anne van Kesteren; et al. <a href="http://www.w3.org/TR/dom/">W3C DOM4</a>. 6 October 2015. PR. URL: <a href="http://www.w3.org/TR/dom/">http://www.w3.org/TR/dom/</a>
<dt id="biblio-geolocation-api"><a class="self-link" href="#biblio-geolocation-api"></a>[geolocation-API]
Expand Down Expand Up @@ -2099,14 +2157,44 @@ <h3 class="no-num heading settled" id="informative"><span class="content">Inform
<dd>Alex Russell; Jungkee Song; Jake Archibald. <a href="http://www.w3.org/TR/service-workers/">Service Workers</a>. 25 June 2015. WD. URL: <a href="http://www.w3.org/TR/service-workers/">http://www.w3.org/TR/service-workers/</a>
</dl>
<h2 class="no-num heading settled" id="idl-index"><span class="content">IDL Index</span><a class="self-link" href="#idl-index"></a></h2>
<pre class="idl">partial interface <a class="idl-code" data-link-type="interface" href="http://www.w3.org/TR/dom/#interface-window">Window</a> {
<pre class="idl">interface <a href="#examplefeature">ExampleFeature</a> {
// This call will succeed in all contexts.
Promise &lt;double> <a href="#dom-examplefeature-calculatenotsosecretresult">calculateNotSoSecretResult</a>();

// This operation will not be exposed to a non-secure context. If such a context
// is somehow able to call it despite this precaution, the Promise will be
// immedietely rejected with a 'SecurityError' exception.
[SecureContext] Promise&lt;double> <a href="#dom-examplefeature-calculatesecretresult">calculateSecretResult</a>();

// The same applies here: the operation will not be exposed to a non-secure context,
// and if somehow called from a non-secure context, a 'SecurityError'
// exception will be thrown.
[SecureContext] boolean <a href="#dom-examplefeature-getsecretboolean">getSecretBoolean</a>();
};

partial interface <a class="idl-code" data-link-type="interface" href="http://www.w3.org/TR/dom/#interface-window">Window</a> {
readonly attribute boolean <a data-readonly="" data-type="boolean " href="#dom-window-issecurecontext">isSecureContext</a>;
};

partial interface <a class="idl-code" data-link-type="interface" href="http://www.w3.org/TR/workers/#workerglobalscope">WorkerGlobalScope</a> {
readonly attribute boolean <a data-readonly="" data-type="boolean " href="#dom-workerglobalscope-issecurecontext">isSecureContext</a>;
};

[SecureContext]
interface <a href="#sensitivefeature">SensitiveFeature</a> {
Promise&lt;double> <a href="#dom-sensitivefeature-getthesecretdouble">getTheSecretDouble</a>();
};

// Or:

interface <a href="#anothersensitivefeature">AnotherSensitiveFeature</a> {
[SecureContext] void <a href="#dom-anothersensitivefeature-dothatpowerfulthing">doThatPowerfulThing</a>();
};

</pre>
<h2 class="no-num heading settled" id="issues-index"><span class="content">Issues Index</span><a class="self-link" href="#issues-index"></a></h2>
<div style="counter-reset:issue">
<div class="issue"> This addition is currently under review. <a href="https://github.com/heycam/webidl/issues/65">&lt;https://github.com/heycam/webidl/issues/65></a><a href="#issue-020b0dc4"> ↵ </a></div>
</div>
</body>
</html>
55 changes: 53 additions & 2 deletions index.src.html
View file
Expand Up @@ -98,6 +98,9 @@ <h1>Secure Contexts</h1>
urlPrefix: webappapis.html
text: creation URL
text: HTTPS state
spec: WEBIDL; urlPrefix: https://heycam.github.io/webidl/
type: dfn
text: exposed; url: dfn-exposed
</pre>
<pre class="biblio">
{
Expand Down Expand Up @@ -616,11 +619,41 @@ <h2 id="framework">Framework</h2>
Likewise, a <a>global object</a> is considered a <a>secure context</a> if its
<a>relevant settings object</a> is a <a>secure context</a>.

<h3 id="monkey-patching">Modifications to HTML</h3>
<h3 id="monkey-patching-idl">Modifications to WebIDL</h3>

A new `[SecureContext]` attribute is available for operators, which ensures
that they will only be <a>exposed</a> into secure contexts. The following
example should help:

<div class="example">
<pre class="idl">
interface ExampleFeature {
// This call will succeed in all contexts.
Promise &lt;double> calculateNotSoSecretResult();

// This operation will not be exposed to a non-secure context. If such a context
// is somehow able to call it despite this precaution, the Promise will be
// immedietely rejected with a 'SecurityError' exception.
[SecureContext] Promise&lt;double> calculateSecretResult();

// The same applies here: the operation will not be exposed to a non-secure context,
// and if somehow called from a non-secure context, a 'SecurityError'
// exception will be thrown.
[SecureContext] boolean getSecretBoolean();
};
</pre>
</div>

Specification authors are encouraged to use this attribute when defining new
features.

ISSUE(heycam/webidl#65): This addition is currently under review.

<h3 id="monkey-patching-html">Modifications to HTML</h3>

<h4 id="monkey-patching-shared-workers">Shared Workers</h4>

The {{SharedWorker()}} constructor will throw a `SecurtyError` exception if
The {{SharedWorker()}} constructor will throw a `SecurityError` exception if
a <a>secure context</a> attempts to attach to an Worker which is not a
<a>secure context</a>, and if a non-secure context attempts to attach to a
Worker which is a <a>secure context</a>. The constructor is modified as
Expand Down Expand Up @@ -1026,6 +1059,24 @@ <h3 id="new">Restricting New Features</h3>
</ol>
</div>

Authors should also ensure that sensitive APIs are only exposed to <a>secure
contexts</a> by guarding them with the `[SecureContext]` attribute:

<div class="example">
<pre class="idl">
[SecureContext]
interface SensitiveFeature {
Promise&lt;double> getTheSecretDouble();
};

// Or:

interface AnotherSensitiveFeature {
[SecureContext] void doThatPowerfulThing();
};
</pre>
</div>

<h3 id="legacy">Restricting Legacy Features</h3>

<em>This section is non-normative.</em>
Expand Down

0 comments on commit 6ad8e91

Please sign in to comment.