security/manager/ssl/nsIOSReauthenticator.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 interface mozIDOMWindow;
   9
  10 [scriptable, uuid(4fe082ae-6ff0-4b41-b24f-eaa664f6e46a)]
  11 interface nsIOSReauthenticator: nsISupports {
  12   /**
  13    * This interface provides an abstract way to request that the user
  14    * reauthenticate themselves to the operating system. It may be useful in
  15    * conjunction with nsIOSKeyStore, whereby consumers of these APIs may
  16    * consider some secrets too sensitive to access without first
  17    * reauthenticating the user.
  18    *
  19    * Usage:
  20    *
  21    * // obtain the singleton nsIOSReauthenticator instance
  22    * const reauthenticator = Cc["@mozilla.org/security/osreauthenticator;1"]
  23    *                           .getService(Ci.nsIOSReauthenticator);
  24    * if (await reauthenticator.asyncReauthenticate()) {
  25    *   // do something only authenticated users are allowed to do...
  26    * } else {
  27    *   // show a "sorry, this isn't allowed" error
  28    * }
  29    */
  30
  31   /**
  32    * Asynchronously cause the operating system to request that the user
  33    * reauthenticate. This is typically in the form of a dialog box asking the
  34    * user for their login password. The actual behaviour of this depends on the
  35    * OS.
  36    *
  37    * @param prompt A short string that may be incorporated in the dialog
  38    * @param caption A short string that may be shown as the dialog caption (usually Product Name)
  39    * @param parentWindow Used to associate the OS dialog with the calling window.
  40    * @return Promise resolving to true if the user successfully authenticated
  41    *         and false otherwise.
  42    */
  43   [implicit_jscontext, must_use]
  44   Promise asyncReauthenticateUser(in AString prompt, in AString caption, in mozIDOMWindow parentWindow);
  45 };