DOMCrypt API Update 2011-06-01

2011/06/01 — 6 Comments

There has been so much written and discussed online and off about privacy, user control and identity lately. This dovetails nicely with the draft spec for DOMCrypt as a proposed Crypto API for web browsers.


DOMCrypt was discussed on the WHATWG mailing list last week, see:

I have summarized the discussion here:

Out of these discussions, I have updated the Firefox feature page:

A Use-cases page was created, see:

For anyone unfamiliar with DOMCrypt, this proposal in a nutshell says:

Privacy and user control on the web is of utter importance. Tracking, unauthorized user data aggregation and personal information breaches are becoming so commonplace you see a new headline almost daily. (It seems).

We need crypto APIs in browsers to allow developers to create more secure communications tools and web applications that don’t have to implicitly trust the server.

The DOMCrypt API is a good start, and more feedback and discussion will really help round out how all of this should work – as well as how it can work in any browser that will support such an API.

This API will provide each web browser window with a ‘cipher’ property[1] that facilitates:

  • asymmetric encryption key pair generation
  • public key encryption
  • public key decryption
  • symmetric encryption
  • signature generation
  • signature verification
  • hashing
  • easy public key discovery via meta tags or an ‘addressbookentry’ tag

[1] There is a bit of discussion around adding this API to window.navigator or consolidation within window.crypto

I have created a Firefox extension that implements most of the above, and am working on an experimental patch that integrates this API into Firefox.

The project originated in an extension I wrote, the home page is here:

The source code for the extension is here:

The Mozilla bugs are here:

You can test the API by installing the extension hosted at and, and going to

The API:

window.cipher = {
 // Public Key API
 pk: {
   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, 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 ) { }) {  }

  // Symmetric Crypto API
  sym: {
  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 ) { }) {  },

  // hashing
  hash: {
    SHA256: function (function callback (hash){}) {  }

I am in the process of posting this proposed spec for review by the W3C webapps list and TC39. Your feedback and / or help with this effort will be greatly appreciated.

6 responses to DOMCrypt API Update 2011-06-01


    Is there any case to be made for including bcrypt? I’m not sure to what degree this would be used for password hashing.


      As far as Firefox is concerned, NSS has many APIs for hashing – I’m not sure the rigor required to bring in an external library will be worth the effort to bring bcrypt into Gecko


    Does this require that the whole plain/cyphertext be known at the initial en/decyrpt call (and therefore have the whole thing in memory at once)?

    This API appears to be stateless (in that I can’t create an object holding, say, the private key and use it as a black box to repeatedly encrypt something over a long session)? This isn’t necessarily bad, just wanted to check that this was a specific design decision.

    Your API documentation doesn’t seem to match the demo (e.g. pk.encrypt has a pubkey parameter).

    The demo (and, as far as I can tell, the code on github) appears to not know about addressbooks. I must admit that’s about my knowledge too – well, I guess I know they’re JSON, just not what fields they have or what they’re used for 🙂

    I think I must be crazy, I find xpidl easier to read 😉


      yes. the entire text must be known – it would be prudent to build an array of jobs if you wanted to encrypt or decrypt a lot of data. As far as the implementation is concerned – you might be onto a weakness here and it would be prudent to explore how to handle streams of data like HTTPS. I am using NSS as it were.
      The stateless aspect was not a design decision – this does give me pause, sort of. I was aiming at encrypting perhaps 1MB per method call just as a first pass. That takes maybe 0.2 seconds on my new 8 core processor. Perhaps we should add a new API for streams?
      As far as the API docs, it looks like I copy and pasted from something that was wrong. I will fix that once I get a little sleep. Thanks! The demo should show a notification bar when it encounters an addressbook-entry meta tag. That worked last time I tested it. See:
      The JSON for the addressbook entry is built in this code snippet:
      I will be updating the spec with WebIDL notation for all of the objects involved.


    In most cases the weakest link in protecting content is the user password. For key generation, or password authentication hashes, you should be using key strengthening techniques such as PBKDF2 to limit brute force attacks (especially where data is stored on the server out of users’ control). Preferably offering ‘slow’ hashes such as bcrypt rather than speed optimised general purpose hashes.

    See for example:

    I think this effort is a really good thing, but please ensure your API makes it easy to follow current best practice, otherwise we only embed outdated methods among web developers. Where data are stored online protected by user password, brute-force attacks are very possible.

    (PS: I’d ideally like access to primitives which makes it possible to do authentication protocols such as SRP, but recognise that’s probably asking too much.)

Trackbacks and Pingbacks:

  1. DOMCrypt: Adding Encryption to the Browser | FunctionSource Development - June 8, 2011

    […] in a security strategy. That’s why Mozilla’s David Dahl is proposing the addition of client-side JavaScript crypto APIs into the browser. Specifically, David proposes the addition of a “crypto” object that […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s