--- a/Overview-UseCases.xml Wed Dec 05 18:12:55 2012 -0500
+++ b/Overview-UseCases.xml Thu Dec 06 12:23:48 2012 -0500
@@ -16,7 +16,7 @@
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
<title>Web Cryptography API Use Cases</title>
- <meta name='revision' content='$Id: Overview-FA.xml,v 1.164 2012/12/05 14:43:12 arangana Exp $'/>
+ <meta name='revision' content='$Id: Overview-FA.xml,v 1.164 2012/12/06 12:23:12 arangana Exp $'/>
<link rel='stylesheet' href='FileAPI.css' type='text/css'/>
<script src='section-links.js' type='application/ecmascript'/>
@@ -103,13 +103,13 @@
<div id='sections'>
<div id='introduction' class='section'>
<h2>Introduction</h2>
- <p>The Web Cryptography API describes a JavaScript API for basic cryptographic operations, including: hashing, signature generation and verification, encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. This document presents use cases in the form of scenarios, with each scenario describing a potential web application using the API.</p>
+ <p>The Web Cryptography API describes a JavaScript API for basic cryptographic operations, including: digesting, signature generation and verification, encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. This document presents use cases in the form of scenarios, with each scenario describing a potential web application using the API.</p>
</div>
<div id='requirements' class='section'>
<h2>Requirements</h2>
<p>This section presents required features of the Web Cryptography API; in many cases, the Web Cryptography API encompasses more than one algorithm and more than one mechanism to accomplish each of these features. The section presents code names for each of the features.</p>
<ul>
- <li><p><dfn id="hash">HASH</dfn>, the ability to perform a cryptographic hash, where an algorithm that takes an arbitrary block of data returns a fixed-size bit sequence, called the <dfn id="hash-value">hash value</dfn>, such that any change to the block of data changes the hash value.</p></li>
+ <li><p><dfn id="digest">DIGEST</dfn>, the ability to perform a cryptographic hash, where an algorithm that takes an arbitrary block of data returns a fixed-size bit sequence, called the <dfn id="hash-value">hash value</dfn>, such that any change to the block of data changes the hash value.</p></li>
<li><p><dfn id="mac">MAC</dfn>, the ability to generate a <em>message authentication code</em>, using an algorithm</p></li>
<li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document, such that upon verification of the signature, the document's authenticity can be determined. The term document in this context can refer to any kind of data used in web applications.</p></li>
<li><p><dfn id="verify">VERIFY</dfn>, the ability to verify a digitally signed document, as well as verify a MAC.</p></li>
@@ -219,28 +219,56 @@
</x:codeblock>
<p>John Doe's use of the social network is thus compromised by Jane Doe's script injection, since the next time he logs in, and <code>init()</code> is called, <code>evil_code</code> is run, which may make requests to Jane's server with query strings that reveal who John chats with, and even the contents of these messages. To mitigate against situations like this, the social networking site might do something like this:</p>
<x:codeblock language="es">
- <span class="comment">// Synchronously retrieve an MD5 hash of the pristine version of the code</span>
+ <span class="comment">// Synchronously retrieve a SHA-256 digest of the pristine version of the code</span>
<span class="comment">// This is retrieved from the server</span>
var src_hash = getHashFromServer();
function init()
{
var src = window.localStorage.getItem('src');
- <span class="comment">// validateSrc is an utility function that wraps the Crypto API</span>
+ <span class="comment">/* Create a Digester and compare
- validateSrc(src, src_hash, success, failFetch);
+ 1. Assume utility function createArrayBufferView that creates an ArrayBufferView of the src
+ (and note that the comparison does depend on this being consistent on client and server).
- function success(){eval(src)};
- function failFetch(){<span class="comment">//Fetch the code using XHR, and populate localStorage with it</span>};
+ 2. Compare the two values after hashing is successfully completed.
+
+ In practice including an onprogress handler and onerror handler is recommended - the code here
+ is terse for readability.
+
+ */</span>
+
+ bufferData = createArrayBufferView(src);
+ var digest = window.crypto.createDigester("SHA-256");
+ digest.init();
+ digest.processData(bufferData);
+ digest.complete();
+
+ digest.oncomplete = function(e){
+
+ if(e.target.result === src_hash)
+ {
+ eval(src);
+ }
+ else
+ {
+ <span class="comment">// Fetch the code using XHR and repopulate localStorage</span>
+ }
+
+
+ }
+
+
}
</x:codeblock>
- <p>In this case, <code>getHashFromServer()</code> is guaranteed to be untampered with, since it connects to the server or the HTTP cache, which are above suspicion.
+ <p>In this case, <code>getHashFromServer()</code> is guaranteed to be untampered with, since it connects to the server or the HTTP cache, which are above suspicion in this threat model.
</p>
+ <div class="note"><p>The conversion to an ArrayBufferView must be consistent with the conversion to bits on the server side, so that the SHA-256 digests can be compared acurately.</p></div>
</div>
- [<a href="#hash">HASH</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
+ [<a href="#digest">DIGEST</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
</div>
<div id='encrypt' class='section'>
<h3>Mitch Turns 21: Encrypted Communications</h3>
--- a/Overview.html Wed Dec 05 18:12:55 2012 -0500
+++ b/Overview.html Thu Dec 06 12:23:48 2012 -0500
@@ -12,7 +12,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Web Cryptography API Use Cases</title>
- <meta name="revision" content="$Id: Overview-FA.xml,v 1.164 2012/12/05 14:43:12 arangana Exp $" />
+ <meta name="revision" content="$Id: Overview-FA.xml,v 1.164 2012/12/06 12:23:12 arangana Exp $" />
<link rel="stylesheet" href="FileAPI.css" type="text/css" />
<script src="section-links.js" type="application/ecmascript"></script>
@@ -30,7 +30,7 @@
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED" type="text/css" /></head>
<body>
- <div class="head"><div><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" width="72" height="48" alt="W3C" /></a></div><h1>Web Cryptography API Use Cases</h1><h2>W3C Editor’s Draft <em>5 December 2012</em></h2><dl><dt>Latest Editor’s Draft:</dt><dd><a href=" http://dvcs.w3.org/hg/webcrypto-usecases"> http://dvcs.w3.org/hg/webcrypto-usecases</a></dd><dt>Latest Published Version:</dt><dt>Editor:</dt><dd><a href="http://arunranga.com/">Arun Ranganathan</a>, Mozilla Corporation <arun@mozilla.com></dd><dt>Participate:</dt><dd></dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr />
+ <div class="head"><div><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" width="72" height="48" alt="W3C" /></a></div><h1>Web Cryptography API Use Cases</h1><h2>W3C Editor’s Draft <em>6 December 2012</em></h2><dl><dt>Latest Editor’s Draft:</dt><dd><a href=" http://dvcs.w3.org/hg/webcrypto-usecases"> http://dvcs.w3.org/hg/webcrypto-usecases</a></dd><dt>Latest Published Version:</dt><dt>Editor:</dt><dd><a href="http://arunranga.com/">Arun Ranganathan</a>, Mozilla Corporation <arun@mozilla.com></dd><dt>Participate:</dt><dd></dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr />
<div class="section">
<h2>Abstract</h2>
@@ -39,7 +39,7 @@
</p>
- <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>This is revision $Id: Overview-FA.xml,v 1.164 2012/12/05 14:43:12 arangana Exp $.</p><p>There are 1 further editorial notes in the document.</p></div>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>This is revision $Id: Overview-FA.xml,v 1.164 2012/12/06 12:23:12 arangana Exp $.</p><p>There are 1 further editorial notes in the document.</p></div>
</div>
<div class="section">
@@ -51,7 +51,7 @@
report can be found in the <a href="http://www.w3.org/TR/">W3C technical
reports index</a> at http://www.w3.org/TR/.
</em></p><p>
- This document is the 5 December 2012 <b>Editor’s Draft</b> of the
+ This document is the 6 December 2012 <b>Editor’s Draft</b> of the
<cite>Web Cryptography API Use Cases</cite> specification.
Please send comments about this document to
@@ -119,13 +119,13 @@
<div id="sections">
<div id="introduction" class="section">
<h2>1. Introduction</h2>
- <p>The Web Cryptography API describes a JavaScript API for basic cryptographic operations, including: hashing, signature generation and verification, encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. This document presents use cases in the form of scenarios, with each scenario describing a potential web application using the API.</p>
+ <p>The Web Cryptography API describes a JavaScript API for basic cryptographic operations, including: digesting, signature generation and verification, encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. This document presents use cases in the form of scenarios, with each scenario describing a potential web application using the API.</p>
</div>
<div id="requirements" class="section">
<h2>2. Requirements</h2>
<p>This section presents required features of the Web Cryptography API; in many cases, the Web Cryptography API encompasses more than one algorithm and more than one mechanism to accomplish each of these features. The section presents code names for each of the features.</p>
<ul>
- <li><p><dfn id="hash">HASH</dfn>, the ability to perform a cryptographic hash, where an algorithm that takes an arbitrary block of data returns a fixed-size bit sequence, called the <dfn id="hash-value">hash value</dfn>, such that any change to the block of data changes the hash value.</p></li>
+ <li><p><dfn id="digest">DIGEST</dfn>, the ability to perform a cryptographic hash, where an algorithm that takes an arbitrary block of data returns a fixed-size bit sequence, called the <dfn id="hash-value">hash value</dfn>, such that any change to the block of data changes the hash value.</p></li>
<li><p><dfn id="mac">MAC</dfn>, the ability to generate a <em>message authentication code</em>, using an algorithm</p></li>
<li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document, such that upon verification of the signature, the document's authenticity can be determined. The term document in this context can refer to any kind of data used in web applications.</p></li>
<li><p><dfn id="verify">VERIFY</dfn>, the ability to verify a digitally signed document, as well as verify a MAC.</p></li>
@@ -235,28 +235,56 @@
</code></pre></div></div>
<p>John Doe's use of the social network is thus compromised by Jane Doe's script injection, since the next time he logs in, and <code>init()</code> is called, <code>evil_code</code> is run, which may make requests to Jane's server with query strings that reveal who John chats with, and even the contents of these messages. To mitigate against situations like this, the social networking site might do something like this:</p>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
- <span class="comment">// Synchronously retrieve an MD5 hash of the pristine version of the code</span>
+ <span class="comment">// Synchronously retrieve a SHA-256 digest of the pristine version of the code</span>
<span class="comment">// This is retrieved from the server</span>
var src_hash = getHashFromServer();
function init()
{
var src = window.localStorage.getItem('src');
- <span class="comment">// validateSrc is an utility function that wraps the Crypto API</span>
+ <span class="comment">/* Create a Digester and compare
- validateSrc(src, src_hash, success, failFetch);
+ 1. Assume utility function createArrayBufferView that creates an ArrayBufferView of the src
+ (and note that the comparison does depend on this being consistent on client and server).
- function success(){eval(src)};
- function failFetch(){<span class="comment">//Fetch the code using XHR, and populate localStorage with it</span>};
+ 2. Compare the two values after hashing is successfully completed.
+
+ In practice including an onprogress handler and onerror handler is recommended - the code here
+ is terse for readability.
+
+ */</span>
+
+ bufferData = createArrayBufferView(src);
+ var digest = window.crypto.createDigester("SHA-256");
+ digest.init();
+ digest.processData(bufferData);
+ digest.complete();
+
+ digest.oncomplete = function(e){
+
+ if(e.target.result === src_hash)
+ {
+ eval(src);
+ }
+ else
+ {
+ <span class="comment">// Fetch the code using XHR and repopulate localStorage</span>
+ }
+
+
+ }
+
+
}
</code></pre></div></div>
- <p>In this case, <code>getHashFromServer()</code> is guaranteed to be untampered with, since it connects to the server or the HTTP cache, which are above suspicion.
+ <p>In this case, <code>getHashFromServer()</code> is guaranteed to be untampered with, since it connects to the server or the HTTP cache, which are above suspicion in this threat model.
</p>
+ <div class="note"><div class="noteHeader">Note</div><p>The conversion to an ArrayBufferView must be consistent with the conversion to bits on the server side, so that the SHA-256 digests can be compared acurately.</p></div>
</div>
- [<a href="#hash">HASH</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
+ [<a href="#digest">DIGEST</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
</div>
<div id="encrypt" class="section">
<h3>3.4. Mitch Turns 21: Encrypted Communications</h3>