netwerk/protocol/http/nsIHttpAuthenticator.idl@deefc01c0e14
netwerk/protocol/http/nsIHttpAuthenticator.idl
Thu, 15 Jan 2015 21:03:48 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 15 Jan 2015 21:03:48 +0100
- branch
- TOR_BUG_9701
- changeset 11
- deefc01c0e14
- permissions
- -rw-r--r--
Integrate friendly tips from Tor colleagues to make (or not) 4.5 alpha 3;
This includes removal of overloaded (but unused) methods, and addition of
a overlooked call to DataStruct::SetData(nsISupports, uint32_t, bool.)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsIHttpAuthenticableChannel;
10 /**
11 * nsIHttpAuthenticator
12 *
13 * Interface designed to allow for pluggable HTTP authentication modules.
14 * Implementations are registered under the ContractID:
15 *
16 * "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
17 *
18 * where <auth-scheme> is the lower-cased value of the authentication scheme
19 * found in the server challenge per the rules of RFC 2617.
20 */
21 [scriptable, uuid(16784db0-fcb1-4352-b0c9-6a3a67e3cf79)]
22 interface nsIHttpAuthenticator : nsISupports
23 {
24 /**
25 * Upon receipt of a server challenge, this function is called to determine
26 * whether or not the current user identity has been rejected. If true,
27 * then the user will be prompted by the channel to enter (or revise) their
28 * identity. Following this, generateCredentials will be called.
29 *
30 * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
31 * return value will be ignored, and user prompting will be suppressed.
32 *
33 * @param aChannel
34 * the http channel that received the challenge.
35 * @param aChallenge
36 * the challenge from the WWW-Authenticate/Proxy-Authenticate
37 * server response header. (possibly from the auth cache.)
38 * @param aProxyAuth
39 * flag indicating whether or not aChallenge is from a proxy.
40 * @param aSessionState
41 * see description below for generateCredentials.
42 * @param aContinuationState
43 * see description below for generateCredentials.
44 * @param aInvalidateIdentity
45 * return value indicating whether or not to prompt the user for a
46 * revised identity.
47 */
48 void challengeReceived(in nsIHttpAuthenticableChannel aChannel,
49 in string aChallenge,
50 in boolean aProxyAuth,
51 inout nsISupports aSessionState,
52 inout nsISupports aContinuationState,
53 out boolean aInvalidatesIdentity);
55 /**
56 * Called to generate the authentication credentials for a particular
57 * server/proxy challenge. This is the value that will be sent back
58 * to the server via an Authorization/Proxy-Authorization header.
59 *
60 * This function may be called using a cached challenge provided the
61 * authenticator sets the REUSABLE_CHALLENGE flag.
62 *
63 * @param aChannel
64 * the http channel requesting credentials
65 * @param aChallenge
66 * the challenge from the WWW-Authenticate/Proxy-Authenticate
67 * server response header. (possibly from the auth cache.)
68 * @param aProxyAuth
69 * flag indicating whether or not aChallenge is from a proxy.
70 * @param aDomain
71 * string containing the domain name (if appropriate)
72 * @param aUser
73 * string containing the user name
74 * @param aPassword
75 * string containing the password
76 * @param aSessionState
77 * state stored along side the user's identity in the auth cache
78 * for the lifetime of the browser session. if a new auth cache
79 * entry is created for this challenge, then this parameter will
80 * be null. on return, the result will be stored in the new auth
81 * cache entry. this parameter is non-null when an auth cache entry
82 * is being reused.
83 * @param aContinuationState
84 * state held by the channel between consecutive calls to
85 * generateCredentials, assuming multiple calls are required
86 * to authenticate. this state is held for at most the lifetime of
87 * the channel.
88 * @param aFlags
89 * authenticator may return one of the generate flags bellow.
90 */
91 string generateCredentials(in nsIHttpAuthenticableChannel aChannel,
92 in string aChallenge,
93 in boolean aProxyAuth,
94 in wstring aDomain,
95 in wstring aUser,
96 in wstring aPassword,
97 inout nsISupports aSessionState,
98 inout nsISupports aContinuationState,
99 out unsigned long aFlags);
101 /**
102 * Generate flags
103 */
105 /**
106 * Indicates that the authenticator has used an out-of-band or internal
107 * source of identity and tells the consumer that it must not cache
108 * the returned identity because it might not be valid and would overwrite
109 * the cached identity. See bug 542318 comment 32.
110 */
111 const unsigned long USING_INTERNAL_IDENTITY = (1<<0);
113 /**
114 * Flags defining various properties of the authenticator.
115 */
116 readonly attribute unsigned long authFlags;
118 /**
119 * A request based authentication scheme only authenticates an individual
120 * request (or a set of requests under the same authentication domain as
121 * defined by RFC 2617). BASIC and DIGEST are request based authentication
122 * schemes.
123 */
124 const unsigned long REQUEST_BASED = (1<<0);
126 /**
127 * A connection based authentication scheme authenticates an individual
128 * connection. Multiple requests may be issued over the connection without
129 * repeating the authentication steps. Connection based authentication
130 * schemes can associate state with the connection being authenticated via
131 * the aContinuationState parameter (see generateCredentials).
132 */
133 const unsigned long CONNECTION_BASED = (1<<1);
135 /**
136 * The credentials returned from generateCredentials may be reused with any
137 * other URLs within "the protection space" as defined by RFC 2617 section
138 * 1.2. If this flag is not set, then generateCredentials must be called
139 * for each request within the protection space. REUSABLE_CREDENTIALS
140 * implies REUSABLE_CHALLENGE.
141 */
142 const unsigned long REUSABLE_CREDENTIALS = (1<<2);
144 /**
145 * A challenge may be reused to later generate credentials in anticipation
146 * of a duplicate server challenge for URLs within "the protection space"
147 * as defined by RFC 2617 section 1.2.
148 */
149 const unsigned long REUSABLE_CHALLENGE = (1<<3);
151 /**
152 * This flag indicates that the identity of the user is not required by
153 * this authentication scheme.
154 */
155 const unsigned long IDENTITY_IGNORED = (1<<10);
157 /**
158 * This flag indicates that the identity of the user includes a domain
159 * attribute that the user must supply.
160 */
161 const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
163 /**
164 * This flag indicates that the identity will be sent encrypted. It does
165 * not make sense to combine this flag with IDENTITY_IGNORED.
166 */
167 const unsigned long IDENTITY_ENCRYPTED = (1<<12);
168 };
170 %{C++
171 #define NS_HTTP_AUTHENTICATOR_CONTRACTID_PREFIX \
172 "@mozilla.org/network/http-authenticator;1?scheme="
173 %}
