toolkit/identity/nsIIdentityCryptoService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIURI;
   8 interface nsIIdentityKeyGenCallback;
   9 interface nsIIdentitySignCallback;
  10
  11 /* Naming and calling conventions:
  12  *
  13  * A"hex" prefix means "hex-encoded string representation of a byte sequence"
  14  * e.g. "ae34bcdf123"
  15  *
  16  * A "base64url" prefix means "base-64-URL-encoded string repressentation of a
  17  * byte sequence.
  18  * e.g. "eyJhbGciOiJSUzI1NiJ9"
  19  * http://en.wikipedia.org/wiki/Base64#Variants_summary_table
  20  * we use the no-padding approach to base64-url-encoding
  21  *
  22  * Callbacks take an "in nsresult rv" argument that indicates whether the async
  23  * operation succeeded. On success, rv will be a success code
  24  * (NS_SUCCEEDED(rv) / Components.isSuccessCode(rv)) and the remaining
  25  * arguments are as defined in the documentation for the callback. When the
  26  * operation fails, rv will be a failure code (NS_FAILED(rv) /
  27  * !Components.isSuccessCode(rv)) and the values of the remaining arguments will
  28  * be unspecified.
  29  *
  30  * Key Types:
  31  *
  32  * "RS256": RSA + SHA-256.
  33  *
  34  * "DS160": DSA with SHA-1. A 1024-bit prime and a 160-bit subprime with SHA-1.
  35  *
  36  * we use these abbreviated algorithm names as per the JWA spec
  37  * http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-02
  38  */
  39
  40 // "@mozilla.org/identity/crypto-service;1"
  41 [scriptable, builtinclass, uuid(f087e6bc-dd33-4f6c-a106-dd786e052ee9)]
  42 interface nsIIdentityCryptoService : nsISupports
  43 {
  44   void generateKeyPair(in AUTF8String algorithm,
  45                        in nsIIdentityKeyGenCallback callback);
  46
  47   ACString base64UrlEncode(in AUTF8String toEncode);
  48 };
  49
  50 /**
  51  * This interface provides a keypair and signing interface for Identity functionality
  52  */
  53 [scriptable, uuid(73962dc7-8ee7-4346-a12b-b039e1d9b54d)]
  54 interface nsIIdentityKeyPair : nsISupports
  55 {
  56   readonly attribute AUTF8String keyType;
  57
  58   // RSA properties, only accessible when keyType == "RS256"
  59
  60   readonly attribute AUTF8String hexRSAPublicKeyExponent;
  61   readonly attribute AUTF8String hexRSAPublicKeyModulus;
  62
  63   // DSA properties, only accessible when keyType == "DS128"
  64   readonly attribute AUTF8String hexDSAPrime;       // p
  65   readonly attribute AUTF8String hexDSASubPrime;    // q
  66   readonly attribute AUTF8String hexDSAGenerator;   // g
  67   readonly attribute AUTF8String hexDSAPublicValue; // y
  68
  69   void sign(in AUTF8String aText,
  70             in nsIIdentitySignCallback callback);
  71
  72   // XXX implement verification bug 769856
  73   // AUTF8String verify(in AUTF8String aSignature, in AUTF8String encodedPublicKey);
  74
  75 };
  76
  77 /**
  78  * This interface provides a JavaScript callback object used to collect the
  79  * nsIIdentityServeKeyPair when the keygen operation is complete
  80  *
  81  * though there is discussion as to whether we need the nsresult,
  82  * we keep it so we can track deeper crypto errors.
  83  */
  84 [scriptable, function, uuid(90f24ca2-2b05-4ca9-8aec-89d38e2f905a)]
  85 interface nsIIdentityKeyGenCallback : nsISupports
  86 {
  87   void generateKeyPairFinished(in nsresult rv,
  88                                in nsIIdentityKeyPair keyPair);
  89 };
  90
  91 /**
  92  * This interface provides a JavaScript callback object used to collect the
  93  * AUTF8String signature
  94  */
  95 [scriptable, function, uuid(2d3e5036-374b-4b47-a430-1196b67b890f)]
  96 interface nsIIdentitySignCallback : nsISupports
  97 {
  98   /** On success, base64urlSignature is the base-64-URL-encoded signature
  99    *
 100    * For RS256 signatures, XXX bug 769858
 101    *
 102    * For DSA128 signatures, the signature is the r value concatenated with the
 103    * s value, each component padded with leading zeroes as necessary.
 104    */
 105   void signFinished(in nsresult rv, in ACString base64urlSignature);
 106 };