Index: Overview-WebCryptoAPI.xml
===================================================================
RCS file: /w3ccvs/WWW/2012/webcrypto/WebCryptoAPI/Overview-WebCryptoAPI.xml,v
retrieving revision 1.44
diff -r1.44 Overview-WebCryptoAPI.xml
3078c3078,3321
<    
---
>       <div id="examples-section" class="section">
>         <h2>JavaScript Example Code</h2>
>         <div id="examples-introduction" class="section">
>           <h3>Introduction</h3>
>           <p>
>             The Web Cryptography API operates on ArrayBufferView arguments and enables:
>           </p>
>           <p>
>             <ol>
>               <li>Signing</li>
>               <li>Encryption</li>
>               <li>Digests</li>
>               <li>Verification</li>
>               <li>Decryption</li>
>             </ol>
>           </p>
>           <p>
>             Such ArrayBufferView arguments can be generated as part of application data
>             or be obtained from ancillary sources, such as the underlying file system or
>             web storage.
>           </p>
>           <p>
>             If using the underlying file system, data can be read asynchronously as an
>             ArrayBuffer using the File API and the resulting ArrayBuffer can be converted
>             to an ArrayBufferView.
>           </p>
>           <p>
>             The examples in this section presume a secret message which is converted to
>             an ArrayBufferView, although these examples can also apply to ArrayBufferView
>             payloads from the underlying file system or web storage.
>           </p>
>         </div>
>         <div id="examples-initial-data" class="section">
>           <h3>(Some initial data to process)</h3>
>         <x:codeblock language="ecmascript">
> var secretMessage = "53kr3t M355ag3 for A1ic3";
> 
> // Convert this to an ArrayBufferView with assumed utility function 'toArrayBufferView'
> 
> var myData = toArrayBufferView(secretMessage); // TODO: add a 'utility function' section
>         </x:codeblock>
>         </div>
>         <div id="examples-signing" class="section">
>           <h3>Generate a signing key pair, sign some data</h3>
>         
>         <x:codeblock language="ecmascript">
> // Algorithm Object
> var algorithmKeyGen = {
>   name: "RSASSA-PKCS1-v1_5",
>   // AlgorithmParams
>   params: {
>     modulusLength: 2048,
>     publicExponent: 65537
>   }
> };
> 
> var algorithmSign = {
>   name: "RSA-256",
>   // AlgorithmParams
>   params: {
>     // null?
>   }
> };
> 
> var keyGen = window.crypto.createKeyGenerator(algorithmKeyGen,
>                                               false, // temporary
>                                               false, // extractable
>                                               ["sign"]);
> 
> keyGen.oncomplete = function onKeyGenComplete(event)
> {
>   // The keyGen operation is complete
>   console.log("Key ID: " + event.target.key.id);
> 
>   // create a "signer" CryptoOperation object
>   var signer = window.crypto.createSigner(algorithmSign, event.target.key);
>   signer.oncomplete = function signer_oncomplete(event)
>   {
>     console.log("The signer CryptoOperation is finished, the signature is: " +
>                 event.target.result);
>   };
>   signer.onerror = function signer_onerror(event)
>   {
>     console.log("The signer CryptoOperation failed");
>   };
> 
>   signer.oninit = function signer_oninit(event)
>   {
>     signer.processData(myData);
>   };
> 
>   signer.progress = function signer_onprogress(event)
>   {
>     signer.complete();
>   };
> 
>   // Sign some data:
>   signer.init();
> };
> 
> keyGen.onerror = function onKeyGenError(event)
> {
>   console.error("KeyGen error: " + event.target.error); // is this correct? event.target.error?
> };
> 
> // Generate the keypair, the key object is available inside the oncomplete handler
> keyGen.generate();
> 
>         </x:codeblock>
>         </div>
>         <div id="examples-key-storage" class="section">
>           <h3>Key Storage</h3>
>         <x:codeblock language="ecmascript">
> var encryptionKey = window.keys.getKeyById("one-of-my-crypto-key-ids-for-this-origin");
> 
> // This key is no longer needed, I should remove it:
> window.keys.removeKeyById(encryptionKey.id);
> 
> var otherEncryptionKey = window.keys.getKeyById("another-crypto-key-id-for-this-origin");
>         </x:codeblock>
>         </div>
>         <div id="examples-pgp-style-encryption" class="section">
>           <h3>PGP Style Encryption</h3>
>         <x:codeblock language="ecmascript">
> // Assumed variables in this scope:
> // var secretMessageToAlice = anArrayBufferView;
> // var alicePubKey = aJWKFormattedPublicKey;
> 
> var aesAlgorithmKeyGen = {
>   name: "AES-CBC",
>   params: {
>     length: 128
>   }
> };
> 
> var aesAlgorithmEncrypt = {
>   name: "AES-CBC",
>   params: {
>     iv: window.crypto.getRandomValues(myArrayBufferView)
>   }
> };
> 
> // Create a keygenerator to produce a one-time-use AES key to encrypt some data
> var cryptoKeyGen = window.crypto.createKeyGenerator(aesAlgorithmKeyGen,
>                                                     false, // temporary
>                                                     false, // extractable
>                                                     ["encrypt"]);
> 
> cryptoKeyGen.oncomplete = function ckg_onComplete(event)
> {
>   // Optionally get the keyId and key via the id:
>   // var aesKeyId = event.target.key.id; // Key id
>   // var aesKey = window.crypto.keys.getKeyByKeyId(aesKeyId);
> 
>   var aesKey = event.target.key;
> 
>   // Import Alice's RSAES-PKCS1-v1_5 Public Key to be used to wrap this AES
>   var alicePubKeyAlg = {
>     name: "RSAES-PKCS1-v1_5",
>     // AlgorithmParams
>     params: {
>     }
>   };
> 
>   var publicKeyImporter = window.crypto.createKeyImporter("jwk",
>                                                           alicePublicKey, // ArrayBufferView
>                                                           alicePubKeyAlg,
>                                                           false,
>                                                           true,
>                                                           ["encrypt"]);
> 
>   publicKeyImporter.oncomplete = function pki_oncomplete(event)
>   {
>     var alicePubKey = event.target.result;
> 
>     var pubKeyCryptoOp = window.crypto.createEncrypter(alicePubKeyAlg, alicePubKey);
> 
>     var aesSymmetricCryptoOp = window.crypto.createEncrypter(aesAlgorithmEncrypt, aesKey);
> 
>     aesSymmetricCryptoOp.oncomplete = function aes_oncomplete(event)
>     {
>       // the message have been encrypted
>       var cipherMessage = event.target.result; // ArrayBufferView
> 
>       // Now, we need to wrap the AES key with Alice's public key
>       pubKeyCryptoOp.oncomplete = function pkco_oncomplete(event)
>       {
>         var wrappingKey = event.target.result;
>         // Now we can send the cipherMessage and wrappingKey to Alice
>         // sendMessage(cipherMessage, wrappingKey); // Ficticious application function
>       };
>       // Begin key wrapping operation
>       pubKeyCryptoOp.oninit = function pkco_oninit(event)
>       {
>         // Provide the aesKey...
>         // TODO: Key needs to be exported first to convert to an ArrayBufferView
>         // var aesKeyAsBuffer = keyToArrayBufferView(aesKey);
>         pubKeyCryptoOp.processData(aesKeyAsBuffer);
>       };
> 
>       pubKeyCryptoOp.onprogress = function pkci_onprogress(event)
>       {
>         pubKeyCryptoOp.complete();
>       };
> 
>       pubKeyCryptoOp.onerror = function pkci_onerror(event)
>       {
>         console.error("PublicKey wrapping operation failed");
>       };
> 
>       // Begin wrapping operation of the aesKey
>       pubKeyCryptoOp.init();
>     };
> 
>     aesSymmetricCryptoOp.oninit = function aes_oninit(event)
>     {
>       aesSymmetricCryptoOp.processData(secretMessageToAlice);
>     };
> 
>     aesSymmetricCryptoOp.onprogress = function aes_onprogress(event)
>     {
>       aesSymmetricCryptoOp.complete();
>     };
> 
>     aesSymmetricCryptoOp.onerror = function aes_onerror(event)
>     {
>       console.error("AES encryption failed");
>     };
> 
>     aesSymmetricCryptoOp.init();
>   };
> 
>   publicKeyImporter.onerror = function pki_onerror(event)
>   {
>     console.error("There was an error attempting to import a key");
>   };
>   // Everything begins here as a recipient's key must be imported into the
>   // key store to be used
>   publicKeyImporter.import();
> };
> 
>         </x:codeblock>
>       </div>
>     </div>