1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3 * The contents of this file are subject to the Mozilla Public
4 * License Version 1.1 (the "License"); you may not use this file
5 * except in compliance with the License. You may obtain a copy of
6 * the License at http://www.mozilla.org/MPL/
8 * Software distributed under the License is distributed on an "AS
9 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
10 * implied. See the License for the specific language governing
11 * rights and limitations under the License.
13 * The Original Code is Mozilla.
15 * The Initial Developer of the Original Code is Netscape
16 * Communications. Portions created by Netscape Communications are
17 * Copyright (C) 2001 by Netscape Communications. All
21 * Darin Fisher <darin@netscape.com> (original author)
24 #include "nsISupports.idl"
26 #include "nsIHttpChannel.idl"
29 * nsIHttpAuthenticator
31 * Interface designed to allow for pluggable HTTP authentication modules.
32 * Implementations are registered under the ContractID:
34 * "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
36 * where <auth-scheme> is the lower-cased value of the authentication scheme
37 * found in the server challenge per the rules of RFC 2617.
39 [scriptable, uuid(0f331436-8bc8-4c68-a124-d0253a19d06f)]
40 interface nsIHttpAuthenticator: nsISupports
43 * Upon receipt of a server challenge, this function is called to determine
44 * whether or not the current user identity has been rejected. If true,
45 * then the user will be prompted by the channel to enter (or revise) their
46 * identity. Following this, generateCredentials will be called.
48 * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
49 * return value will be ignored, and user prompting will be suppressed.
52 * the http channel that received the challenge.
54 * the challenge from the WWW-Authenticate/Proxy-Authenticate
55 * server response header. (possibly from the auth cache.)
57 * flag indicating whether or not aChallenge is from a proxy.
58 * @param aSessionState
59 * see description below for generateCredentials.
60 * @param aContinuationState
61 * see description below for generateCredentials.
62 * @param aInvalidateIdentity
63 * return value indicating whether or not to prompt the user for a
66 void challengeReceived(in nsIHttpChannel aChannel,
68 in boolean aProxyAuth,
69 inout nsISupports aSessionState,
70 inout nsISupports aContinuationState,
71 out boolean aInvalidatesIdentity);
74 * Called to generate the authentication credentials for a particular
75 * server/proxy challenge. This is the value that will be sent back
76 * to the server via an Authorization/Proxy-Authorization header.
78 * This function may be called using a cached challenge provided the
79 * authenticator sets the REUSABLE_CHALLENGE flag.
82 * the http channel requesting credentials
84 * the challenge from the WWW-Authenticate/Proxy-Authenticate
85 * server response header. (possibly from the auth cache.)
87 * flag indicating whether or not aChallenge is from a proxy.
89 * string containing the domain name (if appropriate)
91 * string containing the user name
93 * string containing the password
94 * @param aSessionState
95 * state stored along side the user's identity in the auth cache
96 * for the lifetime of the browser session. if a new auth cache
97 * entry is created for this challenge, then this parameter will
98 * be null. on return, the result will be stored in the new auth
99 * cache entry. this parameter is non-null when an auth cache entry
101 * @param aContinuationState
102 * state held by the channel between consecutive calls to
103 * generateCredentials, assuming multiple calls are required
104 * to authenticate. this state is held for at most the lifetime of
107 string generateCredentials(in nsIHttpChannel aChannel,
108 in string aChallenge,
109 in boolean aProxyAuth,
112 in wstring aPassword,
113 inout nsISupports aSessionState,
114 inout nsISupports aContinuationState);
117 * Flags defining various properties of the authenticator.
119 readonly attribute unsigned long authFlags;
122 * A request based authentication scheme only authenticates an individual
123 * request (or a set of requests under the same authentication domain as
124 * defined by RFC 2617). BASIC and DIGEST are request based authentication
127 const unsigned long REQUEST_BASED = (1<<0);
130 * A connection based authentication scheme authenticates an individual
131 * connection. Multiple requests may be issued over the connection without
132 * repeating the authentication steps. Connection based authentication
133 * schemes can associate state with the connection being authenticated via
134 * the aContinuationState parameter (see generateCredentials).
136 const unsigned long CONNECTION_BASED = (1<<1);
139 * The credentials returned from generateCredentials may be reused with any
140 * other URLs within "the protection space" as defined by RFC 2617 section
141 * 1.2. If this flag is not set, then generateCredentials must be called
142 * for each request within the protection space. REUSABLE_CREDENTIALS
143 * implies REUSABLE_CHALLENGE.
145 const unsigned long REUSABLE_CREDENTIALS = (1<<2);
148 * A challenge may be reused to later generate credentials in anticipation
149 * of a duplicate server challenge for URLs within "the protection space"
150 * as defined by RFC 2617 section 1.2.
152 const unsigned long REUSABLE_CHALLENGE = (1<<3);
155 * This flag indicates that the identity of the user is not required by
156 * this authentication scheme.
158 const unsigned long IDENTITY_IGNORED = (1<<10);
161 * This flag indicates that the identity of the user includes a domain
162 * attribute that the user must supply.
164 const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);