Privacy/Features/DOMCryptAPISpec/Latest: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Fix another supplemental)
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
= DOMCrypt 'window.mozCrypto' Specification =
= DOMCrypt Specification =


;DRAFT
;DRAFT


;Version 0.3
;Version 0.4


;Updated 2011-07-13
;Updated 2011-07-26


; Author: David Dahl <ddahl@mozilla.com>
; Author: David Dahl <ddahl@mozilla.com>
; Author: Adam Barth <adam@adambarth.com>


== Introduction ==
== 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 ).
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 ).
=== W3C Web Cryptography Working Group Charter ===
* The W3C is using the DOMCrypt API as the "strawman" API
** http://www.w3.org/2011/11/webcryptography-charter.html


== Terms ==
== Terms ==
Line 22: Line 27:


; window.mozCrypto
; 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
: The temporary window property used to distinguish this new API from the current window.crypto property (used in the extension code and the current Gecko patches). The consensus so far is to add this API to the window.crypto property


; window.crypto
; window.crypto
Line 35: Line 40:
; Private Key
; Private Key
: The private half of an asymmetric key pair
: The private half of an asymmetric key pair
; Symmetric Key
: an encryption key used for symmetric encryption


== Browser Window property WebIDL ==
== Browser Window property WebIDL ==
Line 45: Line 47:
All windows will have this property (in the current implementation) for the time being as this API is hashed out.
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.<br>
The property is namespaced in order to provide future capabilities.


<pre class="brush:js;toolbar:false;">  
<pre class="brush:js;toolbar:false;">  
[Supplemental]
supplemental interface Crypto {
interface Crypto {
   readonly attribute CryptoPk pk;
   readonly attribute CryptoPk pk;
   readonly attribute CryptoSym sym;
   readonly attribute CryptoSign sign;
  readonly attribute CryptoHash hash;
  readonly attribute CryptoHmac hmac;
};
};


interface PKCryptoPublicKey {
[Constructor(DOMString algorithm)]
  readonly attribute DOMString pubKey;
interface CryptoHash {
  readonly attribute DOMString algorithm;
   void append(ArrayBuffer data);
  readonly attribute integer created;
   ArrayBuffer finish();
}
 
interface PKCryptoMessage {
   attribute DOMString cryptoMessage;  
   attribute DOMString algorithm;  
};
};


[Callback=FunctionOnly, NoInterfaceObject] interface GenerateKeypairCallback {
[Constructor(DOMString algorithm, ArrayBuffer key)]
   void onsuccess(DOMString pubKey);
interface CryptoHmac {
};
   void append(ArrayBuffer data);
 
   ArrayBuffer finish();
[Callback=FunctionOnly, NoInterfaceObject] interface GetPublicKeyCallback {
   void onsuccess(DOMString pubKey);
};
};


[Callback=FunctionOnly, NoInterfaceObject] interface PKEncryptCallback {
callback interface GenerateKeypairCallback {
   void onsuccess(PKCryptoMessage message);
   void onsuccess(ArrayBuffer keyID, ArrayBuffer pubKey);
};
};


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


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


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


interface CryptoPk {
interface CryptoPk {
 
   void generateKeypair(DOMString algorithm, GenerateKeypairCallback callback, boolean signingKeypair);
  attribute DOMString algorithm;
 
   void generateKeypair(GenerateKeypairCallback callback);
 
   void getPublicKey(GetPublicKeyCallback callback);
   void getPublicKey(GetPublicKeyCallback callback);
 
   void encrypt(ArrayBuffer plainText, ArrayBuffer keyID, PKEncryptCallback callback);
   void encrypt(DOMString plainText, DOMString pubKey, PKEncryptCallback callback);
   void decrypt(ArrayBuffer message, ArrayBuffer keyID, PKDecryptCallback callback);
 
   void decrypt(PKCryptoMessage message, PKDecryptCallback callback);
 
  void sign(DOMString plainText, PKSignCallback callback);
 
  void verify(DOMString signature, DOMString pubKey, DOMString plainText, PKVerifyCallback callback);
 
};
};


// Use JWE as the crypto object?, or something like the following:
callback interface SignCallback {
interface SymCipherObject {
   void onsuccess(ArrayBuffer signature);
   attribute DOMString cipherString;  
  attribute DOMString algorithm;
  attribute DOMString symKeyID;
  // What is missing here?
};
};


[Callback=FunctionOnly, NoInterfaceObject] interface SymEncryptCallback {
callback interface VerifyCallback {
   void onsuccess(SymCipherObject cipherObject);
   void onsuccess(boolean verified);
};
};


[Callback=FunctionOnly, NoInterfaceObject] interface SymDecryptCallback {
interface CryptoSign {
   void onsuccess(DOMString plainText);
   void sign(ArrayBuffer keyID, ArrayBuffer plainText, PKSignCallback callback);
  void verify(ArrayBuffer signature, ArrayBuffer pubKey, ArrayBuffer plainText, PKVerifyCallback callback);
};
};
</pre>


