security/manager/ssl/nsISecretDecoderRing.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 [scriptable, uuid(0EC80360-075C-11d4-9FD4-00C04F1B83D8)]
   9 interface nsISecretDecoderRing: nsISupports {
  10   /**
  11    * Encrypt to Base64 output.
  12    * Note that the input must basically be a byte array (i.e. the code points
  13    * must be within the range [0, 255]). Hence, using this method directly to
  14    * encrypt passwords (or any text, really) won't work as expected.
  15    * Instead, use something like nsIScriptableUnicodeConverter to first convert
  16    * the desired password or text to UTF-8, then encrypt that. Remember to
  17    * convert back when calling decryptString().
  18    *
  19    * @param text The text to encrypt.
  20    * @return The encrypted text, encoded as Base64.
  21    */
  22   [must_use]
  23   ACString encryptString(in ACString text);
  24
  25   /**
  26    * Run encryptString on multiple strings, asynchronously. This will allow you
  27    * to not jank the browser if you need to encrypt a large number of strings
  28    * all at once. This method accepts an array of wstrings which it will convert
  29    * to UTF-8 internally before encrypting.
  30    *
  31    * @param plaintexts the strings to encrypt.
  32    * @return A promise for the list of encrypted strings, encoded as Base64.
  33    */
  34   [implicit_jscontext, must_use]
  35   Promise asyncEncryptStrings(in Array<AUTF8String> plaintexts);
  36
  37   /**
  38    * Decrypt Base64 input.
  39    * See the encryptString() documentation - this method has basically the same
  40    * limitations.
  41    *
  42    * @param encryptedBase64Text Encrypted input text, encoded as Base64.
  43    * @return The decoded text.
  44    */
  45   [must_use]
  46   ACString decryptString(in ACString encryptedBase64Text);
  47
  48   /**
  49    * Run decryptString on multiple strings, asynchronously. This will allow you
  50    * to not jank the browser if you need to decrypt a large number of strings
  51    * all at once.
  52    *
  53    * @param encryptedStrings the strings to decrypt, encoded as Base64.
  54    * @return A promise that resolves with the list of decrypted strings in Unicode.
  55    */
  56   [implicit_jscontext, must_use]
  57   Promise asyncDecryptStrings(in Array<ACString> encryptedStrings);
  58
  59   /**
  60    * Prompt the user to change the password on the SDR key.
  61    */
  62   [must_use]
  63   void changePassword();
  64
  65   /**
  66    * Logout of the security device that protects the SDR key.
  67    */
  68   [must_use]
  69   void logout();
  70
  71   /**
  72    * Logout of the security device that protects the SDR key and tear
  73    * down authenticated objects.
  74    */
  75   [must_use]
  76   void logoutAndTeardown();
  77 };