--- a/Overview-UseCases.xml Mon Dec 10 09:57:19 2012 -0500
+++ b/Overview-UseCases.xml Mon Dec 17 13:32:37 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/06 12:23:12 arangana Exp $'/>
+ <meta name='revision' content='$Id: Overview-FA.xml,v 1.164 2012/12/17 12:23:12 arangana Exp $'/>
<link rel='stylesheet' href='FileAPI.css' type='text/css'/>
<script src='section-links.js' type='application/ecmascript'/>
@@ -50,7 +50,7 @@
<div class='section'>
<h2>Abstract</h2>
<p>
- This document collates the target use cases for the Web Cryptography API. These use cases, described as <em>scenarios</em>, represent the set of expected functionality that may be achieved by the Web Cryptography API.
+ This document is NOT a recommendation track document, and should be read as an informative overview of the target use cases for a cryptographic API for the web. These use cases, described as <em>scenarios</em>, represent some of the set of expected functionality that may be achieved by the <a href="#WebCrypto">Web Cryptography API</a>, which provides an API for cryptographic operations such as encryption and decryption, and the <a href="#KeyDiscovery">Key Discovery API</a>, which specifically covers the ability to access cryptographic keys that have been <a href="#pre-prov"><em>pre-provisioned</em></a>. As both APIs are under construction, the reader should consult each specification for changes, and should treat sample code provided here as illustrative only. Presented here are <em>primary</em> use cases, showing what the working group hopes to achieve first. Other use cases are marked as <em>secondary</em>.
</p>
@@ -61,7 +61,7 @@
<h2>Status of this Document</h2>
<?sotd-top public-webcrypto@w3.org http://lists.w3.org/Archives/Public/public-webcrypto/?>
<p>
- Ongoing discussion of this document will be on the <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
+ This document is not a recommendation track document, and is presented for information purposes only. Ongoing discussion of this document will be on the <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
mailing list.
</p>
@@ -90,7 +90,7 @@
This document is produced by the <a href='http://www.w3.org/2012/webcrypto/'>Web Cryptography Working Group</a>, within
the W3C <a href='http://www.w3.org/Interaction/'>Interaction Domain</a>.
Changes made to this document can be found in the
- <a href='http://dev.w3.org/cvsweb/2006/webapi/FileAPI/Overview-UseCases.xml'>W3C public CVS server</a>.
+ <a href='https://dvcs.w3.org/hg/webcrypto-usecases'>W3C public Mercurial Repository</a>.
</p>
<?sotd-bottom http://www.w3.org/2004/01/pp-impl/42538/status?>
</div>
@@ -103,48 +103,83 @@
<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: 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>
+ <p>The <a href="#WebCrypto">Web Cryptography API</a> describes a JavaScript API for user agents such as web browsers, and exposes basic cryptographic operations, including: digesting, signature generation and verification, encryption, decryption, cryptographic key generation, key derivation, key import and key export. The <a href="#KeyDiscovery">Key Discovery API</a> describes a JavaScript API to invoke <a href="#pre-prov">pre-provisioned keys</a>. This document presents use cases in the form of scenarios that cover the use of both APIs, with each scenario describing a potential web application using these APIs. Where possible, code snippets have been provided to demonstrate what a developer might do when addressing the use case.</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>
+ <p>This section presents required features of a cryptographic API. It is possible that there is 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, which will be used alongside each scenario, illustrating which feature is used.</p>
<ul>
<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, with <dfn id="hmac">HMAC</dfn> being a specific kind of message authentication code, with a specific algorithm.</p></li>
- <li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document with private key, such that upon verification of the signature with the corresponding public key, the document's authenticity from the point of view of the signature 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>
- <li><p><dfn id="encrypt">ENCRYPT</dfn>, the ability to encode a document using an encryption algorithm. <dfn id="encrypt-pki">ENCRYPT-PKI</dfn> is a specific type of encryption involving PKI, and <dfn id="encrypt-sym">ENCRYPT-SYM</dfn> is a specific type of encryption using symmetric keys.</p></li>
- <li><p><dfn id="decrypt">DECRYPT</dfn>, the ability to decrypt a digitally signed document. <dfn id="decrypt-pki">DECRYPT-PKI</dfn> is a specific type of decryption using PKI, and <dfn id="decrypt-sym">DECRYPT-SYM</dfn> is a specific type of decryption using symmetric keys.</p></li>
- <li><p><dfn id="derive">DERIVE</dfn>, the ability to derive a key or keys used in cryptographic operations; <dfn id="derive-pki">DERIVE-PKI</dfn> is the ability to derive keys usable in PKI operations.</p></li>
- <li><p><dfn id="keyexchange">KEYEX</dfn>, the ability for two entities to exchange key(s) without interception by a third party, with <dfn id="keyex-dh">KEYEX-DH</dfn> representing Diffie-Hellman key exchange, a particularly common application of safe key exchange.</p></li>
- <li><p><dfn id="keycall">KEYCALL</dfn>, the ability to call a particular key from a web application that either generated the key or that is in the same domain as the key.</p></li>
- <li><p><dfn id="PKI">-PKI</dfn>, an acronym for <dfn id="pki">Public Key Infrastructure</dfn> used in this document as a suffix to other features.</p></li>
- <li><p><dfn id="SYM">-SYM</dfn>, an acronym for <dfn id="sym">Symmetric Key</dfn> operations, used in this document as a suffix to other features.</p></li>
- <li><p><dfn id="random">RANDOM</dfn>, the ability to generate a random cryptographically secure number.</p></li>
+ <li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document with a private key, such that upon verification of the signature with the corresponding public key, the document's authenticity from the point of view of the signature can be determined. The term document in this context can refer to any kind of data used with 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 or HMAC.</p></li>
+ <li><p><dfn id="encrypt">ENCRYPT</dfn>, the ability to encode a document using an encryption algorithm. <dfn id="encrypt-sym">ENCRYPT-SYM</dfn> is a specific type of encryption using symmetric cryptographic keys, and <dfn id="encrypt-assym">ENCRYPT-ASSYM</dfn> is a specific type of encryption using assymetric cryptographic keys, typically a public and private key pair.</p></li>
+ <li><p><dfn id="decrypt">DECRYPT</dfn>, the ability to decrypt a digitally signed document. <dfn id="decrypt-sym">DECRYPT-SYM</dfn> is a specific type of decryption using symmetric keys, and <dfn id="decrypt-assym">DECRYPT-ASSYM</dfn> is a specific type of decryption using assymetric keys, typically a public and private key pair.</p></li>
+ <li><p><dfn id="derive">DERIVE</dfn>, the ability to derive a key or key pair used in cryptographic operations; <dfn id="derive-assym">DERIVE-ASSYM</dfn> is the ability to derive assymetric keys, typically a public and private key pair, for use with assymetric cryptographic operations, and <dfn id="derive-sym">DERIVE-SYM</dfn> is the ability to derive a symmetric key for use with symmetric cryptographic operations.</p></li>
+ <li><p><dfn id="import">IMPORT</dfn>, the ability to import a key or key pair that have already been created elsewhere, for use within the web application that is invoking the import function, for use within the importing web application's origin. This necessiates an interoperable key format, which may be represented as octets.</p></li>
+ <li><p><dfn id="export">EXPORT</dfn>, the ability to export a key or key pair that can be accessed from within the application that is invoking the export function. This necessiates an interoperable key format, which may be represented as octets, that other web applications can then import.</p></li>
+ <li><p><dfn id="keyexchange">KEYEX</dfn>, the ability for two entities to exchange key(s) without interception by a third party, with <dfn id="keyex-dh">KEYEX-DH</dfn> representing Diffie-Hellman key exchange, a common application of safe key exchange.</p></li>
+ <li><p><dfn id="keycall">KEYCALL</dfn>, the ability to access a particular key (or key pair) from within a web application's key storage, which is within the web application's origin only. Here, the key storage might be IndexedDB or localStorage, and the key or key pair might have been created by the web application or imported by the web application.</p></li>
+ <li><p><dfn id="sym">-SYM</dfn>, an abbreviation for <dfn id="sym">symmetric key cryptographic operations</dfn>, used in this document as a suffix to other features to specifically clarify the feature being invoked by the web application.</p></li>
+ <li><p><dfn id="assym">ASSYM</dfn>, an abbreviation for <dfn id="assym">assymetric key cryptographic operations</dfn>, typically involving a public and private key pair, used in this document as a suffix to other features to specifically clarify the feature being invoked by the web application.</p></li>
+ <li><p><dfn id="random">RANDOM</dfn>, the ability to generate cryptographically secure random numbers.</p></li>
+ </ul>
+ <p>Additionally, the Web Cryptography WG is actively discussing three other features:</p>
+ <ul>
+ <li><p><dfn id="WRAP">WRAP</dfn> which allows a web application to use a key to <em>wrap another key</em>, so that the wrapped key can be unwrapped by a party with the corresponding wrapping key, but is hard to obtain or unwrap by anyone without the corresponding wrapping key. While it is possible to create a key-wrapping and unwrapping mechanism with the other features listed, this feature provides a way to do so without exposing the key to be wrapped to JavaScript. <div class="ednote">Would WRAP and UNWRAP benefit from -SYM or -ASSYM qualifiers?</div></p></li>
+ <li><p><dfn id="UNWRAP">UNWRAP</dfn> which allows a web application to use a key to unwrap another encrypted key or key pair, which can then be used in standard cryptographic operations. While it is possible to create a key-wrapping and unwrapping mechanism with the other features listed, this feature provides a way to do so without exposing the key to be wrapped to JavaScript.</p>
+ <div class="ednote"><p>This feature is subject to discussion, including further work by the <a href="#JOSE">JOSE WG</a>. See <a href="https://www.w3.org/2012/webcrypto/track/issues/35">ISSUE-35</a> logged by the WebCrypto WG.</p></div>
+ </li>
- </ul>
+ <li><p><dfn id="NAMEDKEY">NAMEDKEY</dfn> which allows an application in JavaScript to discover a <dfn id="pre-prov">pre-provisioned</dfn> key within the scope of the application's origin, which exists at the time of the application's first invocation, and has not been derived, generated or imported by the application using any of the features listed above; such keys may have been provisioned by a device manufacturer, for example, and the JavaSript application can access them for initial authorization and authentication at time of first invocation. </p>
+ <div class="note"><p>This feature is developed in the <a href="#KeyDiscover">Key Discovery API</a>.</p></div>
+ </li>
+ </ul>
</div>
<div id='scenarios' class='section'>
<h2>Use Case Scenarios</h2>
- <p>This section collates use case scenarios based on the requirements.</p>
- <div id='banking-korea' class='section'>
+ <p>This section collates use case scenarios that leverages the <a href="#WebCrypto">WebCrypto API</a> or the <a href="#KeyDiscovery">Key Discovery API</a>. Where possible, sample code is provided, and should be considered illustrative only, since the underlying API specifications are changing.</p>
+ <div id='banking' class='section'>
<h3>Banking Transactions</h3>
- <p>Park Jae-sang opens up a bank account with Gangnam Bank (GB), and wishes to log-in and engage in online transactions, including account balance checking, online payments (with some automated scheduled payments), and account transfers between domestic and investment accounts. The first time Park logs in to the GB website with a temporary verification code sent to his cell phone, the bank asks him to ascertain if the browser he is using is not at a kiosk; moreover, he is asked if it is a web browser and machine configuration he will use often.</p>
- <p>He confirms that it is. The GB web site then asks him to generate a public key/private key pair, along with a digital certificate. Park consents, and the web page creates the key pair, storing his private key in the browser's designated key store, along with a one-time key escrow by the bank. Additionally, Jae-sang is presented with the bank's public key, such that documents issued by the bank can be verified and decrypted. Jae-sang is also presented with a user guide that explains the validity period of the certificate, and for how long it will persist. [<a href="#derive">DERIVE</a> | <a href="#keyex-dh">KEYEX-DH</a>].</p>
+ <p>Park Jae-sang opens up a bank account with Gangnam Bank, and wishes to log-in and engage in online transactions, including account balance checking, online payments (with some automated scheduled payments), and account transfers between domestic and investment accounts. The first time Park logs in to the Gangnam Bank website (Gangnam Bank's website from now on will be abbreviated "GB") with a temporary verification code sent to his cell phone, the bank asks him to ascertain if the browser he is using is not at a kiosk; moreover, he is asked if it is a web browser and machine configuration he will use often.</p>
+ <p>He confirms that it is. The GB web site then asks him to generate a public key/private key pair. Park consents, and the web page creates the key pair, storing his private key in the browser's designated key store, along with a one-time key escrow by the bank. Additionally, Jae-sang is presented with the bank's public key, such that documents issued by the bank can be verified and decrypted; Jae-sang presents the derived public key to GB. Jae-sang is also presented with a user guide that explains the validity period of the certificate, and for how long it will persist. [<a href="#derive">DERIVE</a> | <a href="#keyex-dh">KEYEX-DH</a>].</p>
<div class="example">
<p>GB may first generate some key pairs for Jae-sang. These include the public key/private key pair which will be used for digital signatures.</p>
<x:codeblock language="es">
- <span class="comment">// TODO add derivation for RSASSA-PKCS1-v1_5 key pair generation </span>
+ <span class="comment">// Algorithm Object</span>
+var algorithmKeyGen = {
+name: "RSASSA-PKCS1-v1_5",
+<span class="comment">// RsaKeyGenParams</span>
+ params: {
+ modulusLength: 2048,
+ publicExponent: new Uint8Array([0x01, 0x00, 0x01]), <span class="comment">// Equivalent to 65537</span>
+ }
+};
+
+var keyGen = window.crypto.generateKey(algorithmKeyGen,
+ false, <span class="comment">// extractable</span>
+ ["sign"]);
+
+keyGen.oncomplete = function(event) {
+
+ <span class="comment">// Store the key pair in IndexedDB</span>
+ <span class="comment">// Perform a signing operation</span>
+}
</x:codeblock>
- <p>GB may then use a key exchange mechanism to exchange keys with the server. This includes making sure that the client (Jae-sang) obtains a copy of GB's public key, and that GB obtains a copy of Jae-sang's public key, which were generated in the preceding step. </p>
+ <p>GB may then use a key exchange mechanism to exchange keys with the server over TLS. This includes making sure that the client (Jae-sang) obtains a copy of GB's public key, and that GB obtains a copy of Jae-sang's public key, which were generated in the preceding step. </p>
<x:codeblock language="es">
- <span class="comment">// TODO add some Diffie-Hellman code </span>
+ <span class="comment">/**
+ TODO add some Diffie-Hellman key exchange code which results in
+ 1. Jae-sang having GB's public key
+ 2. GB having Jae-sang's public key
+ **/</span>
+
</x:codeblock>
</div>
- <p>Subsequent access to the GB website -- always over TLS -- is triggered via presentation of the key and certificate that Jae-sang generated when he first accessed the website. JavaScript initially loaded by GB contains a message that only Jae-sang can decipher, since it is encrypted with his public key; moreover, that message is signed by GB, which gives the client confidence that the message originates from GB. The message is deciphered, and the deciphered message is then digitally signed and sent back to the GB server. This establishes identity with non-repudiation. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#sign">SIGN</a>].
+ <p>Subsequent access to the GB website -- always over <a href="#TLS">TLS</a> -- is triggered via presentation of the key and certificate that Jae-sang generated when he first accessed the website. JavaScript initially loaded by GB contains a message that only Jae-sang can decipher, since it is encrypted with his public key; moreover, that message is signed by GB, which gives the client confidence that the message originates from GB. The message is deciphered, and the deciphered message is then digitally signed and sent back to the GB server. This establishes identity with non-repudiation. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-ASSYM</a> | <a href="#sign">SIGN</a>].
<div class="example">
- <p><div class="ednote">Flesh out this example.</div> </p>
+ <p>In the example below, an encrypted message is signed by GB. The signature is verified, and upon successful verfication, is decrypted. The decrypted message is then signed and sent to GB. This example should be seen as a simplification for illustrative purposes only, since assymetric encryption and decryption isn't recommended, and techniques such as key wrapping should be used [+<a href="#unwrap">UNWRAP</a>].</p>
<x:codeblock language="es">
<span class="comment">// Message generated by GB... the ellipsis are added. </span>
@@ -167,14 +202,12 @@
hash: "SHA-256"
}
};
- verifier = window.crypto.createVerifier(mRSARFC3447, pubGBKeySign, getSignature());
- verifier.init();
- verifier.processData(signature);
- verifier.complete();
+ verifier = window.crypto.verify(mRSARFC3447, pubGBKeySign, signature);
verifier.oncomplete = function(e){
<span class="comment">/*
If verified, obtain a prvKeyEncrypt from IndexedDB representing Jae-sang's private key and:
- 1. Decrypt the message
+ 1. Decrypt the message. Note that here, typically the encryption key might be symmetric
+ and wrapped. This sample simplifies this by not demonstrating key wrapping.
2. Sign it
3. Send it back
Else the signature is invalid -- abort
@@ -182,10 +215,9 @@
</span>
if (e.target.result == true)
{
- var decrypter = window.crypto.createDecrypter("RSAES-PKCS1-v1_5", prvKeyEncrypt);
- decrypter.init();
- decrypter.processData(pMessage);
- decrypter.onprogress = function(e){e.target.complete()};
+ var decrypter = window.crypto.decrypt("RSAES-PKCS1-v1_5", prvKeyEncrypt);
+ decrypter.process(pMessage);
+ decrypter.onprogress = function(e){e.target.finish()};
decrypter.oncomplete = function(evt)
{
@@ -195,10 +227,8 @@
<span class="comment">/* Assume key retrieval code from IndexedDB that results in pubKeySign */</span>
- var signer = window.crypto.createSigner(mRSARFC3447, pubKeySign);
- signer.init();
- signer.processData(message);
- signer.onprogress = function(e){e.target.complete();}
+ var signer = window.crypto.sign(mRSARFC3447, pubKeySign, message);
+ signer.onprogress = function(e){e.target.finish();}
signer.oncomplete = function(evt)
{
<span class="comment">/*
@@ -213,32 +243,46 @@
<span class="comment">// Unverified signature -- ABORT </span>
}
}
-
-
-
</x:codeblock>
</div>
- His browser presents this key every time he accesses the website and enters his password, which effectively binds his username and password to the generated private key and certificate. Additionally, Jae-sang can digitally sign online checks, authorize payments, and sign tax forms that he submits to the bank site using this generated key [<a href="#sign">SIGN</a>]. He can also perform the following tasks, following an authentication cycle such as the one described above:</p>
+ His browser presents this key every time he accesses the website and enters his password, which effectively binds his username and password to the generated private key. Additionally, Jae-sang can digitally sign online checks, authorize payments, and sign tax forms that he submits to the bank site using this generated key [<a href="#sign">SIGN</a>]. He can also perform the following tasks, following an authentication cycle such as the one described above:</p>
<ol>
- <li><p>Receive documents from GB via HTTP that only he can read, with the assurance that they have come from GB and only GB. These include his private bank statements and tax documents, which are signed with his public key, already obtained in a previous step. [<a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#decrypt">DECRYPT</a>]</p></li>
- <li><p>Submit documents to GB that only GB can read, with the assurance that these have come from Jae-sang. Such documents include confidential financial information. [<a href="#sign">SIGN</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>]</p></li>
+ <li><p>Receive encrypted documents from GB via HTTP that only he can read, with the assurance that they have come from GB and only GB. These include his private bank statements and tax documents, which are signed with his public key, already obtained in a previous step. [<a href="#verify">VERIFY</a> | <a href="#UNWRAP">UNWRAP</a>| <a href="#decrypt-sym">DECRYPT-SYM</a> ].</p></li>
+ <li><p>Submit documents to GB that only GB can read, with the assurance that these have come from Jae-sang. Such documents include confidential financial information, and may be encrypted at submission. [<a href="#sign">SIGN</a> | <a href="#derive-sym">DERIVE-SYM</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#wrap">WRAP</a>]</p></li>
</ol>
- <p>If GB wishes to "cache" aspects of reusuable authentication code, but cannot avail of a code signing system, GB can employ a similar data integrity mechanism that the <a href="#data-integrity">social networking site uses</a>. Moreover, Jae-sang or GB may at any time reinitiate a key generation for subsequent transactions.</p>
+ <p>If GB wishes to "cache" aspects of reusuable authentication code, but cannot avail of a code signing system, GB can employ a similar data integrity mechanism that the <a href="#data-integrity">social networking site uses</a>. Moreover, Jae-sang or GB may at any time reinitiate a key generation operation for subsequent transactions; GB will determine the validity of the keys in question.</p>
</div>
<div id='video-service' class='section'>
<h3>Video Services</h3>
- <p>Virginie connects to her favorite video service to watch an episode of a show she is interested in using her entertainment device, which connects to the biggest screen in her living room. The video service collects a monthly subscription fee and allows the watching of five streaming movies a month at that fee, and streams high definition content over an Internet connection. Virginie does the following:</p>
- <ol>
- <li><p>She sets her device up to interact with the service. Her device runs a user agent that meets the conformance criteria for the Web Cryptography API specification. During the set up process, the entertainment device generates the keys it will use and exchanges them safely with the video service [<a href="#derive">DERIVE</a> | <a href="#derive-pki">DERIVE-PKI</a> | <a href="#keys-dh">KEYEX-DH</a>].</p></li>
- <li><p>Subsequent access to the video service from her device is seamless, and it identifies her as Virginie, loading her preferences and her watch queue. [<a href="#keycall">KEYCALL</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#sign">??SIGN</a>]. She can access the service and browse videos to watch.</p></li>
- <li><p>She selects her favorite show and picks an episode that she has not yet seen. The service then determines that she is authorized to watch that video, and streams that video. [VERIFY | SIGN]</p></li>
- <li><p>Virginie rates the video so that the service understands her preferences. Along with personalized data about Virginie, the device sends usage statistics and metrics back to the service [<a href="#mac">MAC</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>].</p></li>
- </ol>
- </div>
+<p>A Video Service Provider wishes to distribute high quality commercial video to users of web-enabled TVs and Set Top Boxes. The video in question can only be delivered to devices with certain capabilities that meet the service provider's security requirements, which may vary based on the content and content quality to be delivered. In order to determine whether the device is indeed approved to be used with the video service, the service provider arranges for suitable devices to each be pre-provisioned with a cryptographic key and associated identifier by the device manufacture, which are made known to the service provider.</p>
+
+<p>Ryan has just bought a new TV and wishes to watch video content from the service provider. He connects the TV to the Internet, and navigates to the video provider's website. The video provider's site establishes a secure communication channel between the video provider's page on the TV and the video provider's servers, proving to the servers that Ryan's TV is indeed one of those that meets the security requirements by use of the cryptographic key and identifier pre-provisioned on the TV. The video provider's page on the TV likewise verifies that it is talking to a genuine server, preventing the hijacking of Ryan's video watching by a malicious third party. To ensure the highest security, the pre-provisoned key is used minimally in this process to deliver session keys. <p>[<a href="#namedkey">NAMEDKEY</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#mac">MAC</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#decrypt-sym">DECRYPT-SYM</a> | <a href="#sign">SIGN</a>]</p></p>
+<div class="example">
+<p>The Key Discovery API describes the provides a mechanism for an application in JavaScript to detect the presence of a pre-provisioned key using the name of a disclosed identifier. </p>
+<div class="ednote"><p>While <code>KeyOperation</code> is asynchronous and event driven, the key retrieval mechanism is synchronous; this might change in subsequent drafts.</p></div>
+<x:codeblock language="es">
+var keys = window.getKeysByName("VetFlxL33t_Device.p1a.b11");
+keys.onerror = function(e){
+ fail("This device is not authorized for Video Service Provider videos.");
+ }
+keys.oncomplete = function(e){
+ if(e.target.result.name == "VetFlxL33t_Device.p1a.b11"){
+ <span class="comment">// Perform further crypto operations</span>
+ <span class="comment"> ... </span>
+ }
+}
+</x:codeblock>
+</div>
+<p>Ryan creates an account with the service provider and signs up for the lowest level of service, which enables him to connect five devices to the service at any one time. Ryan's account creation involved the creation of a specific key pair to uniquely identify him. [<a href="#derive-assym">DERIVE-ASSYM</a> | <a href="#keyex">KEYEX</a> | <a href="#keycall">KEYCALL</a> | <a href="#namedkey">NAMEDKEY</a> | <a href="#sign">SIGN</a> ]</p>
+<p>
+The video service provider is able to track the number of devices Ryan has connected to the service by virtue of the pre-provisioned keys and identifiers, so that when he attempts to connect a sixth device, the service can prompt him to upgrade his service level or deactivate one of the existing devices. [<a href="#keycall">KEYCALL</a> | <a href="#namedkey">NAMEDKEY</a>]</p>
+<p>
+Ryan finally attempts to play some video through the service. By virtue of the secure connection, the video service provider is able to make content authorization decisions that are tailored to the security capabilities of the exact make, model and version of TV that Ryan has purchased, thereby ensuring that the content providers security requirements are met in respect of the specific content requested. Ryan's devices send encrypted messages about quality of service and watching behavior to the video service provider. [<a href="#namedkey">NAMEDKEY</a> | <a href="#keycall">KEYCALL</a> | <a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#mac">MAC</a> | <a href="#wrap">WRAP</a> | <a href="#encrypt">ENCRYPT</a>]</p>
+</div>
<div id='data-integrity' class='section'>
<h3>Code Sanctity and Bandwidth Saver</h3>
- <p>A major social networking site wishes to optimize website performance by storing JavaScript and other resources in local storage, preventing a needless server roundrip. The social network site wishes to verify that these resources have not been tampered with; the service uses <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> to store assets for their web pages, notably JavaScript. Their threat model is such that the social networking site implicitly trusts the HTTP connection (which uses TLS), the browser, and the HTTP cache, but cannot vouch for localStorage or IndexedDB. Let us take the case of a couple who have gone from being "In a Relationship" to "It's Complicated." John Doe uses the social networking site often, while Jane Doe, a JavaScript programmer, packs her bags to move out of the apartment.
+ <p>A major social networking site wishes to optimize website performance by storing JavaScript and other resources in local storage, preventing a needless server roundrip. The social network site wishes to verify that these resources have not been tampered with; the service uses <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> to store assets for their web pages, notably JavaScript. Their threat model is such that the social networking site implicitly trusts the HTTP connection (which uses <a href="#TLS">TLS</a>), the browser, and the HTTP cache, but cannot vouch for <a href="#localStorage"><code>localStorage</code></a> or <a href="#IndexedDB"><code>IndexedDB</code></a>. Let us take the case of a couple who have gone from being "In a Relationship" to "It's Complicated." John Doe uses the social networking site often, while Jane Doe, a JavaScript programmer, packs her bags to move out of the apartment.</p>
<div class="example">
<p>This illustrates a worst case scenario, in which <code>localStorage</code> is compromised by a malicious user. Normally, the social networking site deploys code of the sort below, which John Doe's browser runs everytime he logs into the social networking site.</p>
<x:codeblock language="es">
@@ -282,10 +326,8 @@
</span>
bufferData = createArrayBufferView(src);
- var digest = window.crypto.createDigester("SHA-256");
- digest.init();
- digest.processData(bufferData);
- digest.complete();
+ var digest = window.crypto.digest("SHA-256", bufferData);
+ digest.finish();
digest.oncomplete = function(e)
{
if(e.target.result === src_hash)
@@ -302,17 +344,20 @@
</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 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 class="note"><p>The conversion to an <a href="#TypedArrays"><code>ArrayBufferView</code></a> 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="#digest">DIGEST</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
+<p>Since their threat model trusts the network layer (which includes <a href="#TLS">TLS</a>, and a distributed web cache not entirely on their own servers) but mistrusts the user's machine to store code via <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> the <a href="#WebCrypto">WebCrypto API</a> offers mitigations:</p>
+<ol>
+ <li><p>As in the example above, the social network can generate a digest of the material extracted from the client storage, and compare this to a pristine version of the digest that the social networking site makes available to the client. If the two digests match, the code is deemed safe. [<a href="#digest">DIGEST</a>]</p></li>
+ <li><p>They can improve on the model above by "signing with an HMAC" (or "signed hash") and then verifying the HMAC. This model offers one level more robustness, since the verification occurs within the WebCrypto API, as opposed to within the application. [<a href="#sign">SIGN</a> | <a href="#hmac">HMAC</a> | <a href="#verify">VERIFY</a>]</p></li>
+</ol>
</div>
- <div id='encrypt' class='section'>
- <h3>Fostering Encrypted Communications</h3>
- <p>Tantek wishes to communicate with Ryan securely. Moreover, Tantek wishes to use an email web application (EWA) provided by a third party, which is a web site that allows users who have accounts to set up email accounts of their own choosing -- that is, users can enter in existing POP/IMAP/SMTP username and password credentials, or simply use an email address provided by the EWA.</p>
- <p>Ryan provides a PGP key on his website, encoded in the relevant conventions. For instance, he uses microformats where relevant, and follows the common practice of including a Base64 "blob" that represents his public key.</p>
+ <div id='encryptedWebMail' class='section'>
+ <h3>Encrypted Communications via Webmail</h3>
+ <p>Tantek wishes to communicate with Ryan securely. Moreover, Tantek wishes to use an email web application (EWA) provided by a third party, which is a web site that allows users who have accounts to set up email accounts of their own choosing -- that is, users can enter in existing POP/IMAP/SMTP username and password credentials, or simply use an email address provided by the EWA at its own address. The EWA serves to send messages, as well as provide a message store available from anywhere. It allows for the possibility of sending encrypted messages.</p>
+ <p>Ryan provides a PGP key on his website, encoded in the relevant conventions. For instance, he uses <a href="#microformats">microformats</a> where relevant, and follows the common practice of including a Base64 text string that represents his public key.</p>
<div class="example">
- <p>Ryan uses the hCard format to encapsulate contact information with some semantic annotation within the markup of his webpage. Within the hCard, he does something like this:</p>
+ <p>Ryan uses the <a href="#hcard">hCard</a> format to encapsulate contact information with some semantic annotation within the markup of his webpage. Within the <a href="#hcard">hCard</a>, he does something like this:</p>
<x:codeblock language="es">
<span class="key">
@@ -327,32 +372,118 @@
</x:codeblock>
<p>The ellipsis have been added for brevity.</p>
</div>
-<p>Logging on to EWA, Tantek may find UI that prompts him to enter in Ryan's hCard path. Tantek does so, and EWA then begins the process of importing Ryan's PGP key. In order to do so, it must first "scrub" the key format to be in one of the accepted import formats of the WebCrypto API.</p>
+<p>Logging on to EWA, Tantek is prompted to import Ryan's contact information from his web page, and is notified that Ryan's public key will also be imported. EWA then begins the process of importing Ryan's PGP key, since it understands how to parse public keys within <a href="#hCard">hCard</a> content. In order to import the key for storage under EWA's origin, it must first "scrub" the key format to be in one of the accepted import formats of the <a href="#WebCrypto">WebCrypto API</a>.</p>
<div class="example">
-<p>// TODO Enter sample code for importing public key.</p>
-</div>
+<p>Here, the Contacts API [cf. <a href="#MozillaContacts">Mozilla</a>][cf. <a href="#GoogleContacts">Google</a>][cf. <a href="#DAPContacts">DAP</a>] could be used to procure Ryan's contact information, and can be one way of importing the key for use by an application such as EWA. Due the same origin policy [cf. <a href="#HTML">HTML</a>], EWA must import the key, so that operations conducted with it fall under the domain of EWA. Assume this importing is done, and convert the key to <a href="#JWK">JSON Web Key</a> format, which the <a href="#WebCrypto">WebCrypto API</a> accepts if converted to octets.</p>
+<x:codeblock language="es">
+<span class="comment">/**
+ 1. First convert the PGP key format into an "importable" format by the WebCrypto API; assume "keyString" is the PGP format
+ Utility functions are assumed here as well.
+ 2. Import the key using the WebCrypto API
+ **/</span>
+
+var alg = "RSA";
+
+var jwkKey = convertToJWK(keyString, alg);
+
+var jwkKeyObject = JSON.parse(jwkKey);
+
+<span class="comment">// Convert to ArrayBufferView</span>
+var octetsKey = mByteArray(jwkKey);
+
+
+var importer = window.crypto.importKey("jwk", octetsKey, "RSAES-PKCS1-v1_5", false, ["encrypt", "verify"]);
+
+importer.oncomplete() = function(evt){
+ var keyImported = evt.target.result;
+
+ <span class="comment">/**
+ 1. Store the new object keyImported in IndexedDB
+ 2. The Key ID used to store the public key may be Ryan's contact
+ 3. Or it could be jkwKeyObject.kid
+ **/</span>
+}
+</x:codeblock>
+</div>
+<p>Following the key import and storage sequence, the key now serves as a key within the origin of EWA. EWA can then offer Tantek the option of encrypting messages to Ryan, which may follow the pattern below:</p>
+<ol>
+ <li>Tantek composes a message that he wishes to send only to Ryan.</li>
+ <li>EWA generates a symmetric key on Tantek's behalf, and uses Ryan's public key, just imported, to wrap that key. [<a href="#derive-sym">DERIVE-SYM</a> | <a href="#keycall">KEYCALL</a> | <a href="#wrap">WRAP</a>].</li>
+ <li>EWA then signs the encrypted message and wrapped key, and sends them from Tantek's email account on Tantek's behalf [<a href="#sign">SIGN</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a>].</li>
+ <li>Ryan also logs into EWA. Separately, he has also imported Tantek's public key to EWA using a similar mechanism that Ryan did. In this case, as long as Ryan has Tantek's public key, he does not strictly need to log into the same EWA as Tantek does; instead, Ryan may choose another email web application with a different origin, but with similar functionality, such that the public key is imported to be used within the origin of the web application. Ryan receives the message, verifies that it is indeed from Tantek, decrypts and reads the message using his corresponding private key. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a>].</li>
+</ol>
+<div class="note"><p>The use case above contains some risk; unless the source and provenance of keys are understood and trusted, the model above for "across the web" key importing lends itself to abuse by malicious users.</p></div>
</div>
<div id='realtime-messaging' class='section'>
<h3>Off The Record Real Time Messaging</h3>
- <p>David and Nadim wish to have an "Off The Record" chat in real time, completely between them, and in text, including the ability to share digital data such as photographs. They log on to a chat server, and connect to each other's machines directly. The server merely serves up the UI for the chat client, and does not log their conversation (and in fact, cannot). David and Nadim need to:</p>
- <ul>
- <li><p>Be assured that they are who they claim they are. [<a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt">DECRYPT</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#encrypt">ENCRYPT</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>] </p></li>
- <li><p>Be assured that during a conversation, messages sent back and forth are unmodified. [<a href="#encrypt">ENCRYPT</a> | <a href="#decrypt">DECRYPT</a>] </p></li>
- <li><p>Be assured that after the conversation, the contents of the conversation cannot be determined. [ENCRYPT-PKI][DECRYPT-PKI] </p></li>
- </ul>
-
+ <p>David and Nadim wish to have an "Off The Record" chat in real time, completely between them, primarily using text, as well as the ability to share digital data such as photographs. They log on to a chat server, and connect to each other's machines directly. The server merely serves up the UI for the chat client, and does not log their conversation (and in fact, cannot). The respective web pages on David and Nadim's browsers may use WebSockets and the WebCrypto API to </p>
+ <ol>
+ <li><p>The generation of assymetric keys for David and Nadim respectively, such that both get public and private keys. [<a href="#derive">DERIVE</a>]</p></li>
+ <li><p>A key exchange, so that David and Nadim get each other's public keys. It is conceivable that using the WebCrypto API the chat application can enable David and Nadim to use a Diffie-Hellman key exchange, or a mechanism such as SIGMA [cf.<a href="#OTR">OTR</a>] over <code>WebSocket</code>s [cf. <a href="#HTML">HTML</a>]. The key exchange which accompanies message exchanges involves the generation of cryptographically secure random numbers. [<a href="#random">RANDOM</a> | <a href="#keyex">KEYEX</a> | <a href="#keyex-dh">KEYEX-DH</a>]</p></li>
+ <li><p>David or Nadim may now compose a message to each other. Each message exchange involves authentication, message authentication codes, further key derivation, and further key exchanges. [<a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#mac">MAC</a> | <a href="#random">RANDOM</a> | <a href="#derive">DERIVE</a> | <a href="#keyex">KEYEX</a> | <a href="#keyex-dh">KEYEX-DH</a>] </p></li>
+ </ol>
+ <div class="ednote"><p>This use case needs additional details.</p></div>
</div>
<div id='savemystuff' class='section'>
<h3>Documents In the Cloud</h3>
- <p>Vijay wishes to confidentially store certain documents, including photos, music, pages from the novel he is working on, and notes about his employer using a web service that he pays a monthly subscription to for such confidential storage. He can drag and drop content from his laptop onto a web page of the service, and it automatically stores it in an encrypted manner. Vijay can do the following:</p>
+ <p>Vijay wishes to confidentially store certain documents of various file types using a web service that he pays a monthly subscription to for such confidential storage. The confidential storage web application (abbreviated "SWA") makes the claim that all storage is encrypted, and that even it cannot access the contents of what a user stores. He can drag and drop content from his laptop onto a web page of the service, and it automatically encrypts it and stores it in an encrypted manner. Vijay can do the following:</p>
<ol>
- <li><p>Log on to the service using his credentials; after the service determines that Vijay is using his primary browser, which he will use to access the service subsequently, it generates encryption keys. [<a href="#derive">DERIVE</a> | <a href="#derive-pki">DERIVE-PKI</a>] </p></li>
- <li><p>Drag over content from his underlying file system that he wishes to store. [<a href="#encrypt-pki">ENCRYPT-PKI</a>] </p></li>
- <li><p>Store that content on the server, with the assurance that it is stored there in a way that is virtually undecipherable to third-parties, including employees of the service in question.</p></li>
- <li><p>Later, Vijay can retrieve the content, and save it back to his local file system. [<a href="#decrypt-pki">DECRYPT-PKI</a>] </p></li>
+ <li><p>Log on to the service using his credentials; after the service determines that Vijay is using his primary browser, which he will use to access the service subsequently, it generates both signature and encryption key pairs. Derivation may be similar to the <a href="#banking">banking use case</a>. [<a href="#derive-assym">DERIVE-ASSYM</a> | <a href="keyex-dh">KEYEX-DH</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a> | <a href="#sign">SIGN</a>] </p></li>
+ <li><p>Drag over content from his underlying file system that he wishes to store. The SWA encrypts the content, and uploads it. It may make multipart cryptographic operations on a given file, and it may also "chunk upload" large content, depending on file-size. [<a href="#sign">SIGN</a> | <a href="#hmac">HMAC</a> | <a href="#derive-sym">DERIVE-SYM</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#keycall">KEYCALL</a> | <a href="#wrap">WRAP</a>] </p>
+<div class="example">
+<p>Multipart cryptographic operations can be performed with the same key.</p>
+<x:codeblock language="es">
+<span class="comment">// TODO: Demonstrate multi-part cryptographic operations</span>
+</x:codeblock>
+</div>
+</li>
+
+ <li><p>Store that content on the server, with the assurance that it is stored there in a way that is virtually undecipherable to third-parties, including those running the SWA.</p></li>
+ <li><p>Later, Vijay can retrieve the content, and save it back to his local file system. He has the assurance that the content has not been tampered with since it was stored, and that it in fact is from SWA. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#hmac">HMAC</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a>] </p></li>
</ol>
</div>
</div>
+ <div id='references' class='section'>
+ <h2>References</h2>
+<dl class='bibliography'>
+ <dt id='WebCrypto'>Web Cryptography API</dt>
+ <dd><cite><a href='http://dvcs.w3.org/hg/webcrypto-api/'>Web Cryptography API</a></cite>, D. Dahl, R. Sleevi. W3C</dd>
+ <dt id='KeyDiscovery'>WebCrypto Key Discovery API</dt>
+ <dd><cite><a href='http://dvcs.w3.org/hg/webcrypto-keydiscovery'>WebCrypto Key Discovery</a></cite>, M. Watson. W3C</dd>
+ <dt id='localStorage'>Web Storage</dt>
+ <dd><cite><a href='http://dev.w3.org/html5/webstorage/'>Web Storage</a></cite>, I. Hickson. W3C</dd>
+ <dt id='IndexedDB'>IndexedDB</dt>
+ <dd><cite><a href='http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html'>Indexed Database API</a></cite>, N. Mehta, J. Sicking, E. Graff, A. Popescu, J. Orlow. W3C</dd>
+ <dt id="TypedArray">Typed Array Specification</dt>
+ <dd><cite><a href="http://www.khronos.org/registry/typedarray/specs/latest/">Typed Array Specification, Editor's Draft</a></cite>, D. Herman, K. Russell. W3C</dd>
+ <dt id="TLS">TLS</dt>
+ <dd><cite><a href="http://tools.ietf.org/html/rfc5246">The Transport Layer Security (TLS) Protocol</a></cite>, T. Dierks, E. Rescorla. W3C</dd>
+ <dt id='OTR'>OTR</dt>
+ <dd><cite><a href="http://www.cypherpunks.ca/otr/Protocol-v3-4.0.0.html">Off-the-Record Messaging Protocol version 3</a></cite>, cypherpunks.ca</dd>
+ <dt id='JOSE'>JOSE WG</dt>
+ <dd><cite><a href="https://tools.ietf.org/wg/jose/">The JOSE (JavaScript Object Signing and Encryption) WG</a></cite>, IETF</dd>
+ <dt id='microformats'>Microformats</dt>
+ <dd><cite><a href="http://www.microformats.org/">Microformats</a></cite>, microformats.org</dd>
+ <dt id='hcard'>hCard</dt>
+ <dd><cite><a href="http://microformats.org/wiki/hcard">hCard</a></cite>, T. Celik, B. Suda, microformats.org</dd>
+ <dt id='keyexamples'>Microformats Key Examples</dt>
+ <dd><cite><a href="http://microformats.org/wiki/key-examples">Key Examples</a></cite>, T. Celik, microformats.org</dd>
+ <dt id="JWK">JSON Web Key</dt>
+ <dd><cite><a href="https://datatracker.ietf.org/doc/draft-ietf-jose-json-web-key/">JSON Web Key (JWK) draft-ietf-jose-json-web-key-07</a></cite>, M. Jones, IETF</dd>
+ <dt id="GoogleContacts">Google Contacts API</dt>
+ <dd><cite><a href="https://developers.google.com/google-apps/contacts/v3/">Google Contacts API v. 3.0</a></cite>, Google</dd>
+ <dt id="MozillaContacts">Mozilla Contacts API</dt>
+ <dd><cite><a href="https://wiki.mozilla.org/WebAPI/ContactsAPI">Mozilla Proposed Contacts API</a></cite>, Mozilla</dd>
+ <dt id="DAPContacts">Pick Contacts Intent</dt>
+ <dd><cite><a href="http://www.w3.org/TR/contacts-api/">Pick Contacts Intent</a></cite>, R. Tibbett, R. Berjon, W3C</dd>
+ <dt id="HTML">HTML</dt>
+ <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/network.html">HTML Living Standard</a></cite>, WHATWG</dd>
+</dl>
+
+
+
+
+ </div>
</div>
</body>
--- a/Overview.html Mon Dec 10 09:57:19 2012 -0500
+++ b/Overview.html Mon Dec 17 13:32:37 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/06 12:23:12 arangana Exp $" />
+ <meta name="revision" content="$Id: Overview-FA.xml,v 1.164 2012/12/17 12:23:12 arangana Exp $" />
<link rel="stylesheet" href="FileAPI.css" type="text/css" />
<script src="section-links.js" type="application/ecmascript"></script>
@@ -30,16 +30,16 @@
<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>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="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>17 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>
<p>
- This document collates the target use cases for the Web Cryptography API. These use cases, described as <em>scenarios</em>, represent the set of expected functionality that may be achieved by the Web Cryptography API.
+ This document is NOT a recommendation track document, and should be read as an informative overview of the target use cases for a cryptographic API for the web. These use cases, described as <em>scenarios</em>, represent some of the set of expected functionality that may be achieved by the <a href="#WebCrypto">Web Cryptography API</a>, which provides an API for cryptographic operations such as encryption and decryption, and the <a href="#KeyDiscovery">Key Discovery API</a>, which specifically covers the ability to access cryptographic keys that have been <a href="#pre-prov"><em>pre-provisioned</em></a>. As both APIs are under construction, the reader should consult each specification for changes, and should treat sample code provided here as illustrative only. Presented here are <em>primary</em> use cases, showing what the working group hopes to achieve first. Other use cases are marked as <em>secondary</em>.
</p>
- <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 class="ednote"><div class="ednoteHeader">Editorial note</div><p>This is revision $Id: Overview-FA.xml,v 1.164 2012/12/17 12:23:12 arangana Exp $.</p><p>There are 4 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 6 December 2012 <b>Editor’s Draft</b> of the
+ This document is the 17 December 2012 <b>Editor’s Draft</b> of the
<cite>Web Cryptography API Use Cases</cite> specification.
Please send comments about this document to
@@ -59,7 +59,7 @@
(<a href="http://lists.w3.org/Archives/Public/public-webcrypto/">archived</a>).
</p>
<p>
- Ongoing discussion of this document will be on the <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
+ This document is not a recommendation track document, and is presented for information purposes only. Ongoing discussion of this document will be on the <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
mailing list.
</p>
@@ -88,7 +88,7 @@
This document is produced by the <a href="http://www.w3.org/2012/webcrypto/">Web Cryptography Working Group</a>, within
the W3C <a href="http://www.w3.org/Interaction/">Interaction Domain</a>.
Changes made to this document can be found in the
- <a href="http://dev.w3.org/cvsweb/2006/webapi/FileAPI/Overview-UseCases.xml">W3C public CVS server</a>.
+ <a href="https://dvcs.w3.org/hg/webcrypto-usecases">W3C public Mercurial Repository</a>.
</p>
<p>
Publication as an Editor’s Draft does not imply endorsement by the
@@ -113,54 +113,89 @@
<div id="toc">
<h2>Table of Contents</h2>
- <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#requirements">2. Requirements</a></li><li><a href="#scenarios">3. Use Case Scenarios</a><ul><li><a href="#banking-korea">3.1. Banking Transactions</a></li><li><a href="#video-service">3.2. Video Services</a></li><li><a href="#data-integrity">3.3. Code Sanctity and Bandwidth Saver</a></li><li><a href="#encrypt">3.4. Fostering Encrypted Communications</a></li><li><a href="#realtime-messaging">3.5. Off The Record Real Time Messaging</a></li><li><a href="#savemystuff">3.6. Documents In the Cloud</a></li></ul></li></ul></div>
+ <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#requirements">2. Requirements</a></li><li><a href="#scenarios">3. Use Case Scenarios</a><ul><li><a href="#banking">3.1. Banking Transactions</a></li><li><a href="#video-service">3.2. Video Services</a></li><li><a href="#data-integrity">3.3. Code Sanctity and Bandwidth Saver</a></li><li><a href="#encryptedWebMail">3.4. Encrypted Communications via Webmail</a></li><li><a href="#realtime-messaging">3.5. Off The Record Real Time Messaging</a></li><li><a href="#savemystuff">3.6. Documents In the Cloud</a></li></ul></li><li><a href="#references">4. References</a></li></ul></div>
</div>
<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: 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>
+ <p>The <a href="#WebCrypto">Web Cryptography API</a> describes a JavaScript API for user agents such as web browsers, and exposes basic cryptographic operations, including: digesting, signature generation and verification, encryption, decryption, cryptographic key generation, key derivation, key import and key export. The <a href="#KeyDiscovery">Key Discovery API</a> describes a JavaScript API to invoke <a href="#pre-prov">pre-provisioned keys</a>. This document presents use cases in the form of scenarios that cover the use of both APIs, with each scenario describing a potential web application using these APIs. Where possible, code snippets have been provided to demonstrate what a developer might do when addressing the use case.</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>
+ <p>This section presents required features of a cryptographic API. It is possible that there is 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, which will be used alongside each scenario, illustrating which feature is used.</p>
<ul>
<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, with <dfn id="hmac">HMAC</dfn> being a specific kind of message authentication code, with a specific algorithm.</p></li>
- <li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document with private key, such that upon verification of the signature with the corresponding public key, the document's authenticity from the point of view of the signature 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>
- <li><p><dfn id="encrypt">ENCRYPT</dfn>, the ability to encode a document using an encryption algorithm. <dfn id="encrypt-pki">ENCRYPT-PKI</dfn> is a specific type of encryption involving PKI, and <dfn id="encrypt-sym">ENCRYPT-SYM</dfn> is a specific type of encryption using symmetric keys.</p></li>
- <li><p><dfn id="decrypt">DECRYPT</dfn>, the ability to decrypt a digitally signed document. <dfn id="decrypt-pki">DECRYPT-PKI</dfn> is a specific type of decryption using PKI, and <dfn id="decrypt-sym">DECRYPT-SYM</dfn> is a specific type of decryption using symmetric keys.</p></li>
- <li><p><dfn id="derive">DERIVE</dfn>, the ability to derive a key or keys used in cryptographic operations; <dfn id="derive-pki">DERIVE-PKI</dfn> is the ability to derive keys usable in PKI operations.</p></li>
- <li><p><dfn id="keyexchange">KEYEX</dfn>, the ability for two entities to exchange key(s) without interception by a third party, with <dfn id="keyex-dh">KEYEX-DH</dfn> representing Diffie-Hellman key exchange, a particularly common application of safe key exchange.</p></li>
- <li><p><dfn id="keycall">KEYCALL</dfn>, the ability to call a particular key from a web application that either generated the key or that is in the same domain as the key.</p></li>
- <li><p><dfn id="PKI">-PKI</dfn>, an acronym for <dfn id="pki">Public Key Infrastructure</dfn> used in this document as a suffix to other features.</p></li>
- <li><p><dfn id="SYM">-SYM</dfn>, an acronym for <dfn id="sym">Symmetric Key</dfn> operations, used in this document as a suffix to other features.</p></li>
- <li><p><dfn id="random">RANDOM</dfn>, the ability to generate a random cryptographically secure number.</p></li>
+ <li><p><dfn id="sign">SIGN</dfn>, the ability to digitally sign a document with a private key, such that upon verification of the signature with the corresponding public key, the document's authenticity from the point of view of the signature can be determined. The term document in this context can refer to any kind of data used with 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 or HMAC.</p></li>
+ <li><p><dfn id="encrypt">ENCRYPT</dfn>, the ability to encode a document using an encryption algorithm. <dfn id="encrypt-sym">ENCRYPT-SYM</dfn> is a specific type of encryption using symmetric cryptographic keys, and <dfn id="encrypt-assym">ENCRYPT-ASSYM</dfn> is a specific type of encryption using assymetric cryptographic keys, typically a public and private key pair.</p></li>
+ <li><p><dfn id="decrypt">DECRYPT</dfn>, the ability to decrypt a digitally signed document. <dfn id="decrypt-sym">DECRYPT-SYM</dfn> is a specific type of decryption using symmetric keys, and <dfn id="decrypt-assym">DECRYPT-ASSYM</dfn> is a specific type of decryption using assymetric keys, typically a public and private key pair.</p></li>
+ <li><p><dfn id="derive">DERIVE</dfn>, the ability to derive a key or key pair used in cryptographic operations; <dfn id="derive-assym">DERIVE-ASSYM</dfn> is the ability to derive assymetric keys, typically a public and private key pair, for use with assymetric cryptographic operations, and <dfn id="derive-sym">DERIVE-SYM</dfn> is the ability to derive a symmetric key for use with symmetric cryptographic operations.</p></li>
+ <li><p><dfn id="import">IMPORT</dfn>, the ability to import a key or key pair that have already been created elsewhere, for use within the web application that is invoking the import function, for use within the importing web application's origin. This necessiates an interoperable key format, which may be represented as octets.</p></li>
+ <li><p><dfn id="export">EXPORT</dfn>, the ability to export a key or key pair that can be accessed from within the application that is invoking the export function. This necessiates an interoperable key format, which may be represented as octets, that other web applications can then import.</p></li>
+ <li><p><dfn id="keyexchange">KEYEX</dfn>, the ability for two entities to exchange key(s) without interception by a third party, with <dfn id="keyex-dh">KEYEX-DH</dfn> representing Diffie-Hellman key exchange, a common application of safe key exchange.</p></li>
+ <li><p><dfn id="keycall">KEYCALL</dfn>, the ability to access a particular key (or key pair) from within a web application's key storage, which is within the web application's origin only. Here, the key storage might be IndexedDB or localStorage, and the key or key pair might have been created by the web application or imported by the web application.</p></li>
+ <li><p><dfn id="sym">-SYM</dfn>, an abbreviation for <dfn id="sym">symmetric key cryptographic operations</dfn>, used in this document as a suffix to other features to specifically clarify the feature being invoked by the web application.</p></li>
+ <li><p><dfn id="assym">ASSYM</dfn>, an abbreviation for <dfn id="assym">assymetric key cryptographic operations</dfn>, typically involving a public and private key pair, used in this document as a suffix to other features to specifically clarify the feature being invoked by the web application.</p></li>
+ <li><p><dfn id="random">RANDOM</dfn>, the ability to generate cryptographically secure random numbers.</p></li>
+ </ul>
+ <p>Additionally, the Web Cryptography WG is actively discussing three other features:</p>
+ <ul>
+ <li><p><dfn id="WRAP">WRAP</dfn> which allows a web application to use a key to <em>wrap another key</em>, so that the wrapped key can be unwrapped by a party with the corresponding wrapping key, but is hard to obtain or unwrap by anyone without the corresponding wrapping key. While it is possible to create a key-wrapping and unwrapping mechanism with the other features listed, this feature provides a way to do so without exposing the key to be wrapped to JavaScript. <div class="ednote"><div class="ednoteHeader">Editorial note</div>Would WRAP and UNWRAP benefit from -SYM or -ASSYM qualifiers?</div></p></li>
+ <li><p><dfn id="UNWRAP">UNWRAP</dfn> which allows a web application to use a key to unwrap another encrypted key or key pair, which can then be used in standard cryptographic operations. While it is possible to create a key-wrapping and unwrapping mechanism with the other features listed, this feature provides a way to do so without exposing the key to be wrapped to JavaScript.</p>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>This feature is subject to discussion, including further work by the <a href="#JOSE">JOSE WG</a>. See <a href="https://www.w3.org/2012/webcrypto/track/issues/35">ISSUE-35</a> logged by the WebCrypto WG.</p></div>
+ </li>
- </ul>
+ <li><p><dfn id="NAMEDKEY">NAMEDKEY</dfn> which allows an application in JavaScript to discover a <dfn id="pre-prov">pre-provisioned</dfn> key within the scope of the application's origin, which exists at the time of the application's first invocation, and has not been derived, generated or imported by the application using any of the features listed above; such keys may have been provisioned by a device manufacturer, for example, and the JavaSript application can access them for initial authorization and authentication at time of first invocation. </p>
+ <div class="note"><div class="noteHeader">Note</div><p>This feature is developed in the <a href="#KeyDiscover">Key Discovery API</a>.</p></div>
+ </li>
+ </ul>
</div>
<div id="scenarios" class="section">
<h2>3. Use Case Scenarios</h2>
- <p>This section collates use case scenarios based on the requirements.</p>
- <div id="banking-korea" class="section">
+ <p>This section collates use case scenarios that leverages the <a href="#WebCrypto">WebCrypto API</a> or the <a href="#KeyDiscovery">Key Discovery API</a>. Where possible, sample code is provided, and should be considered illustrative only, since the underlying API specifications are changing.</p>
+ <div id="banking" class="section">
<h3>3.1. Banking Transactions</h3>
- <p>Park Jae-sang opens up a bank account with Gangnam Bank (GB), and wishes to log-in and engage in online transactions, including account balance checking, online payments (with some automated scheduled payments), and account transfers between domestic and investment accounts. The first time Park logs in to the GB website with a temporary verification code sent to his cell phone, the bank asks him to ascertain if the browser he is using is not at a kiosk; moreover, he is asked if it is a web browser and machine configuration he will use often.</p>
- <p>He confirms that it is. The GB web site then asks him to generate a public key/private key pair, along with a digital certificate. Park consents, and the web page creates the key pair, storing his private key in the browser's designated key store, along with a one-time key escrow by the bank. Additionally, Jae-sang is presented with the bank's public key, such that documents issued by the bank can be verified and decrypted. Jae-sang is also presented with a user guide that explains the validity period of the certificate, and for how long it will persist. [<a href="#derive">DERIVE</a> | <a href="#keyex-dh">KEYEX-DH</a>].</p>
+ <p>Park Jae-sang opens up a bank account with Gangnam Bank, and wishes to log-in and engage in online transactions, including account balance checking, online payments (with some automated scheduled payments), and account transfers between domestic and investment accounts. The first time Park logs in to the Gangnam Bank website (Gangnam Bank's website from now on will be abbreviated "GB") with a temporary verification code sent to his cell phone, the bank asks him to ascertain if the browser he is using is not at a kiosk; moreover, he is asked if it is a web browser and machine configuration he will use often.</p>
+ <p>He confirms that it is. The GB web site then asks him to generate a public key/private key pair. Park consents, and the web page creates the key pair, storing his private key in the browser's designated key store, along with a one-time key escrow by the bank. Additionally, Jae-sang is presented with the bank's public key, such that documents issued by the bank can be verified and decrypted; Jae-sang presents the derived public key to GB. Jae-sang is also presented with a user guide that explains the validity period of the certificate, and for how long it will persist. [<a href="#derive">DERIVE</a> | <a href="#keyex-dh">KEYEX-DH</a>].</p>
<div class="example"><div class="exampleHeader">Example</div>
<p>GB may first generate some key pairs for Jae-sang. These include the public key/private key pair which will be used for digital signatures.</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">// TODO add derivation for RSASSA-PKCS1-v1_5 key pair generation </span>
+ <span class="comment">// Algorithm Object</span>
+var algorithmKeyGen = {
+name: "RSASSA-PKCS1-v1_5",
+<span class="comment">// RsaKeyGenParams</span>
+ params: {
+ modulusLength: 2048,
+ publicExponent: new Uint8Array([0x01, 0x00, 0x01]), <span class="comment">// Equivalent to 65537</span>
+ }
+};
+
+var keyGen = window.crypto.generateKey(algorithmKeyGen,
+ false, <span class="comment">// extractable</span>
+ ["sign"]);
+
+keyGen.oncomplete = function(event) {
+
+ <span class="comment">// Store the key pair in IndexedDB</span>
+ <span class="comment">// Perform a signing operation</span>
+}
</code></pre></div></div>
- <p>GB may then use a key exchange mechanism to exchange keys with the server. This includes making sure that the client (Jae-sang) obtains a copy of GB's public key, and that GB obtains a copy of Jae-sang's public key, which were generated in the preceding step. </p>
+ <p>GB may then use a key exchange mechanism to exchange keys with the server over TLS. This includes making sure that the client (Jae-sang) obtains a copy of GB's public key, and that GB obtains a copy of Jae-sang's public key, which were generated in the preceding step. </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">// TODO add some Diffie-Hellman code </span>
+ <span class="comment">/**
+ TODO add some Diffie-Hellman key exchange code which results in
+ 1. Jae-sang having GB's public key
+ 2. GB having Jae-sang's public key
+ **/</span>
+
</code></pre></div></div>
</div>
- <p>Subsequent access to the GB website -- always over TLS -- is triggered via presentation of the key and certificate that Jae-sang generated when he first accessed the website. JavaScript initially loaded by GB contains a message that only Jae-sang can decipher, since it is encrypted with his public key; moreover, that message is signed by GB, which gives the client confidence that the message originates from GB. The message is deciphered, and the deciphered message is then digitally signed and sent back to the GB server. This establishes identity with non-repudiation. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#sign">SIGN</a>].
+ <p>Subsequent access to the GB website -- always over <a href="#TLS">TLS</a> -- is triggered via presentation of the key and certificate that Jae-sang generated when he first accessed the website. JavaScript initially loaded by GB contains a message that only Jae-sang can decipher, since it is encrypted with his public key; moreover, that message is signed by GB, which gives the client confidence that the message originates from GB. The message is deciphered, and the deciphered message is then digitally signed and sent back to the GB server. This establishes identity with non-repudiation. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-ASSYM</a> | <a href="#sign">SIGN</a>].
<div class="example"><div class="exampleHeader">Example</div>
- <p><div class="ednote"><div class="ednoteHeader">Editorial note</div>Flesh out this example.</div> </p>
+ <p>In the example below, an encrypted message is signed by GB. The signature is verified, and upon successful verfication, is decrypted. The decrypted message is then signed and sent to GB. This example should be seen as a simplification for illustrative purposes only, since assymetric encryption and decryption isn't recommended, and techniques such as key wrapping should be used [+<a href="#unwrap">UNWRAP</a>].</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">// Message generated by GB... the ellipsis are added. </span>
@@ -183,14 +218,12 @@
hash: "SHA-256"
}
};
- verifier = window.crypto.createVerifier(mRSARFC3447, pubGBKeySign, getSignature());
- verifier.init();
- verifier.processData(signature);
- verifier.complete();
+ verifier = window.crypto.verify(mRSARFC3447, pubGBKeySign, signature);
verifier.oncomplete = function(e){
<span class="comment">/*
If verified, obtain a prvKeyEncrypt from IndexedDB representing Jae-sang's private key and:
- 1. Decrypt the message
+ 1. Decrypt the message. Note that here, typically the encryption key might be symmetric
+ and wrapped. This sample simplifies this by not demonstrating key wrapping.
2. Sign it
3. Send it back
Else the signature is invalid -- abort
@@ -198,10 +231,9 @@
</span>
if (e.target.result == true)
{
- var decrypter = window.crypto.createDecrypter("RSAES-PKCS1-v1_5", prvKeyEncrypt);
- decrypter.init();
- decrypter.processData(pMessage);
- decrypter.onprogress = function(e){e.target.complete()};
+ var decrypter = window.crypto.decrypt("RSAES-PKCS1-v1_5", prvKeyEncrypt);
+ decrypter.process(pMessage);
+ decrypter.onprogress = function(e){e.target.finish()};
decrypter.oncomplete = function(evt)
{
@@ -211,10 +243,8 @@
<span class="comment">/* Assume key retrieval code from IndexedDB that results in pubKeySign */</span>
- var signer = window.crypto.createSigner(mRSARFC3447, pubKeySign);
- signer.init();
- signer.processData(message);
- signer.onprogress = function(e){e.target.complete();}
+ var signer = window.crypto.sign(mRSARFC3447, pubKeySign, message);
+ signer.onprogress = function(e){e.target.finish();}
signer.oncomplete = function(evt)
{
<span class="comment">/*
@@ -229,32 +259,46 @@
<span class="comment">// Unverified signature -- ABORT </span>
}
}
-
-
-
</code></pre></div></div>
</div>
- His browser presents this key every time he accesses the website and enters his password, which effectively binds his username and password to the generated private key and certificate. Additionally, Jae-sang can digitally sign online checks, authorize payments, and sign tax forms that he submits to the bank site using this generated key [<a href="#sign">SIGN</a>]. He can also perform the following tasks, following an authentication cycle such as the one described above:</p>
+ His browser presents this key every time he accesses the website and enters his password, which effectively binds his username and password to the generated private key. Additionally, Jae-sang can digitally sign online checks, authorize payments, and sign tax forms that he submits to the bank site using this generated key [<a href="#sign">SIGN</a>]. He can also perform the following tasks, following an authentication cycle such as the one described above:</p>
<ol>
- <li><p>Receive documents from GB via HTTP that only he can read, with the assurance that they have come from GB and only GB. These include his private bank statements and tax documents, which are signed with his public key, already obtained in a previous step. [<a href="#verify">VERIFY</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#decrypt">DECRYPT</a>]</p></li>
- <li><p>Submit documents to GB that only GB can read, with the assurance that these have come from Jae-sang. Such documents include confidential financial information. [<a href="#sign">SIGN</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>]</p></li>
+ <li><p>Receive encrypted documents from GB via HTTP that only he can read, with the assurance that they have come from GB and only GB. These include his private bank statements and tax documents, which are signed with his public key, already obtained in a previous step. [<a href="#verify">VERIFY</a> | <a href="#UNWRAP">UNWRAP</a>| <a href="#decrypt-sym">DECRYPT-SYM</a> ].</p></li>
+ <li><p>Submit documents to GB that only GB can read, with the assurance that these have come from Jae-sang. Such documents include confidential financial information, and may be encrypted at submission. [<a href="#sign">SIGN</a> | <a href="#derive-sym">DERIVE-SYM</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#wrap">WRAP</a>]</p></li>
</ol>
- <p>If GB wishes to "cache" aspects of reusuable authentication code, but cannot avail of a code signing system, GB can employ a similar data integrity mechanism that the <a href="#data-integrity">social networking site uses</a>. Moreover, Jae-sang or GB may at any time reinitiate a key generation for subsequent transactions.</p>
+ <p>If GB wishes to "cache" aspects of reusuable authentication code, but cannot avail of a code signing system, GB can employ a similar data integrity mechanism that the <a href="#data-integrity">social networking site uses</a>. Moreover, Jae-sang or GB may at any time reinitiate a key generation operation for subsequent transactions; GB will determine the validity of the keys in question.</p>
</div>
<div id="video-service" class="section">
<h3>3.2. Video Services</h3>
- <p>Virginie connects to her favorite video service to watch an episode of a show she is interested in using her entertainment device, which connects to the biggest screen in her living room. The video service collects a monthly subscription fee and allows the watching of five streaming movies a month at that fee, and streams high definition content over an Internet connection. Virginie does the following:</p>
- <ol>
- <li><p>She sets her device up to interact with the service. Her device runs a user agent that meets the conformance criteria for the Web Cryptography API specification. During the set up process, the entertainment device generates the keys it will use and exchanges them safely with the video service [<a href="#derive">DERIVE</a> | <a href="#derive-pki">DERIVE-PKI</a> | <a href="#keys-dh">KEYEX-DH</a>].</p></li>
- <li><p>Subsequent access to the video service from her device is seamless, and it identifies her as Virginie, loading her preferences and her watch queue. [<a href="#keycall">KEYCALL</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#sign">??SIGN</a>]. She can access the service and browse videos to watch.</p></li>
- <li><p>She selects her favorite show and picks an episode that she has not yet seen. The service then determines that she is authorized to watch that video, and streams that video. [VERIFY | SIGN]</p></li>
- <li><p>Virginie rates the video so that the service understands her preferences. Along with personalized data about Virginie, the device sends usage statistics and metrics back to the service [<a href="#mac">MAC</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>].</p></li>
- </ol>
- </div>
+<p>A Video Service Provider wishes to distribute high quality commercial video to users of web-enabled TVs and Set Top Boxes. The video in question can only be delivered to devices with certain capabilities that meet the service provider's security requirements, which may vary based on the content and content quality to be delivered. In order to determine whether the device is indeed approved to be used with the video service, the service provider arranges for suitable devices to each be pre-provisioned with a cryptographic key and associated identifier by the device manufacture, which are made known to the service provider.</p>
+
+<p>Ryan has just bought a new TV and wishes to watch video content from the service provider. He connects the TV to the Internet, and navigates to the video provider's website. The video provider's site establishes a secure communication channel between the video provider's page on the TV and the video provider's servers, proving to the servers that Ryan's TV is indeed one of those that meets the security requirements by use of the cryptographic key and identifier pre-provisioned on the TV. The video provider's page on the TV likewise verifies that it is talking to a genuine server, preventing the hijacking of Ryan's video watching by a malicious third party. To ensure the highest security, the pre-provisoned key is used minimally in this process to deliver session keys. <p>[<a href="#namedkey">NAMEDKEY</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#mac">MAC</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#decrypt-sym">DECRYPT-SYM</a> | <a href="#sign">SIGN</a>]</p></p>
+<div class="example"><div class="exampleHeader">Example</div>
+<p>The Key Discovery API describes the provides a mechanism for an application in JavaScript to detect the presence of a pre-provisioned key using the name of a disclosed identifier. </p>
+<div class="ednote"><div class="ednoteHeader">Editorial note</div><p>While <code>KeyOperation</code> is asynchronous and event driven, the key retrieval mechanism is synchronous; this might change in subsequent drafts.</p></div>
+<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
+var keys = window.getKeysByName("VetFlxL33t_Device.p1a.b11");
+keys.onerror = function(e){
+ fail("This device is not authorized for Video Service Provider videos.");
+ }
+keys.oncomplete = function(e){
+ if(e.target.result.name == "VetFlxL33t_Device.p1a.b11"){
+ <span class="comment">// Perform further crypto operations</span>
+ <span class="comment"> ... </span>
+ }
+}
+</code></pre></div></div>
+</div>
+<p>Ryan creates an account with the service provider and signs up for the lowest level of service, which enables him to connect five devices to the service at any one time. Ryan's account creation involved the creation of a specific key pair to uniquely identify him. [<a href="#derive-assym">DERIVE-ASSYM</a> | <a href="#keyex">KEYEX</a> | <a href="#keycall">KEYCALL</a> | <a href="#namedkey">NAMEDKEY</a> | <a href="#sign">SIGN</a> ]</p>
+<p>
+The video service provider is able to track the number of devices Ryan has connected to the service by virtue of the pre-provisioned keys and identifiers, so that when he attempts to connect a sixth device, the service can prompt him to upgrade his service level or deactivate one of the existing devices. [<a href="#keycall">KEYCALL</a> | <a href="#namedkey">NAMEDKEY</a>]</p>
+<p>
+Ryan finally attempts to play some video through the service. By virtue of the secure connection, the video service provider is able to make content authorization decisions that are tailored to the security capabilities of the exact make, model and version of TV that Ryan has purchased, thereby ensuring that the content providers security requirements are met in respect of the specific content requested. Ryan's devices send encrypted messages about quality of service and watching behavior to the video service provider. [<a href="#namedkey">NAMEDKEY</a> | <a href="#keycall">KEYCALL</a> | <a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#mac">MAC</a> | <a href="#wrap">WRAP</a> | <a href="#encrypt">ENCRYPT</a>]</p>
+</div>
<div id="data-integrity" class="section">
<h3>3.3. Code Sanctity and Bandwidth Saver</h3>
- <p>A major social networking site wishes to optimize website performance by storing JavaScript and other resources in local storage, preventing a needless server roundrip. The social network site wishes to verify that these resources have not been tampered with; the service uses <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> to store assets for their web pages, notably JavaScript. Their threat model is such that the social networking site implicitly trusts the HTTP connection (which uses TLS), the browser, and the HTTP cache, but cannot vouch for localStorage or IndexedDB. Let us take the case of a couple who have gone from being "In a Relationship" to "It's Complicated." John Doe uses the social networking site often, while Jane Doe, a JavaScript programmer, packs her bags to move out of the apartment.
+ <p>A major social networking site wishes to optimize website performance by storing JavaScript and other resources in local storage, preventing a needless server roundrip. The social network site wishes to verify that these resources have not been tampered with; the service uses <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> to store assets for their web pages, notably JavaScript. Their threat model is such that the social networking site implicitly trusts the HTTP connection (which uses <a href="#TLS">TLS</a>), the browser, and the HTTP cache, but cannot vouch for <a href="#localStorage"><code>localStorage</code></a> or <a href="#IndexedDB"><code>IndexedDB</code></a>. Let us take the case of a couple who have gone from being "In a Relationship" to "It's Complicated." John Doe uses the social networking site often, while Jane Doe, a JavaScript programmer, packs her bags to move out of the apartment.</p>
<div class="example"><div class="exampleHeader">Example</div>
<p>This illustrates a worst case scenario, in which <code>localStorage</code> is compromised by a malicious user. Normally, the social networking site deploys code of the sort below, which John Doe's browser runs everytime he logs into the social networking site.</p>
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
@@ -298,10 +342,8 @@
</span>
bufferData = createArrayBufferView(src);
- var digest = window.crypto.createDigester("SHA-256");
- digest.init();
- digest.processData(bufferData);
- digest.complete();
+ var digest = window.crypto.digest("SHA-256", bufferData);
+ digest.finish();
digest.oncomplete = function(e)
{
if(e.target.result === src_hash)
@@ -318,17 +360,20 @@
</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 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 class="note"><div class="noteHeader">Note</div><p>The conversion to an <a href="#TypedArrays"><code>ArrayBufferView</code></a> 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="#digest">DIGEST</a> | <a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a>]</p>
+<p>Since their threat model trusts the network layer (which includes <a href="#TLS">TLS</a>, and a distributed web cache not entirely on their own servers) but mistrusts the user's machine to store code via <a href="#localStorage"><code>localStorage</code></a> and <a href="#IndexedDB"><code>IndexedDB</code></a> the <a href="#WebCrypto">WebCrypto API</a> offers mitigations:</p>
+<ol>
+ <li><p>As in the example above, the social network can generate a digest of the material extracted from the client storage, and compare this to a pristine version of the digest that the social networking site makes available to the client. If the two digests match, the code is deemed safe. [<a href="#digest">DIGEST</a>]</p></li>
+ <li><p>They can improve on the model above by "signing with an HMAC" (or "signed hash") and then verifying the HMAC. This model offers one level more robustness, since the verification occurs within the WebCrypto API, as opposed to within the application. [<a href="#sign">SIGN</a> | <a href="#hmac">HMAC</a> | <a href="#verify">VERIFY</a>]</p></li>
+</ol>
</div>
- <div id="encrypt" class="section">
- <h3>3.4. Fostering Encrypted Communications</h3>
- <p>Tantek wishes to communicate with Ryan securely. Moreover, Tantek wishes to use an email web application (EWA) provided by a third party, which is a web site that allows users who have accounts to set up email accounts of their own choosing -- that is, users can enter in existing POP/IMAP/SMTP username and password credentials, or simply use an email address provided by the EWA.</p>
- <p>Ryan provides a PGP key on his website, encoded in the relevant conventions. For instance, he uses microformats where relevant, and follows the common practice of including a Base64 "blob" that represents his public key.</p>
+ <div id="encryptedWebMail" class="section">
+ <h3>3.4. Encrypted Communications via Webmail</h3>
+ <p>Tantek wishes to communicate with Ryan securely. Moreover, Tantek wishes to use an email web application (EWA) provided by a third party, which is a web site that allows users who have accounts to set up email accounts of their own choosing -- that is, users can enter in existing POP/IMAP/SMTP username and password credentials, or simply use an email address provided by the EWA at its own address. The EWA serves to send messages, as well as provide a message store available from anywhere. It allows for the possibility of sending encrypted messages.</p>
+ <p>Ryan provides a PGP key on his website, encoded in the relevant conventions. For instance, he uses <a href="#microformats">microformats</a> where relevant, and follows the common practice of including a Base64 text string that represents his public key.</p>
<div class="example"><div class="exampleHeader">Example</div>
- <p>Ryan uses the hCard format to encapsulate contact information with some semantic annotation within the markup of his webpage. Within the hCard, he does something like this:</p>
+ <p>Ryan uses the <a href="#hcard">hCard</a> format to encapsulate contact information with some semantic annotation within the markup of his webpage. Within the <a href="#hcard">hCard</a>, he does 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="key">
@@ -343,32 +388,118 @@
</code></pre></div></div>
<p>The ellipsis have been added for brevity.</p>
</div>
-<p>Logging on to EWA, Tantek may find UI that prompts him to enter in Ryan's hCard path. Tantek does so, and EWA then begins the process of importing Ryan's PGP key. In order to do so, it must first "scrub" the key format to be in one of the accepted import formats of the WebCrypto API.</p>
+<p>Logging on to EWA, Tantek is prompted to import Ryan's contact information from his web page, and is notified that Ryan's public key will also be imported. EWA then begins the process of importing Ryan's PGP key, since it understands how to parse public keys within <a href="#hCard">hCard</a> content. In order to import the key for storage under EWA's origin, it must first "scrub" the key format to be in one of the accepted import formats of the <a href="#WebCrypto">WebCrypto API</a>.</p>
<div class="example"><div class="exampleHeader">Example</div>
-<p>// TODO Enter sample code for importing public key.</p>
-</div>
+<p>Here, the Contacts API [cf. <a href="#MozillaContacts">Mozilla</a>][cf. <a href="#GoogleContacts">Google</a>][cf. <a href="#DAPContacts">DAP</a>] could be used to procure Ryan's contact information, and can be one way of importing the key for use by an application such as EWA. Due the same origin policy [cf. <a href="#HTML">HTML</a>], EWA must import the key, so that operations conducted with it fall under the domain of EWA. Assume this importing is done, and convert the key to <a href="#JWK">JSON Web Key</a> format, which the <a href="#WebCrypto">WebCrypto API</a> accepts if converted to octets.</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">/**
+ 1. First convert the PGP key format into an "importable" format by the WebCrypto API; assume "keyString" is the PGP format
+ Utility functions are assumed here as well.
+ 2. Import the key using the WebCrypto API
+ **/</span>
+
+var alg = "RSA";
+
+var jwkKey = convertToJWK(keyString, alg);
+
+var jwkKeyObject = JSON.parse(jwkKey);
+
+<span class="comment">// Convert to ArrayBufferView</span>
+var octetsKey = mByteArray(jwkKey);
+
+
+var importer = window.crypto.importKey("jwk", octetsKey, "RSAES-PKCS1-v1_5", false, ["encrypt", "verify"]);
+
+importer.oncomplete() = function(evt){
+ var keyImported = evt.target.result;
+
+ <span class="comment">/**
+ 1. Store the new object keyImported in IndexedDB
+ 2. The Key ID used to store the public key may be Ryan's contact
+ 3. Or it could be jkwKeyObject.kid
+ **/</span>
+}
+</code></pre></div></div>
+</div>
+<p>Following the key import and storage sequence, the key now serves as a key within the origin of EWA. EWA can then offer Tantek the option of encrypting messages to Ryan, which may follow the pattern below:</p>
+<ol>
+ <li>Tantek composes a message that he wishes to send only to Ryan.</li>
+ <li>EWA generates a symmetric key on Tantek's behalf, and uses Ryan's public key, just imported, to wrap that key. [<a href="#derive-sym">DERIVE-SYM</a> | <a href="#keycall">KEYCALL</a> | <a href="#wrap">WRAP</a>].</li>
+ <li>EWA then signs the encrypted message and wrapped key, and sends them from Tantek's email account on Tantek's behalf [<a href="#sign">SIGN</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a>].</li>
+ <li>Ryan also logs into EWA. Separately, he has also imported Tantek's public key to EWA using a similar mechanism that Ryan did. In this case, as long as Ryan has Tantek's public key, he does not strictly need to log into the same EWA as Tantek does; instead, Ryan may choose another email web application with a different origin, but with similar functionality, such that the public key is imported to be used within the origin of the web application. Ryan receives the message, verifies that it is indeed from Tantek, decrypts and reads the message using his corresponding private key. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a>].</li>
+</ol>
+<div class="note"><div class="noteHeader">Note</div><p>The use case above contains some risk; unless the source and provenance of keys are understood and trusted, the model above for "across the web" key importing lends itself to abuse by malicious users.</p></div>
</div>
<div id="realtime-messaging" class="section">
<h3>3.5. Off The Record Real Time Messaging</h3>
- <p>David and Nadim wish to have an "Off The Record" chat in real time, completely between them, and in text, including the ability to share digital data such as photographs. They log on to a chat server, and connect to each other's machines directly. The server merely serves up the UI for the chat client, and does not log their conversation (and in fact, cannot). David and Nadim need to:</p>
- <ul>
- <li><p>Be assured that they are who they claim they are. [<a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#decrypt">DECRYPT</a> | <a href="#decrypt-pki">DECRYPT-PKI</a> | <a href="#encrypt">ENCRYPT</a> | <a href="#encrypt-pki">ENCRYPT-PKI</a>] </p></li>
- <li><p>Be assured that during a conversation, messages sent back and forth are unmodified. [<a href="#encrypt">ENCRYPT</a> | <a href="#decrypt">DECRYPT</a>] </p></li>
- <li><p>Be assured that after the conversation, the contents of the conversation cannot be determined. [ENCRYPT-PKI][DECRYPT-PKI] </p></li>
- </ul>
-
+ <p>David and Nadim wish to have an "Off The Record" chat in real time, completely between them, primarily using text, as well as the ability to share digital data such as photographs. They log on to a chat server, and connect to each other's machines directly. The server merely serves up the UI for the chat client, and does not log their conversation (and in fact, cannot). The respective web pages on David and Nadim's browsers may use WebSockets and the WebCrypto API to </p>
+ <ol>
+ <li><p>The generation of assymetric keys for David and Nadim respectively, such that both get public and private keys. [<a href="#derive">DERIVE</a>]</p></li>
+ <li><p>A key exchange, so that David and Nadim get each other's public keys. It is conceivable that using the WebCrypto API the chat application can enable David and Nadim to use a Diffie-Hellman key exchange, or a mechanism such as SIGMA [cf.<a href="#OTR">OTR</a>] over <code>WebSocket</code>s [cf. <a href="#HTML">HTML</a>]. The key exchange which accompanies message exchanges involves the generation of cryptographically secure random numbers. [<a href="#random">RANDOM</a> | <a href="#keyex">KEYEX</a> | <a href="#keyex-dh">KEYEX-DH</a>]</p></li>
+ <li><p>David or Nadim may now compose a message to each other. Each message exchange involves authentication, message authentication codes, further key derivation, and further key exchanges. [<a href="#sign">SIGN</a> | <a href="#verify">VERIFY</a> | <a href="#mac">MAC</a> | <a href="#random">RANDOM</a> | <a href="#derive">DERIVE</a> | <a href="#keyex">KEYEX</a> | <a href="#keyex-dh">KEYEX-DH</a>] </p></li>
+ </ol>
+ <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>This use case needs additional details.</p></div>
</div>
<div id="savemystuff" class="section">
<h3>3.6. Documents In the Cloud</h3>
- <p>Vijay wishes to confidentially store certain documents, including photos, music, pages from the novel he is working on, and notes about his employer using a web service that he pays a monthly subscription to for such confidential storage. He can drag and drop content from his laptop onto a web page of the service, and it automatically stores it in an encrypted manner. Vijay can do the following:</p>
+ <p>Vijay wishes to confidentially store certain documents of various file types using a web service that he pays a monthly subscription to for such confidential storage. The confidential storage web application (abbreviated "SWA") makes the claim that all storage is encrypted, and that even it cannot access the contents of what a user stores. He can drag and drop content from his laptop onto a web page of the service, and it automatically encrypts it and stores it in an encrypted manner. Vijay can do the following:</p>
<ol>
- <li><p>Log on to the service using his credentials; after the service determines that Vijay is using his primary browser, which he will use to access the service subsequently, it generates encryption keys. [<a href="#derive">DERIVE</a> | <a href="#derive-pki">DERIVE-PKI</a>] </p></li>
- <li><p>Drag over content from his underlying file system that he wishes to store. [<a href="#encrypt-pki">ENCRYPT-PKI</a>] </p></li>
- <li><p>Store that content on the server, with the assurance that it is stored there in a way that is virtually undecipherable to third-parties, including employees of the service in question.</p></li>
- <li><p>Later, Vijay can retrieve the content, and save it back to his local file system. [<a href="#decrypt-pki">DECRYPT-PKI</a>] </p></li>
+ <li><p>Log on to the service using his credentials; after the service determines that Vijay is using his primary browser, which he will use to access the service subsequently, it generates both signature and encryption key pairs. Derivation may be similar to the <a href="#banking">banking use case</a>. [<a href="#derive-assym">DERIVE-ASSYM</a> | <a href="keyex-dh">KEYEX-DH</a> | <a href="#verify">VERIFY</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a> | <a href="#sign">SIGN</a>] </p></li>
+ <li><p>Drag over content from his underlying file system that he wishes to store. The SWA encrypts the content, and uploads it. It may make multipart cryptographic operations on a given file, and it may also "chunk upload" large content, depending on file-size. [<a href="#sign">SIGN</a> | <a href="#hmac">HMAC</a> | <a href="#derive-sym">DERIVE-SYM</a> | <a href="#encrypt-sym">ENCRYPT-SYM</a> | <a href="#keycall">KEYCALL</a> | <a href="#wrap">WRAP</a>] </p>
+<div class="example"><div class="exampleHeader">Example</div>
+<p>Multipart cryptographic operations can be performed with the same key.</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">// TODO: Demonstrate multi-part cryptographic operations</span>
+</code></pre></div></div>
+</div>
+</li>
+
+ <li><p>Store that content on the server, with the assurance that it is stored there in a way that is virtually undecipherable to third-parties, including those running the SWA.</p></li>
+ <li><p>Later, Vijay can retrieve the content, and save it back to his local file system. He has the assurance that the content has not been tampered with since it was stored, and that it in fact is from SWA. [<a href="#keycall">KEYCALL</a> | <a href="#verify">VERIFY</a> | <a href="#hmac">HMAC</a> | <a href="#unwrap">UNWRAP</a> | <a href="#decrypt-sym">DECRYPT-SYM</a>] </p></li>
</ol>
</div>
</div>
+ <div id="references" class="section">
+ <h2>4. References</h2>
+<dl class="bibliography">
+ <dt id="WebCrypto">Web Cryptography API</dt>
+ <dd><cite><a href="http://dvcs.w3.org/hg/webcrypto-api/">Web Cryptography API</a></cite>, D. Dahl, R. Sleevi. W3C</dd>
+ <dt id="KeyDiscovery">WebCrypto Key Discovery API</dt>
+ <dd><cite><a href="http://dvcs.w3.org/hg/webcrypto-keydiscovery">WebCrypto Key Discovery</a></cite>, M. Watson. W3C</dd>
+ <dt id="localStorage">Web Storage</dt>
+ <dd><cite><a href="http://dev.w3.org/html5/webstorage/">Web Storage</a></cite>, I. Hickson. W3C</dd>
+ <dt id="IndexedDB">IndexedDB</dt>
+ <dd><cite><a href="http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html">Indexed Database API</a></cite>, N. Mehta, J. Sicking, E. Graff, A. Popescu, J. Orlow. W3C</dd>
+ <dt id="TypedArray">Typed Array Specification</dt>
+ <dd><cite><a href="http://www.khronos.org/registry/typedarray/specs/latest/">Typed Array Specification, Editor's Draft</a></cite>, D. Herman, K. Russell. W3C</dd>
+ <dt id="TLS">TLS</dt>
+ <dd><cite><a href="http://tools.ietf.org/html/rfc5246">The Transport Layer Security (TLS) Protocol</a></cite>, T. Dierks, E. Rescorla. W3C</dd>
+ <dt id="OTR">OTR</dt>
+ <dd><cite><a href="http://www.cypherpunks.ca/otr/Protocol-v3-4.0.0.html">Off-the-Record Messaging Protocol version 3</a></cite>, cypherpunks.ca</dd>
+ <dt id="JOSE">JOSE WG</dt>
+ <dd><cite><a href="https://tools.ietf.org/wg/jose/">The JOSE (JavaScript Object Signing and Encryption) WG</a></cite>, IETF</dd>
+ <dt id="microformats">Microformats</dt>
+ <dd><cite><a href="http://www.microformats.org/">Microformats</a></cite>, microformats.org</dd>
+ <dt id="hcard">hCard</dt>
+ <dd><cite><a href="http://microformats.org/wiki/hcard">hCard</a></cite>, T. Celik, B. Suda, microformats.org</dd>
+ <dt id="keyexamples">Microformats Key Examples</dt>
+ <dd><cite><a href="http://microformats.org/wiki/key-examples">Key Examples</a></cite>, T. Celik, microformats.org</dd>
+ <dt id="JWK">JSON Web Key</dt>
+ <dd><cite><a href="https://datatracker.ietf.org/doc/draft-ietf-jose-json-web-key/">JSON Web Key (JWK) draft-ietf-jose-json-web-key-07</a></cite>, M. Jones, IETF</dd>
+ <dt id="GoogleContacts">Google Contacts API</dt>
+ <dd><cite><a href="https://developers.google.com/google-apps/contacts/v3/">Google Contacts API v. 3.0</a></cite>, Google</dd>
+ <dt id="MozillaContacts">Mozilla Contacts API</dt>
+ <dd><cite><a href="https://wiki.mozilla.org/WebAPI/ContactsAPI">Mozilla Proposed Contacts API</a></cite>, Mozilla</dd>
+ <dt id="DAPContacts">Pick Contacts Intent</dt>
+ <dd><cite><a href="http://www.w3.org/TR/contacts-api/">Pick Contacts Intent</a></cite>, R. Tibbett, R. Berjon, W3C</dd>
+ <dt id="HTML">HTML</dt>
+ <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/network.html">HTML Living Standard</a></cite>, WHATWG</dd>
+</dl>
+
+
+
+
+ </div>
</div>
</body>