Privacy/Features/DOMCryptAPISpec/Latest

DOMCrypt 'window.mozCrypto' Specification

DRAFT

Version 0.4

Updated 2011-07-26

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

window.crypto

The existing DOM property where this API should be integrated

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. Key pairs are bound to the origin

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

[Supplemental] interface Crypto {

 readonly attribute CryptoPk pk;
 readonly attribute CryptoSign sign;

};

[Constructor(in DOMString algorithm)] interface CryptoHash {

 void append(ArrayBuffer data);
 ArrayBuffer finish();

};

[Constructor(in DOMString algorithm)] interface CryptoHmac {

 ArrayBuffer createHMAC(ArrayBuffer plainText, ArrayBuffer key);
 boolean verifyHMAC(ArrayBuffer hmac, ArrayBuffer key);

};

[Callback=FunctionOnly, NoInterfaceObject] interface GenerateKeypairCallback {

 void onsuccess(ArayBuffer keyID, ArrayBuffer pubKey);

};

[Callback=FunctionOnly, NoInterfaceObject] interface GetPublicKeyCallback {

 void onsuccess(ArrayBuffer pubKey);

};

[Callback=FunctionOnly, NoInterfaceObject] interface PKEncryptCallback {

 void onsuccess(ArrayBuffer message);

};

[Callback=FunctionOnly, NoInterfaceObject] interface PKDecryptCallback {

 void onsuccess(ArrayBuffer plainText);

};

[Callback=FunctionOnly, NoInterfaceObject] interface PKSignCallback {

 void onsuccess(ArrayBuffer signature);

};

[Callback=FunctionOnly, NoInterfaceObject] interface PKVerifyCallback {

 void onsuccess(boolean verified);

};

interface CryptoPk {

 void generateKeypair(DOMString algorithm, GenerateKeypairCallback callback, boolean signingKeypair);

 void getPublicKey(GetPublicKeyCallback callback);

 void encrypt(ArrayBuffer plainText, ArrayBuffer keyID, PKEncryptCallback callback);

 void decrypt(ArrayBuffer message, ArrayBuffer keyID, PKDecryptCallback callback);

};

interface CryptoSign {

 void sign(ArrayBuffer keyID, ArrayBuffer plainText, PKSignCallback callback);

 void verify(ArrayBuffer signature, ArrayBuffer pubKey, ArrayBuffer plainText, PKVerifyCallback callback);

};

Notes

• Each origin will only have access to the asymmetric private key generated for it. This will minimize the need for any kind of access control dialog for key usage.

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

Meetings

• 2011-07-14, at Mozilla, Mountain View, CA Privacy/Features/DOMCryptAPISpec/Meeting-2011-07-14