--- a/keydiscovery-source.html Mon Dec 10 09:51:48 2012 -0800
+++ b/keydiscovery-source.html Mon Dec 10 15:42:09 2012 -0800
@@ -51,7 +51,7 @@
// previousPublishDate: "2012-05-02",
// edEnd: "",
// previousMaturity: "ED",
- edDraftURI: "http://www.w3.org/TR/2012/WD-WebCryptoKey-20121207/",
+ edDraftURI: "http://dvcs.w3.org/hg/webcrypto-keydiscovery/raw-file/tip/keydiscovery.html",
wg: "Web Cryptography WG",
//wgURI: "http://www.w3.org/TR/WebCryptoKey",
wgPublicList: "public-webcrypto",
@@ -94,6 +94,13 @@
<section>
<h2>Use cases</h2>
+ <section>
+ <h3>Out of band key provisioning</h3>
+ <p>Web applications may wish to use keys that have been provisioned through means outside the scope of the WebCrypto API. This may include keys that are provisioned through platform-specific native APIs, stored in secure elements such as trusted platform modules (TPMs), individually bound to devices at time of manufacturing or otherwise installed via device-specific provisioning protocols.</p>
+ <p>Such keys may, for example, be used to assist in identifying a device to a specific web service. User agents may choose to expose such keys to web applications after implementing appropriate security and privacy mitigations, including gaining user consent.</p>
+
+<p>In this scenario, a web application discovers a pre-provisioned key based on its name and uses it to perform authorized cryptographic operations as part of a protocol with a server. The server may utilize knowledge obtained out-of-band regarding the key's provisioning to make access control and policy decisions, such as inferring the identity of the device and customizing its responses based on that.</p>
+ </section>
<p></p>
</section>
@@ -190,55 +197,101 @@
</section>
</section>
</section>
- <section>
- <h2>Dependencies</h2>
- <p>This specification relies on underlying specifications.</p>
+
+ <section class="section" id="dependencies">
+ <h3>Dependencies</h3>
<p>
- <dl>
- <dt>Web Cryptography API</dt>
- <dd><p>A <a>conforming user agent</a> MUST support the Web Cryptography API [[WEBCRYPTO]].</p></dd>
- </dl>
+ This specification relies on several other underlying specifications.
</p>
+ <dl>
+ <dt>HTML5</dt>
+ <dd>The terms and algorithms
+ <dfn title="Window"><code>Window</code></dfn>,
+ <dfn title="Function"><code>Function</code></dfn>,
+ <dfn>origin</dfn>, <dfn>same origin</dfn>, <dfn>structured clone</dfn>,
+ <dfn>structured clone algorithm</dfn>, <dfn>task</dfn>, <dfn>task source</dfn>,
+ <dfn title="queue-a-task">queue a task</dfn>
+ and <dfn title="fire-a-simple-event">fire a simple event</dfn> are defined by the HTML 5
+ specification [[!HTML5]].
+ </dd>
+ <dt>Web Cryptography API</dt>
+ <dd><p>A <a>conforming user agent</a> MUST support the Web Cryptography API [[!WEBCRYPTO]].</p>
+ <p>The terms <dfn title="Key"><code>Key</code></dfn> and <dfn title="KeyOperation"><code>KeyOperation</code></dfn> are defined in [[!WEBCRYPTO]].</p>
+ </dd>
+ <dt>WebIDL</dt>
+ <dd>Many of the interface definitions and all of the IDL in this spec depends on [[!WEBIDL]].</dd>
+ <dt>WebWorkers</dt>
+ <dd>The term <dfn title="WorkerGlobalScope"><a class="externalDFN"><code>WorkerGlobalScope</code></a></dfn> is defined by
+ the WebWorkers specification [[!WEBWORKERS]].</dd>
+ </dl>
</section>
- <section>
- <h2>Terminology</h2>
- <p>The terms <dfn>origin</dfn> and <dfn>same origin</dfn> are defined by the HTML specification [[!HTML5]].</p>
-
- </section>
+
<section>
<h2>API definition</h2>
<section class="informative"><h3>Overview</h3>
- <p>This specification defines a new <a><code>cryptokeys</code></a> attribute on the <code>Window</code> object. This attribute is an object supporting a method, <a><code>getkeysByName</code></a> which may be used to get an array of all keys matching a <code>DOMString</code> name specifier. The array of keys is returned through a callback function, in the form of a <a>KeyArray</a> object.</p></section>
- <section><h3>KeyArray interface</h3>
- <dl title="interface KeyArray" class="idl">
- <dt>readonly attribute unsigned long length</dt><dd>The number of key objects in the array.</dd>
- <dt>Key? get(unsigned long index)</dt><dd>Get a Key object by index.</dd>
- </dl>
- </section>
+ <p>This specification defines a new <a><code>cryptokeys</code></a> attribute on the <a><code>Window</code></a> and <a><code>WorkerGlobalScope</code></a> objects. This attribute is an object supporting a method, <a><code>getkeysByName</code></a> which may be used to get an array of all keys matching a <code>DOMString</code> name specifier. Keys are returned as <a>NamedKey</a> objects which are subclasses of the <a><code>Key</code></a> class.</p></section>
- <section><h3>GetKeysByNameCallback interface</h3>
- <dl title="[Callback] interface GetKeysByNameCallback" class="idl">
- <dt>void complete( KeyArray keys )</dt><dd>Called when the key search is complete</dd>
+ <section><h3>NamedKey interface</h3>
+ <dl title="interface NamedKey : Key" class="idl">
+ <dt>readonly attribute DOMString name</dt>
+ <dd><p>A local identifier for the key.</p></dd>
+ <dt>readonly attribute DOMString? id</dt>
+ <dd>
+ <p>A global identifier associated with the key.</p>
+ <p>Origin-specific pre-provisioned keys are frequently provisioned with associated identifiers. Where an identifier exists that uniquely identifies the key amongst all keys pre-provisoned with the same <a>origin</a> and <a><code>name</code></a> and if this identifier can be canonically expressed as a sequence of no more than 256 bytes, then this identifier SHOULD be exposed, base64 encoded, as the <a><code>id</code></a>. If no identifier matching these conditions exists, <a><code>id</code></a> MUST be <code>null</code>.</p>
+ </dd>
</dl>
- </section>
-
- <section><h3>GetKeysByNameParams dictionary</h3>
- <dl title="dictionary GetKeysByNameParams" class="idl">
- <dt>DOMString name</dt><dd>The name specifier for the requested keys.</dd>
- <dt>GetKeysByNameCallback oncompletion;</dt><dd>Called on completion of the key search.</dd>
- </dl>
+ <section><h4>Structured clone algorithm</h4></section>
+ <p>When a user agent is required to obtain a <a>structured clone</a> of a <a>NamedKey</a> object, it must run the following steps.</p>
+ <ol>
+ <li>Let <var>input</var> and <var>memory</var> be the corresponding inputs defined by the <a title="structured clone algorithm">internal structured clone algorithm</a>, where <var>input</var> is a <a>NamedKey</a> object to be cloned.</li>
+ <li>Let <var>output</var> be a newly constructed <a>NamedKey</a> object, where the structured clone algorithm is followed for the base <code>Key</code> object.</li>
+ <li>Let the following attributes of <var>output</var> be equal to the value obtained by invoking the internal structured clone algorithm recursively, using the corresponding attribute on <var>input</var> as the new "<var>input</var>" argument and <var>memory</var> as the new "<var>memory</var>" argument:
+ <ul>
+ <li><code>name</code></li>
+ <li><code>id</code></li>
+ </ul></li>
+ </ol>
</section>
<section><h3>CryptoKeys interface</h3>
<dl title="[NoInterfaceObject] interface CryptoKeys" class="idl">
- <dt>void getKeysByName( GetKeysByNameParams params )</dt>
- <dd>Gets all keys matching the name specifier in the parameters. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.</dd>
+ <dt><a href-"http://www.w3.org/TR/WebCryptoAPI/#dfn-KeyOperation">KeyOperation</a> getKeysByName( DOMString name )</dt>
+ <dd>
+ <p>When invoked, this method must perform the following steps:
+ <ol>
+ <li>Let <var>KeyOp</var> be a newly created object implementing the <code><a href-"http://www.w3.org/TR/WebCryptoAPI/#KeyOperation-interface">KeyOperation</a></code> interface</li>
+ <li>Queue an operation to asynchronously run the following steps:</li>
+ <ol>
+ <li>Search for a key or keys matching the name specifier provided in <code>name</code>. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.</li>
+ <dl class-"switch">
+ <dt>If one or more keys are found</dt>
+ <dd>
+ <ol>
+ <li>Let the <code>result</code> attribute of <var>KeyOp</var> be an object of type <code>NamedKey[]</code> containing the keys</li>
+ <li><a title="queue-a-task">queue a task</a> to <a title="fire-a-simple-event">fire a simple event</a> called <code>onsuccess</code>at <var>KeyOp</var></li>
+ </ol>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd><a title="queue-a-task">queue a task</a> to <a title="fire-a-simple-event">fire a simple event</a> called <code>onerror</code> at <var>KeyOp</var></dd>
+ </dl>
+ </ol>
+ <li>Return <var>KeyOp</var> to the task that invoked <a>getKeysByName</a></li>
+ </ol>
+ </p>
+
+ <p>A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters. If no matching keys are found, and empty array is returned.</p></dd>
</dl>
</section>
- <section><h3>WindowCryptoKeys interface</h3>
- <p>The <a>WindowCryptoKeys</a> interface is exposed on the <code>Window</code> object.</p>
- <div class="idl" title="Window implements WindowCryptoKeys"></div>
- <dl title="[NoInterfaceObject] interface WindowCryptoKeys" class="idl">
+
+ <section><h3>Extension of Window interface</h3>
+ <dl title="partial interface Window" class="idl">
+ <dt>readonly attribute CryptoKeys cryptokeys</dt>
+ <dd>The object that exposes the key discovery methods</dd>
+ </dl></section>
+
+ <section><h3>Extension of WorkerGlobalScope interface</h3>
+ <dl title="partial interface WorkerGlobalScope" class="idl">
<dt>readonly attribute CryptoKeys cryptokeys</dt>
<dd>The object that exposes the key discovery methods</dd>
</dl></section>
--- a/keydiscovery.html Mon Dec 10 09:51:48 2012 -0800
+++ b/keydiscovery.html Mon Dec 10 15:42:09 2012 -0800
@@ -371,17 +371,17 @@
</p>
<h1 class="title" id="title">WebCrypto Key Discovery</h1>
- <h2 id="w3c-editor-s-draft-08-december-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 08 December 2012</h2>
+ <h2 id="w3c-editor-s-draft-10-december-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 10 December 2012</h2>
<dl>
<dt>This version:</dt>
- <dd><a href="http://www.w3.org/TR/2012/WD-WebCryptoKey-20121207/">http://www.w3.org/TR/2012/WD-WebCryptoKey-20121207/</a></dd>
+ <dd><a href="http://dvcs.w3.org/hg/webcrypto-keydiscovery/raw-file/tip/keydiscovery.html">http://dvcs.w3.org/hg/webcrypto-keydiscovery/raw-file/tip/keydiscovery.html</a></dd>
<dt>Latest published version:</dt>
<dd><a href="http://www.w3.org/TR/WebCryptoKey/">http://www.w3.org/TR/WebCryptoKey/</a></dd>
<dt>Latest editor's draft:</dt>
- <dd><a href="http://www.w3.org/TR/2012/WD-WebCryptoKey-20121207/">http://www.w3.org/TR/2012/WD-WebCryptoKey-20121207/</a></dd>
+ <dd><a href="http://dvcs.w3.org/hg/webcrypto-keydiscovery/raw-file/tip/keydiscovery.html">http://dvcs.w3.org/hg/webcrypto-keydiscovery/raw-file/tip/keydiscovery.html</a></dd>
@@ -475,7 +475,7 @@
-</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#use-cases" class="tocxref"><span class="secno">2. </span>Use cases</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">3. </span>Conformance</a></li><li class="tocline"><a href="#scope" class="tocxref"><span class="secno">4. </span>Scope</a></li><li class="tocline"><a href="#privacy-considerations" class="tocxref"><span class="secno">5. </span>Privacy considerations</a><ul class="toc"><li class="tocline"><a href="#named-origin-specific-pre-provisioned-keys" class="tocxref"><span class="secno">5.1 </span>Named origin-specific pre-provisioned keys</a><ul class="toc"><li class="tocline"><a href="#comparison-to-cookies-and-persistent-storage" class="tocxref"><span class="secno">5.1.1 </span>Comparison to cookies and persistent storage</a></li><li class="tocline"><a href="#user-tracking" class="tocxref"><span class="secno">5.1.2 </span>User tracking</a></li><li class="tocline"><a href="#cookie-resurrection" class="tocxref"><span class="secno">5.1.3 </span>Cookie resurrection</a></li><li class="tocline"><a href="#sensitivity-of-data" class="tocxref"><span class="secno">5.1.4 </span>Sensitivity of data</a></li></ul></li></ul></li><li class="tocline"><a href="#dependencies" class="tocxref"><span class="secno">6. </span>Dependencies</a></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">7. </span>Terminology</a></li><li class="tocline"><a href="#api-definition" class="tocxref"><span class="secno">8. </span>API definition</a><ul class="toc"><li class="tocline"><a href="#overview" class="tocxref"><span class="secno">8.1 </span>Overview</a></li><li class="tocline"><a href="#keyarray-interface" class="tocxref"><span class="secno">8.2 </span>KeyArray interface</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">8.2.1 </span>Attributes</a></li><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">8.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#getkeysbynamecallback-interface" class="tocxref"><span class="secno">8.3 </span>GetKeysByNameCallback interface</a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">8.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#getkeysbynameparams-dictionary" class="tocxref"><span class="secno">8.4 </span>GetKeysByNameParams dictionary</a><ul class="toc"><li class="tocline"><a href="#dictionary-getkeysbynameparams-members" class="tocxref"><span class="secno">8.4.1 </span>Dictionary <span class="formerLink"><code>GetKeysByNameParams</code></span> Members</a></li></ul></li><li class="tocline"><a href="#cryptokeys-interface" class="tocxref"><span class="secno">8.5 </span>CryptoKeys interface</a><ul class="toc"><li class="tocline"><a href="#methods-2" class="tocxref"><span class="secno">8.5.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#windowcryptokeys-interface" class="tocxref"><span class="secno">8.6 </span>WindowCryptoKeys interface</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">8.6.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">9. </span>Examples</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">A. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">A.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">A.2 </span>Informative references</a></li></ul></li></ul></section>
+</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#use-cases" class="tocxref"><span class="secno">2. </span>Use cases</a><ul class="toc"><li class="tocline"><a href="#out-of-band-key-provisioning" class="tocxref"><span class="secno">2.1 </span>Out of band key provisioning</a></li></ul></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">3. </span>Conformance</a></li><li class="tocline"><a href="#scope" class="tocxref"><span class="secno">4. </span>Scope</a></li><li class="tocline"><a href="#privacy-considerations" class="tocxref"><span class="secno">5. </span>Privacy considerations</a><ul class="toc"><li class="tocline"><a href="#named-origin-specific-pre-provisioned-keys" class="tocxref"><span class="secno">5.1 </span>Named origin-specific pre-provisioned keys</a><ul class="toc"><li class="tocline"><a href="#comparison-to-cookies-and-persistent-storage" class="tocxref"><span class="secno">5.1.1 </span>Comparison to cookies and persistent storage</a></li><li class="tocline"><a href="#user-tracking" class="tocxref"><span class="secno">5.1.2 </span>User tracking</a></li><li class="tocline"><a href="#cookie-resurrection" class="tocxref"><span class="secno">5.1.3 </span>Cookie resurrection</a></li><li class="tocline"><a href="#sensitivity-of-data" class="tocxref"><span class="secno">5.1.4 </span>Sensitivity of data</a></li></ul></li></ul></li><li class="tocline"><a href="#dependencies" class="tocxref"><span class="secno">6. </span>Dependencies</a></li><li class="tocline"><a href="#api-definition" class="tocxref"><span class="secno">7. </span>API definition</a><ul class="toc"><li class="tocline"><a href="#overview" class="tocxref"><span class="secno">7.1 </span>Overview</a></li><li class="tocline"><a href="#namedkey-interface" class="tocxref"><span class="secno">7.2 </span>NamedKey interface</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">7.2.1 </span>Attributes</a></li><li class="tocline"><a href="#structured-clone-algorithm" class="tocxref"><span class="secno">7.2.2 </span>Structured clone algorithm</a></li></ul></li><li class="tocline"><a href="#cryptokeys-interface" class="tocxref"><span class="secno">7.3 </span>CryptoKeys interface</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">7.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#extension-of-window-interface" class="tocxref"><span class="secno">7.4 </span>Extension of Window interface</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">7.4.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#extension-of-workerglobalscope-interface" class="tocxref"><span class="secno">7.5 </span>Extension of WorkerGlobalScope interface</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">7.5.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">8. </span>Examples</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">A. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">A.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">A.2 </span>Informative references</a></li></ul></li></ul></section>
<section class="informative" id="introduction">
<!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
@@ -501,6 +501,13 @@
<section id="use-cases">
<!--OddPage--><h2><span class="secno">2. </span>Use cases</h2>
+ <section id="out-of-band-key-provisioning">
+ <h3><span class="secno">2.1 </span>Out of band key provisioning</h3>
+ <p>Web applications may wish to use keys that have been provisioned through means outside the scope of the WebCrypto API. This may include keys that are provisioned through platform-specific native APIs, stored in secure elements such as trusted platform modules (TPMs), individually bound to devices at time of manufacturing or otherwise installed via device-specific provisioning protocols.</p>
+ <p>Such keys may, for example, be used to assist in identifying a device to a specific web service. User agents may choose to expose such keys to web applications after implementing appropriate security and privacy mitigations, including gaining user consent.</p>
+
+<p>In this scenario, a web application discovers a pre-provisioned key based on its name and uses it to perform authorized cryptographic operations as part of a protocol with a server. The server may utilize knowledge obtained out-of-band regarding the key's provisioning to make access control and policy decisions, such as inferring the identity of the device and customizing its responses based on that.</p>
+ </section>
<p></p>
</section>
@@ -607,62 +614,103 @@
</section>
</section>
</section>
- <section id="dependencies">
+
+ <section class="section" id="dependencies">
<!--OddPage--><h2><span class="secno">6. </span>Dependencies</h2>
- <p>This specification relies on underlying specifications.</p>
<p>
- </p><dl>
- <dt>Web Cryptography API</dt>
- <dd><p>A <a href="#dfn-conforming-user-agent" class="internalDFN">conforming user agent</a> <em class="rfc2119" title="must">must</em> support the Web Cryptography API [<cite><a class="bibref" href="#bib-WEBCRYPTO">WEBCRYPTO</a></cite>].</p></dd>
- </dl>
- <p></p>
+ This specification relies on several other underlying specifications.
+ </p>
+ <dl>
+ <dt>HTML5</dt>
+ <dd>The terms and algorithms
+ <dfn title="Window" id="dfn-window"><code>Window</code></dfn>,
+ <dfn title="Function" id="dfn-function"><code>Function</code></dfn>,
+ <dfn id="dfn-origin">origin</dfn>, <dfn id="dfn-same-origin">same origin</dfn>, <dfn id="dfn-structured-clone">structured clone</dfn>,
+ <dfn id="dfn-structured-clone-algorithm">structured clone algorithm</dfn>, <dfn id="dfn-task">task</dfn>, <dfn id="dfn-task-source">task source</dfn>,
+ <dfn title="queue-a-task" id="dfn-queue-a-task">queue a task</dfn>
+ and <dfn title="fire-a-simple-event" id="dfn-fire-a-simple-event">fire a simple event</dfn> are defined by the HTML 5
+ specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
+ </dd>
+ <dt>Web Cryptography API</dt>
+ <dd><p>A <a href="#dfn-conforming-user-agent" class="internalDFN">conforming user agent</a> <em class="rfc2119" title="must">must</em> support the Web Cryptography API [<cite><a class="bibref" href="#bib-WEBCRYPTO">WEBCRYPTO</a></cite>].</p>
+ <p>The terms <dfn title="Key" id="dfn-key"><code>Key</code></dfn> and <dfn title="KeyOperation" id="dfn-keyoperation"><code>KeyOperation</code></dfn> are defined in [<cite><a class="bibref" href="#bib-WEBCRYPTO">WEBCRYPTO</a></cite>].</p>
+ </dd>
+ <dt>WebIDL</dt>
+ <dd>Many of the interface definitions and all of the IDL in this spec depends on [<cite><a class="bibref" href="#bib-WEBIDL">WEBIDL</a></cite>].</dd>
+ <dt>WebWorkers</dt>
+ <dd>The term <dfn title="WorkerGlobalScope" id="dfn-workerglobalscope"><a class="externalDFN"><code>WorkerGlobalScope</code></a></dfn> is defined by
+ the WebWorkers specification [<cite><a class="bibref" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>].</dd>
+ </dl>
</section>
- <section id="terminology">
- <!--OddPage--><h2><span class="secno">7. </span>Terminology</h2>
- <p>The terms <dfn id="dfn-origin">origin</dfn> and <dfn id="dfn-same-origin">same origin</dfn> are defined by the HTML specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].</p>
-
- </section>
+
<section id="api-definition">
- <!--OddPage--><h2><span class="secno">8. </span>API definition</h2>
- <section class="informative" id="overview"><h3><span class="secno">8.1 </span>Overview</h3><p><em>This section is non-normative.</em></p>
- <p>This specification defines a new <a><code>cryptokeys</code></a> attribute on the <code>Window</code> object. This attribute is an object supporting a method, <a><code>getkeysByName</code></a> which may be used to get an array of all keys matching a <code>DOMString</code> name specifier. The array of keys is returned through a callback function, in the form of a <a href="#idl-def-KeyArray" class="idlType"><code>KeyArray</code></a> object.</p></section>
- <section id="keyarray-interface"><h3><span class="secno">8.2 </span>KeyArray interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-KeyArray">interface <span class="idlInterfaceID">KeyArray</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-KeyArray-length">length</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>Key</a>?</span> <span class="idlMethName"><a href="#widl-KeyArray-get-Key-unsigned-long-index">get</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">index</span></span>);</span>
-};</span></pre><section id="attributes"><h4><span class="secno">8.2.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-KeyArray-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The number of key objects in the array.</dd></dl></section><section id="methods"><h4><span class="secno">8.2.2 </span>Methods</h4><dl class="methods"><dt id="widl-KeyArray-get-Key-unsigned-long-index"><code>get</code></dt><dd>Get a Key object by index.<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">index</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>Key</a></code>, nullable</div></dd></dl></section>
+ <!--OddPage--><h2><span class="secno">7. </span>API definition</h2>
+ <section class="informative" id="overview"><h3><span class="secno">7.1 </span>Overview</h3><p><em>This section is non-normative.</em></p>
+ <p>This specification defines a new <a><code>cryptokeys</code></a> attribute on the <a href="#dfn-window" class="internalDFN"><code>Window</code></a> and <a href="#dfn-workerglobalscope" class="internalDFN"><code>WorkerGlobalScope</code></a> objects. This attribute is an object supporting a method, <a><code>getkeysByName</code></a> which may be used to get an array of all keys matching a <code>DOMString</code> name specifier. Keys are returned as <a href="#idl-def-NamedKey" class="idlType"><code>NamedKey</code></a> objects which are subclasses of the <a href="#dfn-key" class="internalDFN"><code>Key</code></a> class.</p></section>
+
+ <section id="namedkey-interface"><h3><span class="secno">7.2 </span>NamedKey interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-NamedKey">interface <span class="idlInterfaceID">NamedKey</span> : <span class="idlSuperclass"><a>Key</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-NamedKey-name">name</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a>?</span> <span class="idlAttrName"><a href="#widl-NamedKey-id">id</a></span>;</span>
+};</span></pre><section id="attributes"><h4><span class="secno">7.2.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-NamedKey-id"><code>id</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly, nullable</dt><dd>
+ <p>A global identifier associated with the key.</p>
+ <p>Origin-specific pre-provisioned keys are frequently provisioned with associated identifiers. Where an identifier exists that uniquely identifies the key amongst all keys pre-provisoned with the same <a href="#dfn-origin" class="internalDFN">origin</a> and <a><code>name</code></a> and if this identifier can be canonically expressed as a sequence of no more than 256 bytes, then this identifier <em class="rfc2119" title="should">should</em> be exposed, base64 encoded, as the <a><code>id</code></a>. If no identifier matching these conditions exists, <a><code>id</code></a> <em class="rfc2119" title="must">must</em> be <code>null</code>.</p>
+ </dd><dt id="widl-NamedKey-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd><p>A local identifier for the key.</p></dd></dl></section>
+ <section id="structured-clone-algorithm"><h4><span class="secno">7.2.2 </span>Structured clone algorithm</h4></section>
+ <p>When a user agent is required to obtain a <a href="#dfn-structured-clone" class="internalDFN">structured clone</a> of a <a href="#idl-def-NamedKey" class="idlType"><code>NamedKey</code></a> object, it must run the following steps.</p>
+ <ol>
+ <li>Let <var>input</var> and <var>memory</var> be the corresponding inputs defined by the <a title="structured clone algorithm" href="#dfn-structured-clone-algorithm" class="internalDFN">internal structured clone algorithm</a>, where <var>input</var> is a <a href="#idl-def-NamedKey" class="idlType"><code>NamedKey</code></a> object to be cloned.</li>
+ <li>Let <var>output</var> be a newly constructed <a href="#idl-def-NamedKey" class="idlType"><code>NamedKey</code></a> object, where the structured clone algorithm is followed for the base <code>Key</code> object.</li>
+ <li>Let the following attributes of <var>output</var> be equal to the value obtained by invoking the internal structured clone algorithm recursively, using the corresponding attribute on <var>input</var> as the new "<var>input</var>" argument and <var>memory</var> as the new "<var>memory</var>" argument:
+ <ul>
+ <li><code>name</code></li>
+ <li><code>id</code></li>
+ </ul></li>
+ </ol>
</section>
- <section id="getkeysbynamecallback-interface"><h3><span class="secno">8.3 </span>GetKeysByNameCallback interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-GetKeysByNameCallback">[<span class="extAttr">Callback</span>]
-interface <span class="idlInterfaceID">GetKeysByNameCallback</span> {
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-GetKeysByNameCallback-complete-void-KeyArray-keys">complete</a></span> (<span class="idlParam"><span class="idlParamType"><a href="#idl-def-KeyArray" class="idlType"><code>KeyArray</code></a></span> <span class="idlParamName">keys</span></span>);</span>
-};</span></pre><section id="methods-1"><h4><span class="secno">8.3.1 </span>Methods</h4><dl class="methods"><dt id="widl-GetKeysByNameCallback-complete-void-KeyArray-keys"><code>complete</code></dt><dd>Called when the key search is complete<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">keys</td><td class="prmType"><code><a href="#idl-def-KeyArray" class="idlType"><code>KeyArray</code></a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
- </section>
-
- <section id="getkeysbynameparams-dictionary"><h3><span class="secno">8.4 </span>GetKeysByNameParams dictionary</h3>
- <pre class="idl"><span class="idlDictionary" id="idl-def-GetKeysByNameParams">dictionary <span class="idlDictionaryID">GetKeysByNameParams</span> {
-<span class="idlMember"> <span class="idlMemberType"><a>DOMString</a></span> <span class="idlMemberName"><a href="#widl-GetKeysByNameParams-name">name</a></span>;</span>
-<span class="idlMember"> <span class="idlMemberType"><a href="#idl-def-GetKeysByNameCallback" class="idlType"><code>GetKeysByNameCallback</code></a></span> <span class="idlMemberName"><a href="#widl-GetKeysByNameParams-oncompletion">oncompletion;</a></span>;</span>
-};</span></pre><section id="dictionary-getkeysbynameparams-members"><h4><span class="secno">8.4.1 </span>Dictionary <a class="idlType" href="#idl-def-GetKeysByNameParams"><code>GetKeysByNameParams</code></a> Members</h4><dl class="dictionary-members"><dt id="widl-GetKeysByNameParams-name"><code>name</code> of type <span class="idlMemberType"><a>DOMString</a></span></dt><dd>The name specifier for the requested keys.</dd><dt id="widl-GetKeysByNameParams-oncompletion"><code>oncompletion;</code> of type <span class="idlMemberType"><a href="#idl-def-GetKeysByNameCallback" class="idlType"><code>GetKeysByNameCallback</code></a></span></dt><dd>Called on completion of the key search.</dd></dl></section>
+ <section id="cryptokeys-interface"><h3><span class="secno">7.3 </span>CryptoKeys interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-CryptoKeys">[<span class="extAttr">NoInterfaceObject</span>]
+interface <span class="idlInterfaceID">CryptoKeys</span> {
+<span class="idlMethod"> <span class="idlMethType"><a>KeyOperation</a></span> <span class="idlMethName"><a href="#widl-CryptoKeys-getKeysByName-KeyOperation-DOMString-name">getKeysByName</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>);</span>
+};</span></pre><section id="methods"><h4><span class="secno">7.3.1 </span>Methods</h4><dl class="methods"><dt id="widl-CryptoKeys-getKeysByName-KeyOperation-DOMString-name"><code>getKeysByName</code></dt><dd>
+ <p>When invoked, this method must perform the following steps:
+ </p><ol>
+ <li>Let <var>KeyOp</var> be a newly created object implementing the <code><a href-"http:="" www.w3.org="" tr="" webcryptoapi="" #keyoperation-interface"="" href="#dfn-keyoperation" class="internalDFN">KeyOperation</a></code> interface</li>
+ <li>Queue an operation to asynchronously run the following steps:</li>
+ <ol>
+ <li>Search for a key or keys matching the name specifier provided in <code>name</code>. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.</li>
+ <dl class-"switch"="">
+ <dt>If one or more keys are found</dt>
+ <dd>
+ <ol>
+ <li>Let the <code>result</code> attribute of <var>KeyOp</var> be an object of type <code>NamedKey[]</code> containing the keys</li>
+ <li><a title="queue-a-task" href="#dfn-queue-a-task" class="internalDFN">queue a task</a> to <a title="fire-a-simple-event" href="#dfn-fire-a-simple-event" class="internalDFN">fire a simple event</a> called <code>onsuccess</code>at <var>KeyOp</var></li>
+ </ol>
+ </dd>
+ <dt>Otherwise</dt>
+ <dd><a title="queue-a-task" href="#dfn-queue-a-task" class="internalDFN">queue a task</a> to <a title="fire-a-simple-event" href="#dfn-fire-a-simple-event" class="internalDFN">fire a simple event</a> called <code>onerror</code> at <var>KeyOp</var></dd>
+ </dl>
+ </ol>
+ <li>Return <var>KeyOp</var> to the task that invoked <a>getKeysByName</a></li>
+ </ol>
+ <p></p>
+
+ <p>A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters. If no matching keys are found, and empty array is returned.</p><table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>KeyOperation</a></code></div></dd></dl></section>
</section>
- <section id="cryptokeys-interface"><h3><span class="secno">8.5 </span>CryptoKeys interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-CryptoKeys">[<span class="extAttr">NoInterfaceObject</span>]
-interface <span class="idlInterfaceID">CryptoKeys</span> {
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-CryptoKeys-getKeysByName-void-GetKeysByNameParams-params">getKeysByName</a></span> (<span class="idlParam"><span class="idlParamType"><a href="#idl-def-GetKeysByNameParams" class="idlType"><code>GetKeysByNameParams</code></a></span> <span class="idlParamName">params</span></span>);</span>
-};</span></pre><section id="methods-2"><h4><span class="secno">8.5.1 </span>Methods</h4><dl class="methods"><dt id="widl-CryptoKeys-getKeysByName-void-GetKeysByNameParams-params"><code>getKeysByName</code></dt><dd>Gets all keys matching the name specifier in the parameters. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">params</td><td class="prmType"><code><a href="#idl-def-GetKeysByNameParams" class="idlType"><code>GetKeysByNameParams</code></a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
- </section>
- <section id="windowcryptokeys-interface"><h3><span class="secno">8.6 </span>WindowCryptoKeys interface</h3>
- <p>The <a href="#idl-def-WindowCryptoKeys" class="idlType"><code>WindowCryptoKeys</code></a> interface is exposed on the <code>Window</code> object.</p>
- <pre class="idl"><span class="idlImplements"><a>Window</a> implements <a href="#idl-def-WindowCryptoKeys" class="idlType"><code>WindowCryptoKeys</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Window</a></code> type are defined to also implement the <a href="#idl-def-WindowCryptoKeys" class="idlType"><code>WindowCryptoKeys</code></a> interface.</p></div>
- <pre class="idl"><span class="idlInterface" id="idl-def-WindowCryptoKeys">[<span class="extAttr">NoInterfaceObject</span>]
-interface <span class="idlInterfaceID">WindowCryptoKeys</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span> <span class="idlAttrName"><a href="#widl-WindowCryptoKeys-cryptokeys">cryptokeys</a></span>;</span>
-};</span></pre><section id="attributes-1"><h4><span class="secno">8.6.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-WindowCryptoKeys-cryptokeys"><code>cryptokeys</code> of type <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span>, readonly</dt><dd>The object that exposes the key discovery methods</dd></dl></section></section>
+ <section id="extension-of-window-interface"><h3><span class="secno">7.4 </span>Extension of Window interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-Window">partial interface <span class="idlInterfaceID">Window</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span> <span class="idlAttrName"><a href="#widl-Window-cryptokeys">cryptokeys</a></span>;</span>
+};</span></pre><section id="attributes-1"><h4><span class="secno">7.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Window-cryptokeys"><code>cryptokeys</code> of type <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span>, readonly</dt><dd>The object that exposes the key discovery methods</dd></dl></section></section>
+
+ <section id="extension-of-workerglobalscope-interface"><h3><span class="secno">7.5 </span>Extension of WorkerGlobalScope interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-WorkerGlobalScope">partial interface <span class="idlInterfaceID">WorkerGlobalScope</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span> <span class="idlAttrName"><a href="#widl-WorkerGlobalScope-cryptokeys">cryptokeys</a></span>;</span>
+};</span></pre><section id="attributes-2"><h4><span class="secno">7.5.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-WorkerGlobalScope-cryptokeys"><code>cryptokeys</code> of type <span class="idlAttrType"><a href="#idl-def-CryptoKeys" class="idlType"><code>CryptoKeys</code></a></span>, readonly</dt><dd>The object that exposes the key discovery methods</dd></dl></section></section>
</section>
- <section id="examples"><!--OddPage--><h2><span class="secno">9. </span>Examples</h2></section>
+ <section id="examples"><!--OddPage--><h2><span class="secno">8. </span>Examples</h2></section>
<!--
<section class='appendix'>
<h2>Acknowledgements</h2>
@@ -677,6 +725,7 @@
</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
</dd><dt id="bib-WEBCRYPTO">[WEBCRYPTO]</dt><dd>Ryan Sleevi, David Dahl. <a href="http://www.w3.org/TR/2012/WD-WebCryptoAPI-20120913/"><cite>Web Cryptography API.</cite></a> 13 September 2012. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2012/WD-WebCryptoAPI-20120913/">http://www.w3.org/TR/2012/WD-WebCryptoAPI-20120913/</a>
</dd><dt id="bib-WEBIDL">[WEBIDL]</dt><dd>Cameron McCormack. <a href="http://www.w3.org/TR/2011/WD-WebIDL-20110927/"><cite>Web IDL.</cite></a> 27 September 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-WebIDL-20110927/">http://www.w3.org/TR/2011/WD-WebIDL-20110927/</a>
+</dd><dt id="bib-WEBWORKERS">[WEBWORKERS]</dt><dd>Ian Hickson. <a href="http://www.w3.org/TR/2011/WD-workers-20110901/"><cite>Web Workers.</cite></a> 1 September 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-workers-20110901/">http://www.w3.org/TR/2011/WD-workers-20110901/</a>
</dd></dl></section><section id="informative-references"><h3><span class="secno">A.2 </span>Informative references</h3><dl class="bibliography"><dt id="bib-COOKIES">[COOKIES]</dt><dd>Adam Barth. <cite><a href="http://www.rfc-editor.org/rfc/rfc6265.txt">HTTP State Management Mechanism</a>.</cite> April 2011. Internet Proposed Standard RFC 6265. URL: <a href="http://www.rfc-editor.org/rfc/rfc6265.txt">http://www.rfc-editor.org/rfc/rfc6265.txt</a>
</dd><dt id="bib-INDEXEDDB">[INDEXEDDB]</dt><dd>Nikunj Mehta, Jonas Sicking, Eliot Graff, Andrei Popescu, Jeremy Orlow. <a href="http://www.w3.org/TR/IndexedDB/">Indexed Database API</a>. April 2011. Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a>
</dd></dl></section></section></body></html>
\ No newline at end of file