interface CryptoSym {
== Notes ==


  attribute DOMString algorithm;
*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.
* All the inputs and outputs should be raw, unformatted ArrayBuffers, letting higher-level pure JS wrappers deal with conversion to application data formats until we understand better what higher-level formats would be useful


  void encrypt(DOMString plainText, DOMString symKeyID, SymEncryptCallback callback);
== Possible Additions  ==
 
  void decrypt(DOMString cipherText, DOMString symKeyID, SymDecryptCallback callback);


One possible addition we might consider is providing the web site with a secure mechanism having the user confirm a transaction. For example, a bank web site might wish to have the user sign a statement authorizing the transfer of funds from one account to another. Unlike the DOMCrypt APIs described above, this API involves interacting with the user to achieve non-repudiation:
<pre class="brush:js;toolbar:false;">
supplemental interface CryptoSign {
  void signWithUserConfirmation(in ArrayBuffer keyID, in DOMString description, in ArrayBuffer data, in PKSignCallback callback);
};
};
</pre>
The signWithUserConfirmation method causes the user agent to display some user interface element containing the human-readable description. If the user confirms the description, the user agent with sign both the human-readable description and the binary data with the key designated by the keyId and supply the signature to the caller via the callback. There are still many details to work out, such as the format of the signed message, but this description is a starting point for discussion.


[Callback=FunctionOnly, NoInterfaceObject] interface hashCallback {
to deploy this feature to production level, we have to consider following issues.
  void onsuccess(DOMString hash);
};


interface CryptoHash {
*is passphase of private key safely entered?. means the confirmation screen need anti-keylogger mechanism.  
 
*is browser sandbox safe? even on the user environment is compromized. (virus-infected?)
  attribute DOMString algorithm;
*co-operatable with requirements of security compliances (PCI, ISO27001...)
 
  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, DOMString pubKey, verifyHMACCallback callback);
 
};
</pre>
 
== 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.
*The configuration object should be removed from the IDL as we move to a set of keys per domain


== References  ==
== References  ==
Line 180: Line 134:
**https://bugs.webkit.org/show_bug.cgi?id=62010
**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
*WHATWG 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
*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
*Mailing lists summarized http://etherpad.mozilla.com:9000/DOMCrypt-discussion
<br>
 
== Meetings ==
 
* 2011-07-14, at Mozilla, Mountain View, CA [[Privacy/Features/DOMCryptAPISpec/Meeting-2011-07-14]]

Latest revision as of 13:25, 15 February 2012

DOMCrypt Specification

DRAFT
Version 0.4
Updated 2011-07-26
Author
David Dahl <ddahl@mozilla.com>
Author
Adam Barth <adam@adambarth.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 ).

W3C Web Cryptography Working Group Charter

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 (used in the extension code and the current Gecko patches). 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

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 CryptoSign sign;
};

[Constructor(DOMString algorithm)]
interface CryptoHash {
  void append(ArrayBuffer data);
  ArrayBuffer finish();
};

[Constructor(DOMString algorithm, ArrayBuffer key)]
interface CryptoHmac {
  void append(ArrayBuffer data);
  ArrayBuffer finish();
};

callback interface GenerateKeypairCallback {
  void onsuccess(ArrayBuffer keyID, ArrayBuffer pubKey);
};

callback interface GetPublicKeyCallback {
  void onsuccess(ArrayBuffer pubKey);
};

callback interface PKEncryptCallback {
  void onsuccess(ArrayBuffer message);
};

callback interface PKDecryptCallback {
  void onsuccess(ArrayBuffer plainText);
};

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);
};

callback interface SignCallback {
  void onsuccess(ArrayBuffer signature);
};

callback interface VerifyCallback {
  void onsuccess(boolean verified);
};

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.
  • All the inputs and outputs should be raw, unformatted ArrayBuffers, letting higher-level pure JS wrappers deal with conversion to application data formats until we understand better what higher-level formats would be useful

Possible Additions

One possible addition we might consider is providing the web site with a secure mechanism having the user confirm a transaction. For example, a bank web site might wish to have the user sign a statement authorizing the transfer of funds from one account to another. Unlike the DOMCrypt APIs described above, this API involves interacting with the user to achieve non-repudiation: 

 
supplemental interface CryptoSign {
  void signWithUserConfirmation(in ArrayBuffer keyID, in DOMString description, in ArrayBuffer data, in PKSignCallback callback); 
};

The signWithUserConfirmation method causes the user agent to display some user interface element containing the human-readable description. If the user confirms the description, the user agent with sign both the human-readable description and the binary data with the key designated by the keyId and supply the signature to the caller via the callback. There are still many details to work out, such as the format of the signed message, but this description is a starting point for discussion.

to deploy this feature to production level, we have to consider following issues.

  • is passphase of private key safely entered?. means the confirmation screen need anti-keylogger mechanism.
  • is browser sandbox safe? even on the user environment is compromized. (virus-infected?)
  • co-operatable with requirements of security compliances (PCI, ISO27001...)

References

Meetings

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