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.

interface nsIAuthPromptCallback : nsISupports {
  /**
   * Authentication information is available.
   *
   * @param aContext
   *        The context as passed to promptPasswordAsync
   * @param user
   *        The username the user entered (or, if ONLY_PASSWORD was set,
   *        that was passed to the nsIAuthPrompt2)
   * @param password
   *        The password the user entered.
   * @param domain
   *        The domain name the user entered, if NEED_DOMAIN was set.
   * @param flags
   *        Flags as passed to promptPasswordAsync
   *
   * @note  Any exceptions thrown from this method should be ignored.
   */
  void onAuthAvailable(in nsISupports aContext,
                       in AString user,
                       in AString password,
                       in AString domain,
                       in unsigned long flags);

  /**
   * Notification that the prompt was cancelled.
   * @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);
};

interface nsIAuthPrompt2 : nsISupports
{         
   const PRUint32 SAVE_PASSWORD_NEVER             = 0;
   const PRUint32 SAVE_PASSWORD_FOR_SESSION       = 1;
   const PRUint32 SAVE_PASSWORD_PERMANENTLY       = 2;

   /** @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;
   /* @} */

   /** @name Flags */
   /* @{ */
   /**
    * This dialog belongs to a network host.
    */
   const PRUint32 AUTH_HOST = 0;
   /**
    * This dialog belongs to a proxy.
    */
   const PRUint32 AUTH_PROXY = 1;

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

   /**
    * This dialog only asks for password information. The implementation SHOULD
    * NOT show a username field. It MUST NOT modify the user inout parameter,
    * 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 = 4;
   /* @} */

   /**
    * 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 passwordRealm
    *        The server-supplied realm for the password. This is a
    *        human-readable string like "Secret files".
    * @param level
    *        One of the level constants from above. See there for descriptions
    *        of the levels.
    * @param savePassword
    *        Hint to the implementation whether to allow saving a password and
    *        for which duration. See above for descriptions of the values.
    * @param flags
    *        Flags describing this dialog. A bitwise OR of the flag values
    *        above.
    * @param user
    *        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.
    * @param pwd
    *        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.
    * @param domain
    *        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 parameter is only used if flags include AUTH_DOMAIN.
    *
    * @retval true
    *         Authentication can proceed using the values of the out
    *         parameters.
    * @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 promptUsernameAndPassword(in nsIChannel aChannel,
                                     in AString passwordRealm,
                                     in PRUint32 level,
                                     in PRUint32 savePassword,
                                     in PRUint32 flags,
                                     inout AString user, 
                                     inout AString pwd,
                                     inout AString domain);

   /**
    * 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 onAuthCancelled method must be called.
    * Calling cancel on the returned object SHOULD close the dialog
    * and MUST call onAuthCancelled on the provided callback.
    *
    * @throw NS_ERROR_NOT_IMPLEMENTED
    *        Asynchronous authentication prompts are not supported;
    *        the caller should fall back to promptUsernameAndPassword
    */
   nsICancelable promptPasswordAsync(in nsIChannel aChannel,
                                     in nsIAuthPromptCallback aCallback,
                                     in nsISupports aContext,
                                     in PRUint32 level,
                                     in PRUint32 savePassword,
                                     in PRUint32 flags,
                                     in AString user,
                                     in AString pwd,
                                     in AString domain);

};

Issues

• NSS/PSM wants to prompt for passwords as well, and has no nsIChannel available
  • http://lxr.mozilla.org/seamonkey/source/security/manager/ssl/src/nsNSSCallbacks.cpp#188
  • Make aChannel an nsISupports, which can also be a certificate or certificate store or whatever?
  • However, after thinking more about this, I don't think it makes sense for this interface to be used by PSM. PSM has no use for a user or a domain, the "levels" here are not useful for it, and dialogs for certificate stores will probably look quite different. It should have its own interface.
• Use nsIRequest instead of nsIChannel?
• The parameter lists are quite long; group some of the info together on an object? This object could be passed to both functions.
  • It would fix this error: ../../../../../mozilla/netwerk/base/public/nsIAuthPrompt2.idl:106: Error: [domstring], [utf8string], [cstring], [astring] types cannot be used as inout parameters