[whatwg] window.cipher HTML crypto API draft spec

Nicholas Zakas nzakas at yahoo-inc.com
Tue May 24 10:40:13 PDT 2011

Very cool, thanks!

Followup question: is aKey in your example a string or a data structure? The reason I ask is because I'd love to generate the key on the server and then pass it back to the client for use. When I previously did some thinking about this, I was thinking of the key as a base64-encoded value, so just curious what you're using.

Thanks again,

-----Original Message-----
From: David Dahl [mailto:ddahl at mozilla.com] 
Sent: Tuesday, May 24, 2011 10:28 AM
To: Nicholas Zakas
Cc: whatwg at lists.whatwg.org; Henri Sivonen
Subject: Re: [whatwg] window.cipher HTML crypto API draft spec


Sure thing. The symmetric API would look something like this: 

cipher.sym.generateKey(function callback(aKey){})
cipher.sym.encrypt(plainText, key, function callback(cipherText){})
cipher.sym.decrypt(cipherText, key, function callback(plainText){})

--- sample code ---
function createKey() {
  cipher.sym.generateKey(function (aKey){
    XHR.post("/save-key/", {key: aKey}, function (result){
      if (result)
        alert("Success: Your key was saved.");

function saveRecord(aRecord, aKey) {
  cipher.sym.encrypt(aRecord, aKey, function (aCipherText) {
    localStorage.setItem("foo", aCipherText);

function readRecord(aID, aKey) {
  var cipherRecord = localStorage.getItem(aID);
  cipher.sym.decrypt(cipherRecord, aKey, function (plainText){

The web app would have your browser create a key, send it to the server via xhr, etc, then you can use encrypt() and decrypt() to secure your localStorage data.

I will add the symmetric API bits to the spec. The implementation is nearly already done as all of the public key encryption already uses symmetric crypto behind the scenes. I will also add this to my implementation for experimentation.



----- Original Message -----
From: "Nicholas Zakas" <nzakas at yahoo-inc.com>
To: "David Dahl" <ddahl at mozilla.com>, "Henri Sivonen" <hsivonen at iki.fi>
Cc: whatwg at lists.whatwg.org
Sent: Tuesday, May 24, 2011 12:04:42 PM
Subject: RE: [whatwg] window.cipher HTML crypto API draft spec

I'm excited to see this get some steam behind it, though I'd echo what some others have said about this being very targeted at the address book use case. The use case I'm more interested in is a bit simpler: I want to encrypt data before saving to localStorage. The key may be one that exists solely on the server.

IMHO, this is an important use case and potentially more common. I'd really like for any encryption API to enable this use case easily, and I'm having a hard time figuring if it's possible with this API. Can you share your thoughts on this (maybe some pseudo-code)?

-----Original Message-----
From: whatwg-bounces at lists.whatwg.org [mailto:whatwg-bounces at lists.whatwg.org] On Behalf Of David Dahl
Sent: Tuesday, May 24, 2011 7:48 AM
To: Henri Sivonen
Cc: whatwg at lists.whatwg.org
Subject: Re: [whatwg] window.cipher HTML crypto API draft spec

----- Original Message -----
From: "Henri Sivonen" <hsivonen at iki.fi>
To: "David Dahl" <ddahl at mozilla.com>
Cc: whatwg at lists.whatwg.org
Sent: Tuesday, May 24, 2011 2:25:53 AM
Subject: Re: [whatwg] window.cipher HTML crypto API draft spec

> It seems unfortunate that crypto is only available when a JavaScript
  program explicitly drives encryption. This means that in order to use
  crypto, the Web app has to be written in such a way that all its
  resource handling is programmed in JavaScript instead of using
  traditional browser-handled resource retrievals.

I imagine using resource retrieval would be the way to handle larger binary data decryption, and would be an amazing counterpart to this API - it also seems like a much bigger project to undertake. The emphasis on DOMCrypt is mainly on giving content developers a way to write privacy-enhanced web apps.

> Consider for example a DropBox-style service that has a browser-based UI
  but that has a design where content is encrypted on the client-side so
  that the service provider is unable to decrypt the data. In this case,
  it would make sense to be able to implement a file download by having a
  plain <a href> to an excrypted file and have the browser automatically
  decrypt it. Likewise, a service that allows the transmission of
  encrypted images should be implementable by having <img src> point
  directly to an encrypted file.

I think someone was asking about that kind of functionality during my presentation at Mozilla. Again, this would be a pretty advanced complement to this API - I would love to see something like that spec'd and implemented as well.

> I suggest adding a Content-Encoding type that tells the HTTP stack that
  the payload of a HTTP response is encrypted and needs to be decrypted
  using a key previously initialized using the JS API.

cool. I'll look into that.

- -

> On the other hand, it seems that letting Web apps generate per-user key
  pairs and letting Web apps discover if the user possesses the private
  key that decrypts a particular message is a privacy problem. Someone who
  wishes to surveil Web users could use private keys as supercookies,
  since the generated private key is most probably going to be unique to

Currently, my implementation requires the enduser to open a file from the file system in order to view the contents of the private key. It is only accessible to privileged code - content has no access to it whatsoever.

> OTOH, wiping keys along with cookies could lead to accidents.
> Is there a plan on how this will integrate into various private data
  deletion UIs in such a way that users have the option to delete keys but
  understand the implications and don't delete them accidentally?

Not yet. There no doubt will have to be a UI that helps users understand the ramifications of deleting keys, etc.

> Are all the methods that take a success callback meant to pop up a
  geolocation-style asynchronous authorization UI until the user
  perma-authorizes a site to use crypto?

It is not implemented yet, but yes, that would be the plan.
- -

> Is the plan to use Firefox Sync to sync the user's private keys across
  multiple browser instances so that the user doesn't need to manually
  transfer keys in the usual case?

I do think so, however, there are those who would caution against the private key ever going over the wire. I think with Sync, it would be safe.

- -

> Currently, it is unfortunate that choosing to use a webmail client
  effectively prevents a person from using encrypted email. To allow
  people to use end-to-end encrypted email with webmail apps, it would be
  useful to support OpenPGP as an encryption format. (Obviously, a
  malicious webmail app could capture the decrypted messages on the
  browser and send them back to the server, but when the webmail app
  itself doesn't contain code like that, putting the decryption in the
  browser rather than putting it on the server would still probably be
  more subpoena-resistant and resistant against casual snooping by bored

I think with an API like this we might see a whole new breed of communications applications that can supplant email and webmail entirely. "Host Proof" apps like Sync are what we need to move to, encrypted by default is possible with our fast CPUs. As I have strived for a very "webby" API, I tried not to design around existing formats, just going for a simple JSON based message, keypair and addressbook-entry. There is no reason a followup spec could not support existing messaging formats.

- -

> It seems unfortunate that the proposed API entry point is yet another
  special name in the global scope. It seems to me that it would be better
  to put the new stuff on the existing window.crypto object or, if mixing
  with the old object is considered confusing, it would make sense to put
  the new stuff on the navigator object as navigator.crypto or
  navigator.cipher in order to avoid polluting the global scope.

I am not tied to 'window.cipher', and there has been a bit of discussion on consolidating this API into window.crypto - I put the property on the window via nsIDOMGlobalPropertyInitializer, which makes it easy:)

- -

> The public key discovery section shows a </meta> end tag. I hope this is
 just a plain error and having content in a meta element isn't part of
 any design.

The tag is unimportant as well - can you explain why you hope this wil not use a meta tag? I could just as easily use <addressbookentry>

- -

> The public key discovery section is generally confusing. Is <meta
  name="addressbook-entry"> meant to represent an email addressbook entry
  that may happen to have a public key associated with it? Or is "cipher
  addressbook" crypto lingo that I'm unfamiliar with and <meta
  name="addressbook-entry"> always represents a public key plus metadata?
  Without understanding the general design, it's hard to comment on the
  choice of minting special name="addressbook-entry"-specific attributes.

The ironic thing here is that I am calling a public key with additional meta data an 'addressbook-entry' to avoid using crypto lingo in the first place. The simplest way I can imagine publishing my public key is in a web page tag, where it is parsed by the browser, and the user is prompted to save their contact's "addressbook entry" in order to send private messages to them. I want to avoid standard crypto nomenclature when endusers are involved. I think the complexity of just the crypto lingo is what doomed PGP from mass adoption.

So you publish your addressbook entry in a tag on your page in order to pass your public key over to a contact. Your contact also does this and here we have the simplest possible public key exchange method. 

Best Regards,


More information about the whatwg mailing list