filled in a bit more data about callbacks/event handlers default tip
authorDavid Dahl <ddahl@mozilla.com>
Mon, 11 Feb 2013 17:10:38 -0600
changeset 10 def6e0e07e79
parent 9 3083bee93329
filled in a bit more data about callbacks/event handlers
Overview.html
highlevel-api-source.html
--- a/Overview.html	Mon Jan 28 17:54:42 2013 -0600
+++ b/Overview.html	Mon Feb 11 17:10:38 2013 -0600
@@ -48,8 +48,8 @@
                                         mailto: "ddahl@mozilla.com", 
                                         company: "Mozilla Corporation", 
                                         companyURL: "http://www.mozilla.org/"} ],
-                            publishDate: "2013-01-28",
-                            previousPublishDate:  "2013-01-25",
+                            publishDate: "2013-02-11",
+                            previousPublishDate:  "2013-01-28",
                             // edEnd:  "",
                             previousMaturity: "ED",
                             edDraftURI:   "https://dvcs.w3.org/hg/webcrypto-highlevel/raw-file/tip/Overview.html",
@@ -82,11 +82,11 @@
         <h2>Use cases</h2>
         <section>
           <h3>Security of data at rest</h3>
-          <p>An E-commerce website needs to store credit card numbers and related customer information to facilitate 1-step ordering. The site can either store this data on its own servers, making it a rich target for criminals. Another option is protecting this data with the "protect" method and decrypting later with "unprotect" during a transaction. The server stores the the key ID and uses it when appropriate. A credit card transaction is processed easily, the server does not store the credentials and the data is safely stored in the browser's LocalStorage.</p>
+          <p>An E-commerce website needs to store credit card numbers and related customer information to facilitate 1-step ordering. The site can either store this data on its own servers, making it a rich target for criminals. Another option is protecting this data with the "seal" method and decrypting later with "open" during a transaction. The server stores the the key ID and uses it when appropriate. A credit card transaction is processed easily, the server does not store the credentials and the data is more safely stored in the browser's LocalStorage without the KeyID, without which, an attacker cannot access the 'sealed' data.</p>
         </section>
         <section>
           <h3>Web-based messaging</h3>
-          <p>A web-messaging company would like to provide a private messaging feature. Users can create keypairs and share them via a link, out of band or via a text message. (Users equate public keys with an "addressbook entry", without which, no communication can take place.) After a message is composed, it is encrypted and signed, then sent to the server for delivery. No plaintext is passed to the server or retained on the client.</p>
+          <p>A web-messaging company would like to provide a private messaging feature. Users can create keypairs and share them via a link, out of band or via a text message. (The user experience of the site equates each public key with an "addressbook entry", without which, no communication can take place.) After a message is composed, it is encrypted and signed, then sent to the server for delivery. No plaintext is passed to the server or retained on the client.</p>
         </section>
     </section>
     
@@ -171,29 +171,51 @@
 
       <section>
         <h3>Highlevel interface</h3>
-
         <dl title="callback CreateKeypairSuccess = void (in DOMString publicKey)" class="idl">
+          <dt>CreateKeyPairSuccess event handler</dt>
+          <dd>Upon creation of a key pair this handler is executed. The argument, publicKey, provides the public key data. The key pair data is a JSON Web Key (JWK)</dd>
         </dl>
         <dl title="callback CreateKeypairError = void (in DOMString error)" class="idl">
+          <dt>CreateKeyPairError event handler</dt>
+          <dd>During key pair generation a platform error will fire this event handler, if defined.</dd>
         </dl>
         <dl title="callback EncryptSuccess = void (in DOMString cipherText, in DOMString keyID)" class="idl">
+          <dt>EncryptSuccess event handler</dt>
+          <dd>Upon successful encryptAndSign operation, this event handler is executed. An argument, cipherText, is provided (a JSON Web Encryption (JWE) DOMString) and the Key ID of the current user's key pair.</dd>
         </dl>
         <dl title="callback EncryptError = void (in DOMString error)" class="idl">
+          <dt>EncryptError event handler</dt>
+          <dd>During a public key encryption operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback DecryptSuccess = void (in DOMString plainText)" class="idl">
+          <dt>DecryptSuccess event handler</dt>
+          <dd>
+            Upon a successful public key decryption operation, this event handler is executed with a plainText argument.
+          </dd>
         </dl>
         <dl title="callback DecryptError = void (in DOMString error)" class="idl">
+          <dt>DecryptError event handler</dt>
+          <dd>During a public key decrypt operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback SealSuccess = void (in DOMString cipherText, in DOMString keyID)" class="idl">
+          <dt>SealSuccess event handler</dt>
+          <dd>Each time seal is called a symmetric key is generated and ued to encrypt the plaintext. Upon successful seal operation, this event handler is executed producing the id that corresponds to the underlying symmetric key generated for this operation.</dd>
         </dl>
         <dl title="callback SealError = void (in DOMString error)" class="idl">
+          <dt>SealError event handler</dt>
+          <dd>During a seal operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback OpenSuccess = void (in DOMString plainText)" class="idl">
+          <dt>OpenSuccess event handler</dt>
+          <dd>Upon successful open operation, this event handler is executed providing the plaintext result.</dd>
         </dl>
         <dl title="callback OpenError = void (in DOMString error)" class="idl">
+          <dt>OpenError event handler</dt>
+            <dd>
+              During an open operation an error will trigger this event handler.
+            </dd>
         </dl>
 
-
         <dl title="[Constructor] interface Highlevel" class="idl">
           <dt>void createKeyPair (optional in DOMString joseAlg)</dt>
           <dd>Generate a keypair</dd>
@@ -230,6 +252,7 @@
           <dt>[TreatNonCallableAsNull] attribute OpenError onOpenError</dt>
           <dd>onOpenError event handler</dd>
         </dl>
