michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIHttpAuthenticableChannel;
michael@0: 
michael@0: /**
michael@0:  * nsIHttpAuthenticator
michael@0:  *
michael@0:  * Interface designed to allow for pluggable HTTP authentication modules.
michael@0:  * Implementations are registered under the ContractID:
michael@0:  *
michael@0:  *   "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
michael@0:  *
michael@0:  * where <auth-scheme> is the lower-cased value of the authentication scheme
michael@0:  * found in the server challenge per the rules of RFC 2617.
michael@0:  */
michael@0: [scriptable, uuid(16784db0-fcb1-4352-b0c9-6a3a67e3cf79)]
michael@0: interface nsIHttpAuthenticator : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * Upon receipt of a server challenge, this function is called to determine
michael@0:      * whether or not the current user identity has been rejected.  If true,
michael@0:      * then the user will be prompted by the channel to enter (or revise) their
michael@0:      * identity.  Following this, generateCredentials will be called.
michael@0:      *
michael@0:      * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
michael@0:      * return value will be ignored, and user prompting will be suppressed.
michael@0:      *
michael@0:      * @param aChannel
michael@0:      *        the http channel that received the challenge.
michael@0:      * @param aChallenge
michael@0:      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
michael@0:      *        server response header.  (possibly from the auth cache.)
michael@0:      * @param aProxyAuth
michael@0:      *        flag indicating whether or not aChallenge is from a proxy.
michael@0:      * @param aSessionState
michael@0:      *        see description below for generateCredentials.
michael@0:      * @param aContinuationState
michael@0:      *        see description below for generateCredentials.
michael@0:      * @param aInvalidateIdentity
michael@0:      *        return value indicating whether or not to prompt the user for a
michael@0:      *        revised identity.
michael@0:      */
michael@0:     void challengeReceived(in    nsIHttpAuthenticableChannel aChannel,
michael@0:                            in    string       aChallenge,
michael@0:                            in    boolean      aProxyAuth,
michael@0:                            inout nsISupports  aSessionState,
michael@0:                            inout nsISupports  aContinuationState,
michael@0:                            out   boolean      aInvalidatesIdentity);
michael@0: 
michael@0:     /**
michael@0:      * Called to generate the authentication credentials for a particular
michael@0:      * server/proxy challenge.  This is the value that will be sent back
michael@0:      * to the server via an Authorization/Proxy-Authorization header.
michael@0:      *
michael@0:      * This function may be called using a cached challenge provided the
michael@0:      * authenticator sets the REUSABLE_CHALLENGE flag.
michael@0:      *
michael@0:      * @param aChannel
michael@0:      *        the http channel requesting credentials
michael@0:      * @param aChallenge
michael@0:      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
michael@0:      *        server response header.  (possibly from the auth cache.)
michael@0:      * @param aProxyAuth
michael@0:      *        flag indicating whether or not aChallenge is from a proxy.
michael@0:      * @param aDomain
michael@0:      *        string containing the domain name (if appropriate)
michael@0:      * @param aUser
michael@0:      *        string containing the user name
michael@0:      * @param aPassword
michael@0:      *        string containing the password
michael@0:      * @param aSessionState
michael@0:      *        state stored along side the user's identity in the auth cache
michael@0:      *        for the lifetime of the browser session.  if a new auth cache
michael@0:      *        entry is created for this challenge, then this parameter will
michael@0:      *        be null.  on return, the result will be stored in the new auth
michael@0:      *        cache entry.  this parameter is non-null when an auth cache entry
michael@0:      *        is being reused.
michael@0:      * @param aContinuationState
michael@0:      *        state held by the channel between consecutive calls to
michael@0:      *        generateCredentials, assuming multiple calls are required
michael@0:      *        to authenticate.  this state is held for at most the lifetime of
michael@0:      *        the channel.
michael@0:      * @param aFlags
michael@0:      *        authenticator may return one of the generate flags bellow.
michael@0:      */
michael@0:     string generateCredentials(in    nsIHttpAuthenticableChannel aChannel,
michael@0:                                in    string         aChallenge,
michael@0:                                in    boolean        aProxyAuth,
michael@0:                                in    wstring        aDomain,
michael@0:                                in    wstring        aUser,
michael@0:                                in    wstring        aPassword,
michael@0:                                inout nsISupports    aSessionState,
michael@0:                                inout nsISupports    aContinuationState,
michael@0:                                out   unsigned long  aFlags);
michael@0: 
michael@0:     /**
michael@0:      * Generate flags
michael@0:      */
michael@0: 
michael@0:     /**
michael@0:      * Indicates that the authenticator has used an out-of-band or internal
michael@0:      * source of identity and tells the consumer that it must not cache
michael@0:      * the returned identity because it might not be valid and would overwrite
michael@0:      * the cached identity.  See bug 542318 comment 32.
michael@0:      */
michael@0:     const unsigned long USING_INTERNAL_IDENTITY = (1<<0);
michael@0: 
michael@0:     /**
michael@0:      * Flags defining various properties of the authenticator.
michael@0:      */
michael@0:     readonly attribute unsigned long authFlags;
michael@0: 
michael@0:     /**
michael@0:      * A request based authentication scheme only authenticates an individual
michael@0:      * request (or a set of requests under the same authentication domain as
michael@0:      * defined by RFC 2617).  BASIC and DIGEST are request based authentication
michael@0:      * schemes.
michael@0:      */
michael@0:     const unsigned long REQUEST_BASED = (1<<0);
michael@0: 
michael@0:     /**
michael@0:      * A connection based authentication scheme authenticates an individual
michael@0:      * connection.  Multiple requests may be issued over the connection without
michael@0:      * repeating the authentication steps.  Connection based authentication
michael@0:      * schemes can associate state with the connection being authenticated via
michael@0:      * the aContinuationState parameter (see generateCredentials).
michael@0:      */
michael@0:     const unsigned long CONNECTION_BASED = (1<<1);
michael@0: 
michael@0:     /**
michael@0:      * The credentials returned from generateCredentials may be reused with any
michael@0:      * other URLs within "the protection space" as defined by RFC 2617 section
michael@0:      * 1.2.  If this flag is not set, then generateCredentials must be called
michael@0:      * for each request within the protection space.  REUSABLE_CREDENTIALS
michael@0:      * implies REUSABLE_CHALLENGE.
michael@0:      */
michael@0:     const unsigned long REUSABLE_CREDENTIALS = (1<<2);
michael@0: 
michael@0:     /**
michael@0:      * A challenge may be reused to later generate credentials in anticipation
michael@0:      * of a duplicate server challenge for URLs within "the protection space"
michael@0:      * as defined by RFC 2617 section 1.2.
michael@0:      */
michael@0:     const unsigned long REUSABLE_CHALLENGE = (1<<3);
michael@0: 
michael@0:     /**
michael@0:      * This flag indicates that the identity of the user is not required by
michael@0:      * this authentication scheme.
michael@0:      */
michael@0:     const unsigned long IDENTITY_IGNORED = (1<<10);
michael@0: 
michael@0:     /**
michael@0:      * This flag indicates that the identity of the user includes a domain
michael@0:      * attribute that the user must supply.
michael@0:      */
michael@0:     const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
michael@0: 
michael@0:     /**
michael@0:      * This flag indicates that the identity will be sent encrypted. It does
michael@0:      * not make sense to combine this flag with IDENTITY_IGNORED.
michael@0:      */
michael@0:     const unsigned long IDENTITY_ENCRYPTED = (1<<12);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: #define NS_HTTP_AUTHENTICATOR_CONTRACTID_PREFIX \
michael@0:     "@mozilla.org/network/http-authenticator;1?scheme="
michael@0: %}