DOMCryptInternalAPI

From MozillaWiki
Jump to: navigation, search
Please use "Edit with form" above to edit this page.

Status

DOMCrypt Internal API
Stage On hold
Status In progress
Release target N/A
Health OK
Status note Needs a new owner

Team

Product manager Sid Stamm
Directly Responsible Individual `
Lead engineer `
Security lead Brian Smith
Privacy lead Sid Stamm
Localization lead n/a
Accessibility lead n/a
QA lead Undetermined
UX lead Undetermined
Product marketing lead Undetermined
Operations lead Undetermined
Additional members n/a

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

`

The given value "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);
};
[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" contains strip markers and therefore it cannot be parsed sufficiently.

Feature details

Priority Unprioritized
Rank 999
Theme / Goal Security Leadership
Roadmap Security
Secondary roadmap Privacy
Feature list Platform
Project `
Engineering team Security

Team status notes

  status notes
Products ` `
Engineering Under development The initial patch is being worked on via bug 649154 , additional bugs are blocked by bug 649154
Security sec-review-active we want to have bsmith look at this
Privacy ` `
Localization ` `
Accessibility ` `
Quality assurance ` `
User experience ` `
Product marketing ` `
Operations ` `