+
       </section>
       
       <section>
--- a/highlevel-api-source.html	Mon Jan 28 17:54:42 2013 -0600
+++ b/highlevel-api-source.html	Mon Feb 11 17:10:38 2013 -0600
@@ -48,8 +48,8 @@
                                         mailto: "ddahl@mozilla.com", 
                                         company: "Mozilla Corporation", 
                                         companyURL: "http://www.mozilla.org/"} ],
-                            publishDate: "2013-01-28",
-                            previousPublishDate:  "2013-01-25",
+                            publishDate: "2013-02-11",
+                            previousPublishDate:  "2013-01-28",
                             // edEnd:  "",
                             previousMaturity: "ED",
                             edDraftURI:   "https://dvcs.w3.org/hg/webcrypto-highlevel/raw-file/tip/Overview.html",
@@ -82,11 +82,11 @@
         <h2>Use cases</h2>
         <section>
           <h3>Security of data at rest</h3>
-          <p>An E-commerce website needs to store credit card numbers and related customer information to facilitate 1-step ordering. The site can either store this data on its own servers, making it a rich target for criminals. Another option is protecting this data with the "protect" method and decrypting later with "unprotect" during a transaction. The server stores the the key ID and uses it when appropriate. A credit card transaction is processed easily, the server does not store the credentials and the data is safely stored in the browser's LocalStorage.</p>
+          <p>An E-commerce website needs to store credit card numbers and related customer information to facilitate 1-step ordering. The site can either store this data on its own servers, making it a rich target for criminals. Another option is protecting this data with the "seal" method and decrypting later with "open" during a transaction. The server stores the the key ID and uses it when appropriate. A credit card transaction is processed easily, the server does not store the credentials and the data is more safely stored in the browser's LocalStorage without the KeyID, without which, an attacker cannot access the 'sealed' data.</p>
         </section>
         <section>
           <h3>Web-based messaging</h3>
-          <p>A web-messaging company would like to provide a private messaging feature. Users can create keypairs and share them via a link, out of band or via a text message. (Users equate public keys with an "addressbook entry", without which, no communication can take place.) After a message is composed, it is encrypted and signed, then sent to the server for delivery. No plaintext is passed to the server or retained on the client.</p>
+          <p>A web-messaging company would like to provide a private messaging feature. Users can create keypairs and share them via a link, out of band or via a text message. (The user experience of the site equates each public key with an "addressbook entry", without which, no communication can take place.) After a message is composed, it is encrypted and signed, then sent to the server for delivery. No plaintext is passed to the server or retained on the client.</p>
         </section>
     </section>
     
@@ -171,29 +171,51 @@
 
       <section>
         <h3>Highlevel interface</h3>
-
         <dl title="callback CreateKeypairSuccess = void (in DOMString publicKey)" class="idl">
+          <dt>CreateKeyPairSuccess event handler</dt>
+          <dd>Upon creation of a key pair this handler is executed. The argument, publicKey, provides the public key data. The key pair data is a JSON Web Key (JWK)</dd>
         </dl>
         <dl title="callback CreateKeypairError = void (in DOMString error)" class="idl">
+          <dt>CreateKeyPairError event handler</dt>
+          <dd>During key pair generation a platform error will fire this event handler, if defined.</dd>
         </dl>
         <dl title="callback EncryptSuccess = void (in DOMString cipherText, in DOMString keyID)" class="idl">
+          <dt>EncryptSuccess event handler</dt>
+          <dd>Upon successful encryptAndSign operation, this event handler is executed. An argument, cipherText, is provided (a JSON Web Encryption (JWE) DOMString) and the Key ID of the current user's key pair.</dd>
         </dl>
         <dl title="callback EncryptError = void (in DOMString error)" class="idl">
+          <dt>EncryptError event handler</dt>
+          <dd>During a public key encryption operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback DecryptSuccess = void (in DOMString plainText)" class="idl">
+          <dt>DecryptSuccess event handler</dt>
+          <dd>
+            Upon a successful public key decryption operation, this event handler is executed with a plainText argument.
+          </dd>
         </dl>
         <dl title="callback DecryptError = void (in DOMString error)" class="idl">
+          <dt>DecryptError event handler</dt>
+          <dd>During a public key decrypt operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback SealSuccess = void (in DOMString cipherText, in DOMString keyID)" class="idl">
+          <dt>SealSuccess event handler</dt>
+          <dd>Each time seal is called a symmetric key is generated and ued to encrypt the plaintext. Upon successful seal operation, this event handler is executed producing the id that corresponds to the underlying symmetric key generated for this operation.</dd>
         </dl>
         <dl title="callback SealError = void (in DOMString error)" class="idl">
+          <dt>SealError event handler</dt>
+          <dd>During a seal operation an error will trigger this event handler.</dd>
         </dl>
         <dl title="callback OpenSuccess = void (in DOMString plainText)" class="idl">
+          <dt>OpenSuccess event handler</dt>
+          <dd>Upon successful open operation, this event handler is executed providing the plaintext result.</dd>
         </dl>
         <dl title="callback OpenError = void (in DOMString error)" class="idl">
+          <dt>OpenError event handler</dt>
+            <dd>
+              During an open operation an error will trigger this event handler.
+            </dd>
         </dl>
 
-
         <dl title="[Constructor] interface Highlevel" class="idl">
           <dt>void createKeyPair (optional in DOMString joseAlg)</dt>
           <dd>Generate a keypair</dd>
@@ -230,6 +252,7 @@
           <dt>[TreatNonCallableAsNull] attribute OpenError onOpenError</dt>
           <dd>onOpenError event handler</dd>
         </dl>
+
       </section>
       
       <section>