1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is Mozilla.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications.
19 * Portions created by the Initial Developer are Copyright (C) 2001
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Darin Fisher <darin@netscape.com> (original author)
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either the GNU General Public License Version 2 or later (the "GPL"), or
27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsISupports.idl"
40
41 interface nsIHttpChannel;
42
43 /**
44 * nsIHttpAuthenticator
45 *
46 * Interface designed to allow for pluggable HTTP authentication modules.
47 * Implementations are registered under the ContractID:
48 *
49 * "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
50 *
51 * where <auth-scheme> is the lower-cased value of the authentication scheme
52 * found in the server challenge per the rules of RFC 2617.
53 */
54 [scriptable, uuid(0f331436-8bc8-4c68-a124-d0253a19d06f)]
55 interface nsIHttpAuthenticator : nsISupports
56 {
57 /**
58 * Upon receipt of a server challenge, this function is called to determine
59 * whether or not the current user identity has been rejected. If true,
60 * then the user will be prompted by the channel to enter (or revise) their
61 * identity. Following this, generateCredentials will be called.
62 *
63 * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
64 * return value will be ignored, and user prompting will be suppressed.
65 *
66 * @param aChannel
67 * the http channel that received the challenge.
68 * @param aChallenge
69 * the challenge from the WWW-Authenticate/Proxy-Authenticate
70 * server response header. (possibly from the auth cache.)
71 * @param aProxyAuth
72 * flag indicating whether or not aChallenge is from a proxy.
73 * @param aSessionState
74 * see description below for generateCredentials.
75 * @param aContinuationState
76 * see description below for generateCredentials.
77 * @param aInvalidateIdentity
78 * return value indicating whether or not to prompt the user for a
79 * revised identity.
80 */
81 void challengeReceived(in nsIHttpChannel aChannel,
82 in string aChallenge,
83 in boolean aProxyAuth,
84 inout nsISupports aSessionState,
85 inout nsISupports aContinuationState,
86 out boolean aInvalidatesIdentity);
87
88 /**
89 * Called to generate the authentication credentials for a particular
90 * server/proxy challenge. This is the value that will be sent back
91 * to the server via an Authorization/Proxy-Authorization header.
92 *
93 * This function may be called using a cached challenge provided the
94 * authenticator sets the REUSABLE_CHALLENGE flag.
95 *
96 * @param aChannel
97 * the http channel requesting credentials
98 * @param aChallenge
99 * the challenge from the WWW-Authenticate/Proxy-Authenticate
100 * server response header. (possibly from the auth cache.)
101 * @param aProxyAuth
102 * flag indicating whether or not aChallenge is from a proxy.
103 * @param aDomain
104 * string containing the domain name (if appropriate)
105 * @param aUser
106 * string containing the user name
107 * @param aPassword
108 * string containing the password
109 * @param aSessionState
110 * state stored along side the user's identity in the auth cache
111 * for the lifetime of the browser session. if a new auth cache
112 * entry is created for this challenge, then this parameter will
113 * be null. on return, the result will be stored in the new auth
114 * cache entry. this parameter is non-null when an auth cache entry
115 * is being reused.
116 * @param aContinuationState
117 * state held by the channel between consecutive calls to
118 * generateCredentials, assuming multiple calls are required
119 * to authenticate. this state is held for at most the lifetime of
120 * the channel.
121 */
122 string generateCredentials(in nsIHttpChannel aChannel,
123 in string aChallenge,
124 in boolean aProxyAuth,
125 in wstring aDomain,
126 in wstring aUser,
127 in wstring aPassword,
128 inout nsISupports aSessionState,
129 inout nsISupports aContinuationState);
130
131 /**
132 * Flags defining various properties of the authenticator.
133 */
134 readonly attribute unsigned long authFlags;
135
136 /**
137 * A request based authentication scheme only authenticates an individual
138 * request (or a set of requests under the same authentication domain as
139 * defined by RFC 2617). BASIC and DIGEST are request based authentication
140 * schemes.
141 */
142 const unsigned long REQUEST_BASED = (1<<0);
143
144 /**
145 * A connection based authentication scheme authenticates an individual
146 * connection. Multiple requests may be issued over the connection without
147 * repeating the authentication steps. Connection based authentication
148 * schemes can associate state with the connection being authenticated via
149 * the aContinuationState parameter (see generateCredentials).
150 */
151 const unsigned long CONNECTION_BASED = (1<<1);
152
153 /**
154 * The credentials returned from generateCredentials may be reused with any
155 * other URLs within "the protection space" as defined by RFC 2617 section
156 * 1.2. If this flag is not set, then generateCredentials must be called
157 * for each request within the protection space. REUSABLE_CREDENTIALS
158 * implies REUSABLE_CHALLENGE.
159 */
160 const unsigned long REUSABLE_CREDENTIALS = (1<<2);
161
162 /**
163 * A challenge may be reused to later generate credentials in anticipation
164 * of a duplicate server challenge for URLs within "the protection space"
165 * as defined by RFC 2617 section 1.2.
166 */
167 const unsigned long REUSABLE_CHALLENGE = (1<<3);
168
169 /**
170 * This flag indicates that the identity of the user is not required by
171 * this authentication scheme.
172 */
173 const unsigned long IDENTITY_IGNORED = (1<<10);
174
175 /**
176 * This flag indicates that the identity of the user includes a domain
177 * attribute that the user must supply.
178 */
179 const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
180
181 /**
182 * This flag indicates that the identity will be sent encrypted. It does
183 * not make sense to combine this flag with IDENTITY_IGNORED.
184 */
185 const unsigned long IDENTITY_ENCRYPTED = (1<<12);
186 };
187
188 %{C++
189 #define NS_HTTP_AUTHENTICATOR_CONTRACTID_PREFIX \
190 "@mozilla.org/network/http-authenticator;1?scheme="
191 %}