DOMCryptInternalAPI

Status

Team

Open issues/risks

The content DOM API that this feature will support should obey private browsing mode, but also integrate well with PSM/NSS, in which case the keystore does not know about Private Browsing. We may need to tie the key storage to Places or something new.

Stage 1: Definition

1. Feature overview

DOMCryptInternalAPI is the PSM code that will generate keypairs, sign, verify, hash, hmac, encrypt and decrypt data. The scriptable interface will reside outside of PSM, consuming this API and providing a simpler abstraction for DOMCrypt, a WebAPI currently being standardized by the W3C via the Web Cryptography Working Group: http://www.w3.org/2012/webcrypto/. This API will also be useful to extension developers and the AddonSDK

2. Users & use cases

• DOMCrypt's DOM bindings ( W3C Web Crypto WG ) will consume this API for all crypto-related functionality
• Extension developers can use this API for any number of signature, hashing, hmac, encrypt and decrypt operations. The API is intended to be relatively easy to use and high-level, only allowing configuration of algorithm and key bits properties
• Mozilla engineers can use this API to experiment in the Privacy, Security and Identity space within browsers more easily than using NSS or more complicated PSM APIs.

• For example: NGOs, human rights organizations and business can use this API to build extensions that improve application security, provide psuedo-anonymity and browser-based encrypted messaging or business transactions.

3. Dependencies

`

4. Requirements

`

Non-goals

• Exposing low-level crypto primitives that can potentially backfire on programmers without deep cryptography understanding

Stage 2: Design

5. Functional specification

This API will need to support the DOM API designed by the W3C Web Crypto WG. The latest - and soon changing spec is here: https://wiki.mozilla.org/Privacy/Features/DOMCryptAPISpec/Latest

IDL

interface nsIDOMCryptAPIKeyPair : nsISupports
{
  readonly attribute AUTF8String publicKey;
  readonly attribute AUTF8String wrappedPrivateKey;
  readonly attribute AUTF8String keyID;
};

interface nsIDOMCryptAPIKeyGenCallback : nsISupports
{
  void keyPairGenFinished(in nsIDOMCryptAPIPublicKey aKeyPair);
};

interface nsIDOMCryptAPIPKEncryptCallback : nsISupports
{
  void encryptFinished(in jsval aCryptoBytes);
};

interface nsIDOMCryptAPIPKDecryptCallback : nsISupports
{
  void decryptFinished(in jsval aClearBytes);
};

interface nsIDOMCryptAPISignatureCallback : nsISupports
{
  void signatureFinished(in jsval aSignature);
};

interface nsIDOMCryptAPIVerifyCallback : nsISupports
{
  void verifyFinished(in boolean aVerified);
};

interface nsIDOMCryptAPI : nsISupports
{
  void PKGenerateKeyPair(in unsigned long aKeySizeInBits, 
                         in unsigned long aAlgorithm,
                         in nsIDOMCryptAPIKeyGenCallback aCallback);
  
  void PKEncrypt(in nsIDOMCryptAPIKeyPair aKeyPair, 
                 in jsval aClearBytes, 
                 in nsIDOMCryptAPIPKEncryptCallback aCallback);

  void PKDecrypt(in AUTF8String aKeyID, 
                 in jsval aEncryptedBytes, 
                 in nsIDOMCryptAPIPKDecryptCallback aCallback);

  const unsigned long ALGORITHM_RSA = 0;
  const unsigned long ALGORITHM_DSA = 1;

  void SigGenerateKeyPair(in unsigned long aKeySizeInBits, 
                          in unsigned long aAlgorithm,
                          in nsIDOMCryptAPIKeyGenCallback aCallback);

  void Sign(in nsIDOMCryptAPIKeyPair aKeyPair, 
            in AString aPlaintext, 
            in nsIDOMCryptAPISignatureCallback aCallback);

  void Verify(in nsIDOMCryptAPIKeyPair aKeyPair, 
              in jsval aClearBytes, 
              in jsval aSignature,
              in nsIDOMCryptAPIVerifyCallback aCallback);
};

• The Hash and HMAC WebIDL from https://wiki.mozilla.org/Privacy/Features/DOMCryptAPISpec/Latest
  • Still need to spend some time on how these should be specified inside this internal API

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

• There is also the need for a symmetric encryption API, perhaps based on DHKE to specify

6. User experience design

`

Stage 3: Planning

7. Implementation plan

`

8. Reviews

Security review

Brian Smith, Kai Engert and Wan-Teh Chang will be asked for review and super review

Privacy review

The privacy team will review this API for potential data leaks, fingerprinting, etc.

Localization review

N/A

Accessibility

Undetermined

Quality Assurance review

Undetermined

Operations review

N/A?

Stage 4: Development

9. Implementation

`

Stage 5: Release

10. Landing criteria

`

interface nsIDOMCryptAPIKeyPair : nsISupports
{
  readonly attribute AUTF8String publicKey;
  readonly attribute AUTF8String wrappedPrivateKey;
  readonly attribute AUTF8String keyID;
};

interface nsIDOMCryptAPIKeyGenCallback : nsISupports
{
  void keyPairGenFinished(in nsIDOMCryptAPIPublicKey aKeyPair);
};

interface nsIDOMCryptAPIPKEncryptCallback : nsISupports
{
  void encryptFinished(in jsval aCryptoBytes);
};

interface nsIDOMCryptAPIPKDecryptCallback : nsISupports
{
  void decryptFinished(in jsval aClearBytes);
};

interface nsIDOMCryptAPISignatureCallback : nsISupports
{
  void signatureFinished(in jsval aSignature);
};

interface nsIDOMCryptAPIVerifyCallback : nsISupports
{
  void verifyFinished(in boolean aVerified);
};

interface nsIDOMCryptAPI : nsISupports
{
  void PKGenerateKeyPair(in unsigned long aKeySizeInBits, 
                         in unsigned long aAlgorithm,
                         in nsIDOMCryptAPIKeyGenCallback aCallback);
  
  void PKEncrypt(in nsIDOMCryptAPIKeyPair aKeyPair, 
                 in jsval aClearBytes, 
                 in nsIDOMCryptAPIPKEncryptCallback aCallback);

  void PKDecrypt(in AUTF8String aKeyID, 
                 in jsval aEncryptedBytes, 
                 in nsIDOMCryptAPIPKDecryptCallback aCallback);

  const unsigned long ALGORITHM_RSA = 0;
  const unsigned long ALGORITHM_DSA = 1;

  void SigGenerateKeyPair(in unsigned long aKeySizeInBits, 
                          in unsigned long aAlgorithm,
                          in nsIDOMCryptAPIKeyGenCallback aCallback);

  void Sign(in nsIDOMCryptAPIKeyPair aKeyPair, 
            in AString aPlaintext, 
            in nsIDOMCryptAPISignatureCallback aCallback);

  void Verify(in nsIDOMCryptAPIKeyPair aKeyPair, 
              in jsval aClearBytes, 
              in jsval aSignature,
              in nsIDOMCryptAPIVerifyCallback aCallback);
};

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

Feature details

Team status notes