Privacy/Features/DOMCryptAPISpec/0.2

From MozillaWiki
Jump to: navigation, search

DOMCrypt 'window.mozCrypto' Specification

DRAFT
Version 0.2PRE This draft is under heavy development right now. WebIDL is being added, v0.2 will be posted 2011-06-06
Updated 2011-06-03
Author
David Dahl <ddahl@mozilla.com>

Introduction

This document describes a proposed Javascript Cryptography API available in web browsers to allow any web page script the ability to generate asymmetric key pairs, encrypt, decrypt (asymmetric and symmetric crypto), sign, verify, HMAC, and hash data ( via a variety of algorithms ).

Terms

DOMCrypt
A generic label for the entire crypto API originating in the open source project 'DOMCrypt'
window.cipher
The now deprecated proposed window property name for this API
window.mozCrypto
The temporary window property used to distinguish this new API from the current window.crypto property. The consensus so far is to add this API to the window.crypto property
cipher Configuration
A JSON object that stores the user's private key and public key
Key Pair
An asymmetric pair of encryption keys. A Public Key which is used by others to encrypted data for you to decrypt with your Private Key
Public Key
The public half of an asymmetric key pair
Private Key
The private half of an asymmetric key pair
Symmetric Key
an encryption key used for symmetric encryption

Objects

Note: Object definitions below are written in JSON.

cipherConfiguration

A JSON Object which labels the Key Pairs, staring with a "default" Key Pair. This allows for multiple Key Pairs in the future. 

 {
   "default": {
     "created"   : 1305140629979,
     "privKey"   : <BASE64 ENCODEDED PRIVATE KEY>,
     "pubKey"    : <BASE64 ENCODEDED PUBLIC KEY>,
     "salt"      : <ENCODED or ENCRYPTED Salt>,
     "iv"        : <ENCODED or ENCRYPTED IV>,
     "algorithm" : "AES_256_CBC", 
   }


Browser Window property

window.mozCrypto

All windows will have this property (in the current implementation) for the time being as this API is hashed out.

The property is namespaced in order to provide future capabilities. The current design is asynchronous and looks like this: 

 
{ 
   pk: {
     // Public Key API
     
     set algorithm(algorithm){ },
     
     get algorithm(){ },

     // Generate a keypair and then execute the callback function
     generateKeypair: function ( function callback( aPublicKey ) { } ) {  },

     // encrypt a plainText
     encrypt: function ( plainText, publicKey, function callback (cipherMessageObject) ) {  } ) {  },

     // decrypt a cipherMessage
     decrypt: function ( cipherMessageObject, function callback ( plainText ) { } ) {  },      

     // sign a message
     sign: function ( plainText, function callback ( signature ) { } ) {  },      

     // verify a signature
     verify: function ( signature, plainText, function callback ( boolean ) { } ) {  },
   },
   
   sym: {
     // Symmetric Crypto API

     get algorithm(),  

     set algorithm(algorithm),
     
     // create a new symmetric key
     generateKey: function (function callback ( key ){ }) {  },
     
     // encrypt some data
     encrypt: function (plainText, key, function callback( cipherText ) { }) {  },
     
     // decrypt some data
     decrypt: function (cipherText, key, function callback( plainText ) { }) {  },
   },

   hash: {
     set algorithm( algorithm ) { },

     get algorithm( ) { },

     createHash: function (function callback (hash) {}) {  }
   },

   hmac: {
     get algorithm() { },

     set algorithm(algorithm){ },

     createHMAC: function (plaintext, key, function callback( mac ){ }) {  },

     verifyHMAC: function(plaintext, key, receivedMac, function callback( booleanVerified ){ }) { }
   }
 }


Notes

The implementation should allow users to whitelist domains and pages which are authorized to use this API - much like how the Geolocation API asks the user for permission to get location data

References


Retrieved from "https://wiki.mozilla.org/index.php?title=Privacy/Features/DOMCryptAPISpec/0.2&oldid=315385"