Privacy/Features/DOMCryptAPISpec/Latest

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 WebIDL

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.

 
[Supplemental]
interface Crypto {
  readonly attribute CryptoPk pk;
  readonly attribute CryptoSym sym;
  readonly attribute CryptoHash hash;
  readonly attribute CryptoHmac hmac;
};

dictionary CryptoKeyPair {
  long created;
  DOMString privKey;
  DOMString pubKey;
  DOMString salt;
  DOMString iv;
  DOMString algorithm; 
}

dictionary CryptoConfiguration {
  CryptoKeyPair keyID;
};

interface PKCryptoMessage {
  attribute DOMString cryptoMessage;
  attribute DOMString wrappedKey;
  attribute DOMString pubKey;
  attribute DOMString salt;
  attribute DOMString iv;
  attribute DOMString algorithm; 
};

[Callback=FunctionOnly, NoInterfaceObject] interface GenerateKeypairCallback {
  void onsuccess(DOMString pubKey);
};

[Callback=FunctionOnly, NoInterfaceObject] interface PKEncryptCallback {
  void onsuccess(PKCryptoMessage message);
};

[Callback=FunctionOnly, NoInterfaceObject] interface PKDecryptCallback {
  void onsuccess(DOMString plainText);
};

[Callback=FunctionOnly, NoInterfaceObject] interface PKSignCallback {
  void onsuccess(DOMString signature);
};

[Callback=FunctionOnly, NoInterfaceObject] interface PKVerifyCallback {
  void onsuccess(boolean verified);
};

interface CryptoPk {

  attribute DOMString algorithm;

  void generateKeypair(GenerateKeypairCallback callback);

  void encrypt(DOMString plainText, DOMString pubKey, PKEncryptCallback callback);

  void decrypt(PKCryptoMessage message, PKDecryptCallback callback);

  void sign(DOMString plainText, PKSignCallback callback);

  void verify(DOMString signature, DOMString plainText, PKVerifyCallback callback);

};

[Callback=FunctionOnly, NoInterfaceObject] interface SymGenerateKeyCallback {
  void onsuccess(DOMString symKey);
};

[Callback=FunctionOnly, NoInterfaceObject] interface SymEncryptCallback {
  void onsuccess(DOMString cipherText);
};

[Callback=FunctionOnly, NoInterfaceObject] interface SymDecryptCallback {
  void onsuccess(DOMString plainText);
};

interface CryptoSym {

  attribute DOMString algorithm;

  void generateKey(SymGenerateKeyCallback callback);

  void encrypt(DOMString plainText, DOMString symKey, SymEncryptCallback callback);

  void decrypt(DOMString cipherText, DOMString symKey, SymDecryptCallback callback);

};

[Callback=FunctionOnly, NoInterfaceObject] interface hashCallback {
  void onsuccess(DOMString hash);
};

interface CryptoHash {

  attribute DOMString algorithm;

  void createHash(DOMString plainText, hashCallback callback);

};

[Callback=FunctionOnly, NoInterfaceObject] interface createHMACCallback {
  void onsuccess(DOMString hmac);
};

[Callback=FunctionOnly, NoInterfaceObject] interface verifyHMACCallback {
  void onsuccess(boolean verified);
};

interface CryptoHmac {

  attribute DOMString algorithm;

  void createHMAC(DOMString plainText, DOMString pubKey, createHMACCallback callback);

  void verifyHMAC(DOMString plainText, verifyHMACCallback callback);

};

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

• DOMCrypt: http://domcrypt.org
• DOMCrypt Mozilla bugs:
  • https://bugzilla.mozilla.org/show_bug.cgi?id=649154
  • https://bugzilla.mozilla.org/show_bug.cgi?id=657432
• DOMCrypt WebKit bug:
  • https://bugs.webkit.org/show_bug.cgi?id=62010

• WHAT-WG mailing list thread: http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2011-May/031741.html
• W3C mailing list thread: http://lists.w3.org/Archives/Public/public-web-security/2011Jun/0000.html
• Mailing lists summarized http://etherpad.mozilla.com:9000/DOMCrypt-discussion