View source for Necko:nsIAuthPrompt2

https://bugzilla.mozilla.org/show_bug.cgi?id=265780

This page describes new and improved authentication interfaces for necko. There are various downsides of the current ones, including:
* Necko must use localized strings
* Embeddors don't get sufficient information
* etc, see https://bugzilla.mozilla.org/showdependencytree.cgi?id=265780

The interfaces in question are nsIAuthPrompt and nsIPromptService; possibly nsIPrompt as well.

I'll suggest an nsIAuthPrompt2 interface below. Its methods will have counterparts in nsIPromptService2; they will have the same signature but an additional window argument.

The nsIAuthPrompt2 is what necko calls stuff on; nsIPromptService2 is what embeddors would implement.

This suggestion is based on https://bugzilla.mozilla.org/attachment.cgi?id=163161 but slightly modified, and async calls added.

 /**
 * A object that hold authentication information. The caller of
 * nsIAuthPrompt2::promptUsernameAndPassword or
 * nsIAuthPrompt2::promptPasswordAsync provides an object implementing this
 * interface; the prompt implementation can then read the values here to prefill
 * the dialog. After the user entered the authentication information, it should
 * set the attributes of this object to indicate to the caller what was entered
 * by the user.
 */
 [scriptable, uuid(0d73639c-2a92-4518-9f92-28f71fea5f20)]
 interface nsIAuthInformation : nsISupports
 {
  /** @name Flags */
  /* @{ */
  /**
   * This dialog belongs to a network host.
   */
  const PRUint32 AUTH_HOST = 1;

  /**
   * This dialog belongs to a proxy.
   */
  const PRUint32 AUTH_PROXY = 2;

  /**
   * This dialog needs domain information. The user interface should show a
   * domain field, prefilled with the domain attribute's value.
   */
  const PRUint32 NEED_DOMAIN = 4;

  /**
   * This dialog only asks for password information. The implementation SHOULD
   * NOT show a username field. It MUST NOT modify the user attribute,
   * although it should show its initial value to the user in some form. For
   * example, a paragraph in the dialog might say "Please enter your password
   * for user jsmith at server intranet".
   *
   * This flag is mutually exclusive with #NEED_DOMAIN.
   */
  const PRUint32 ONLY_PASSWORD = 8;
  /* @} */

  /**
   * Flags describing this dialog. A bitwise OR of the flag values
   * above.
   *
   * It is possible that neither #AUTH_HOST nor #AUTH_PROXY are set.
   *
   * Implementations should ignore flags they don't understand; especially, they
   * should not throw an exception because of an unsupported flag.
   */
  readonly attribute unsigned long flags;

  /**
   * The server-supplied realm of the authentication as defined in RFC 2617.
   * Can be the empty string if the protocol does not support realms.
   * Otherwise, this is a human-readable string like "Secret files".
   */
  readonly attribute AString realm;

  /**
   * The authentication scheme used for this request, if applicable. If the
   * protocol for this authentication does not support schemes, this will be
   * the empty string. Otherwise, this will be a string such as "basic" or 
   * "digest". This string will always be in lowercase.
   */
  readonly attribute AUTF8String authenticationScheme;

  /**
   * The initial value should be used to prefill the dialog.
   * Implementations should not show the password in clear.
   * On return, this parameter should contain the username entered by
   * the user.
   */
  attribute AString username;

  /**
   * The initial value should be used to prefill the dialog or show it
   * in some other way to the user.
   * On return, this parameter should contain the username entered by
   * the user.
   */
  attribute AString password;

  /**
   * The initial value should be used to prefill the dialog or show it
   * in some other way to the user.
   * On return, this parameter should contain the domain entered by
   * the user.
   * This attribute is only used if flags include #NEED_DOMAIN.
   */
  attribute AString domain;
 };

 /**
 * Interface for callback methods for the asynchronous nsIAuthPrompt2 method.
 * Callers MUST call exactly one method if nsIAuthPrompt2::promptPasswordAsync
 * returns successfully. They MUST NOT call any method on this interface before
 * promptPasswordAsync returns.
 */
 [scriptable, uuid(bdc387d7-2d29-4cac-92f1-dd75d786631d)]
 interface nsIAuthPromptCallback : nsISupports
 {
  /**
   * Authentication information is available.
   *
   * @param aContext
   *        The context as passed to promptPasswordAsync
   * @param aAuthInfo
   *        Authentication information. Must be the same object that was passed
   *        to promptPasswordAsync.
   *
   * @note  Any exceptions thrown from this method should be ignored.
   */
  void onAuthAvailable(in nsISupports aContext,
                       in nsIAuthInformation aAuthInfo);

  /**
   * Notification that the prompt was cancelled.
   *
   * @param aContext
   *        The context that was passed to promptPasswordAsync.
   * @param userCancel
   *        If false, this prompt was cancelled by calling the
   *        the cancel method on the nsICancelable; otherwise,
   *        it was cancelled by the user.
   */
  void onAuthCancelled(in nsISupports aContext, in boolean userCancel);
 };


 /**
 * An interface allowing to prompt for a username and password. This interface
 * is usually acquired using getInterface on notification callbacks or similar.
 * It can be used to prompt users for authentication information, either
 * synchronously or asynchronously.
 */
 [scriptable, uuid(447fc780-1d28-412a-91a1-466d48129c65)]
 interface nsIAuthPrompt2 : nsISupports
 {         
  /** @name Security Levels */
  /* @{ */
  /**
   * The password will be sent unencrypted. No security provided.
   */
  const PRUint32 LEVEL_NONE = 0;
  /**
   * Password will be sent encrypted, but the connection is otherwise
   * insecure.
   */
  const PRUint32 LEVEL_PW_ENCRYPTED = 1;
  /**
   * The connection, both for password and data, is secure.
   */
  const PRUint32 LEVEL_SECURE = 2;
  /* @} */

  /**
   * Requests a username and a password. Implementations will commonly show a
   * dialog with a username and password field, depending on flags also a
   * domain field.
   *
   * @param aChannel
   *        The channel that requires authentication.
   * @param level
   *        One of the level constants from above. See there for descriptions
   *        of the levels.
   * @param authInfo
   *        Authentication information object. The implementation should fill in
   *        this object with the information entered by the user before
   *        returning.
   *
   * @retval true
   *         Authentication can proceed using the values in the authInfo
   *         object.
   * @retval false
   *         Authentication should be cancelled, usually because the user did
   *         not provide username/password.
   *
   * @note   Exceptions thrown from this function will be treated like a
   *         return value of false.
   */
  boolean promptAuth(in nsIChannel aChannel,
                     in PRUint32 level,
                     in nsIAuthInformation authInfo);

  /**
   * Asynchronously prompt the user for a username and password.
   * This has largely the same semantics as promptUsernameAndPassword(),
   * but must return immediately after calling and return the entered
   * data in a callback.
   *
   * If the user closes the dialog using a cancel button or similar,
   * the callback's nsIAuthPromptCallback::onAuthCancelled method must be
   * called.
   * Calling nsICancelable::cancel on the returned object SHOULD close the
   * dialog and MUST call nsIAuthPromptCallback::onAuthCancelled on the provided
   * callback.
   *
   * @throw NS_ERROR_NOT_IMPLEMENTED
   *        Asynchronous authentication prompts are not supported;
   *        the caller should fall back to promptUsernameAndPassword().
   */
  nsICancelable asyncPromptAuth(in nsIChannel aChannel,
                                in nsIAuthPromptCallback aCallback,
                                in nsISupports aContext,
                                in PRUint32 level,
                                in nsIAuthInformation authInfo);
 };