Privacy/Features/DOMCryptAPISpec/0.1

From MozillaWiki
Jump to: navigation, search

DOMCrypt 'window.cipher' Specification

DRAFT
Version 0.1
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, sign, verify, hash data ( via a variety of algorithms ) as well as the discovery and persistence of a contact's public key.

Terms

DOMCrypt
A generic label for the entire crypto API originating in the open source project 'DOMCrypt'
window.cipher
The proposed window property name for this API
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
cipherAddressbook or Addressbook
A JSON object containing a user's contact's public key. This is also a term used to avoid such cryptography lingo as 'key', 'key ring'
AddressbookEntry
A JSON object that contains a contact's public key. The addressbook and AddressbookEntry nomenclature is used to simplify the way refer to public keys and key rings. e.g.: I need Natasha's AddressbookEntry in order to send her a private message (and she will need my AddressbookEntry to reply).
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", 
   }
cipherAddressbook

The JSON object containing a user's contact's Public Keys 

  [
    {
      "id"      : <a unique id, e.g: an email address>,
      "handle"  : "natasha",
      "domain"  : "domcrypt.org",
      "pubKey"  : <BASE64 ENCODED PUBLIC KEY>,
      "created" : 1305140629979,
    },
  ]

Browser Window property

window.cipher

All web pages will have this property. 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 ) { } ) {  },

     // get the JSON cipherAddressbook
     get addressbook() {},
     
     // make changes to the addressbook
     saveAddressbook: function (JSONObject, function callback ( addresssbook ) { }) {  }
   },
   
   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: {
     SHA256: 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 ){ }) { }
   }
 }

PublicKey discovery

A user discovers public keys (addressbook entries) in the markup of a web page as a meta tag. The browser alerts the user that an 'addressbookEntry' has been published. the user then has the option to save it to the cipherAddressbook

addressbookEntry
<meta name="addressbook-entry" pubkey="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1vW1laRyBkIfdeB2GQT+rz4dRwYUMtQJQ4Z8/QJCQj5qFuYKqcUn+8UssedWMjygRME1Eamcv5X5HLvphYMaRufk4PvKXLNq0Xh7cmNLcpQT639v+RjWpvHNWsdtYfd80nKCf1S46TlbH2/aw/+tcdLdj8MOTDtzII2oCcXU8B8PXNf49rcNMv8KagjC6LMQDrgvmZ56T1J3wHtQAH/QXGvh4WjQc2sWC/V+2xGkQL4+4yeP7STJBQXKmmqanExsqmwii1rV0Rd2GQnJRaSj+56HMDbZkLnZsxJExul5vu6ec+nBfACxWDMVCeVWbYxBpfURgC5nDsznkgT5VhXOJwIDAQAB",

           handle="natasha",
           domain="droplettr.com"
           date="1298322911812",
           algorithm="AES_256_CBC">

</meta>

Notes

window.mozCipher is the proposed experimental, mozilla-prefixed window property name for this API
The implementation should allow users to whitelist domains and pages which are authorized to use this API - especially in regards to creating keypairs and getting the user's addressbook

References


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