services/crypto/IWeaveCrypto.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Weave code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Mozilla Corporation
  19  * Portions created by the Initial Developer are Copyright (C) 2007
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Dan Mills <thunder@mozilla.com> (original author)
  24  *   Honza Bambas <honzab@allpeers.com>
  25  *   Justin Dolske <dolske@mozilla.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 [scriptable, uuid(f4463043-315e-41f3-b779-82e900e6fffa)]
  44 interface IWeaveCrypto : nsISupports
  45 {
  46   /**
  47    * Shortcuts for some algorithm SEC OIDs.  Full list available here:
  48    * http://lxr.mozilla.org/seamonkey/source/security/nss/lib/util/secoidt.h
  49    */
  50
  51   const unsigned long DES_EDE3_CBC = 156;
  52   const unsigned long AES_128_CBC  = 184;
  53   const unsigned long AES_192_CBC  = 186;
  54   const unsigned long AES_256_CBC  = 188;
  55
  56   /**
  57    * One of the above constants. Used as the mechanism for encrypting bulk
  58    * data and wrapping keys.
  59    *
  60    * Default is AES_256_CBC.
  61    */
  62   attribute unsigned long algorithm;
  63
  64   /**
  65    * The size of the RSA key to create with generateKeypair().
  66    *
  67    * Default is 2048.
  68    */
  69   attribute unsigned long keypairBits;
  70
  71   /**
  72    * Encrypt data using a symmetric key.
  73    * The algorithm attribute specifies how the encryption is performed.
  74    *
  75    * @param   clearText
  76    *          The data to be encrypted (not base64 encoded).
  77    * @param   symmetricKey
  78    *          A base64-encoded symmetric key (eg, one from generateRandomKey).
  79    * @param   iv
  80    *          A base64-encoded initialization vector
  81    * @returns Encrypted data, base64 encoded
  82    */
  83   ACString encrypt(in AUTF8String clearText,
  84                    in ACString symmetricKey, in ACString iv);
  85
  86   /**
  87    * Encrypt data using a symmetric key.
  88    * The algorithm attribute specifies how the encryption is performed.
  89    *
  90    * @param   cipherText
  91    *          The base64-encoded data to be decrypted
  92    * @param   symmetricKey
  93    *          A base64-encoded symmetric key (eg, one from unwrapSymmetricKey)
  94    * @param   iv
  95    *          A base64-encoded initialization vector
  96    * @returns Decrypted data (not base64-encoded)
  97    */
  98   AUTF8String decrypt(in ACString cipherText,
  99                    in ACString symmetricKey, in ACString iv);
 100
 101   /**
 102    * Generate a RSA public/private keypair.
 103    *
 104    * @param aPassphrase
 105    *        User's passphrase. Used with PKCS#5 to generate a symmetric key
 106    *        for wrapping the private key.
 107    * @param aSalt
 108    *        Salt for the user's passphrase.
 109    * @param aIV
 110    *        Random IV, used when wrapping the private key.
 111    * @param aEncodedPublicKey
 112    *        The public key, base-64 encoded.
 113    * @param aWrappedPrivateKey
 114    *        The public key, encrypted with the user's passphrase, and base-64 encoded.
 115    */
 116   void generateKeypair(in ACString aPassphrase, in ACString aSalt, in ACString aIV,
 117                        out ACString aEncodedPublicKey, out ACString aWrappedPrivateKey);
 118
 119   /*
 120    * Generate a random symmetric key.
 121    *
 122    * @returns The random key, base64 encoded
 123    */
 124   ACString generateRandomKey();
 125
 126   /*
 127    * Generate a random IV.
 128    *
 129    * The IV will be sized for the algorithm specified in the algorithm
 130    * attribute of IWeaveCrypto.
 131    *
 132    * @returns The random IV, base64 encoded
 133    */
 134   ACString generateRandomIV();
 135
 136   /*
 137    * Generate random data.
 138    *
 139    * @param aByteCount
 140    *        The number of bytes of random data to generate.
 141    * @returns The random bytes, base64-encoded
 142    */
 143   ACString generateRandomBytes(in unsigned long aByteCount);
 144
 145
 146   /**
 147    * Encrypts a symmetric key with a user's public key.
 148    *
 149    * @param aSymmetricKey
 150    *        The base64 encoded string holding a symmetric key.
 151    * @param aEncodedPublicKey
 152    *        The base64 encoded string holding a public key.
 153    * @returns The wrapped symmetric key, base64 encoded
 154    *
 155    * For RSA, the unencoded public key is a PKCS#1 object.
 156    */
 157   ACString wrapSymmetricKey(in ACString aSymmetricKey,
 158                             in ACString aEncodedPublicKey);
 159
 160   /**
 161    * Decrypts a symmetric key with a user's private key.
 162    *
 163    * @param aWrappedSymmetricKey
 164    *        The base64 encoded string holding an encrypted symmetric key.
 165    * @param aWrappedPrivateKey
 166    *        The base64 encoded string holdering an encrypted private key.
 167    * @param aPassphrase
 168    *        The passphrase to decrypt the private key.
 169    * @param aSalt
 170    *        The salt for the passphrase.
 171    * @param aIV
 172    *        The random IV used when unwrapping the private key.
 173    * @returns The unwrapped symmetric key, base64 encoded
 174    *
 175    * For RSA, the unencoded, decrypted key is a PKCS#1 object.
 176    */
 177   ACString unwrapSymmetricKey(in ACString aWrappedSymmetricKey,
 178                               in ACString aWrappedPrivateKey,
 179                               in ACString aPassphrase,
 180                               in ACString aSalt,
 181                               in ACString aIV);
 182
 183   /**
 184    * Rewrap a private key with a new user passphrase.
 185    *
 186    * @param aWrappedPrivateKey
 187    *        The base64 encoded string holding an encrypted private key.
 188    * @param aPassphrase
 189    *        The passphrase to decrypt the private key.
 190    * @param aSalt
 191    *        The salt for the passphrase.
 192    * @param aIV
 193    *        The random IV used when unwrapping the private key.
 194    * @param aNewPassphrase
 195    *        The new passphrase to wrap the private key with.
 196    * @returns The (re)wrapped private key, base64 encoded
 197    *
 198    */
 199    ACString rewrapPrivateKey(in ACString aWrappedPrivateKey,
 200                              in ACString aPassphrase,
 201                              in ACString aSalt,
 202                              in ACString aIV,
 203                              in ACString aNewPassphrase);
 204
 205    /**
 206     * Verify a user's passphrase against a private key.
 207     *
 208     * @param aWrappedPrivateKey
 209     *        The base64 encoded string holding an encrypted private key.
 210     * @param aPassphrase
 211     *        The passphrase to decrypt the private key.
 212     * @param aSalt
 213     *        The salt for the passphrase.
 214     * @param aIV
 215     *        The random IV used when unwrapping the private key.
 216     * @returns Boolean true if the passphrase decrypted the key correctly.
 217     *
 218     */
 219    boolean verifyPassphrase(in ACString aWrappedPrivateKey,
 220                             in ACString aPassphrase,
 221                             in ACString aSalt,
 222                             in ACString aIV);
 223 };
 224