nsIHttpAuthenticator.idl (10060B)
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/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIHttpAuthenticableChannel; 9 interface nsIHttpAuthenticatorCallback; 10 interface nsICancelable; 11 12 /** 13 * nsIHttpAuthenticator 14 * 15 * Interface designed to allow for pluggable HTTP authentication modules. 16 * Implementations are registered under the ContractID: 17 * 18 * "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>" 19 * 20 * where <auth-scheme> is the lower-cased value of the authentication scheme 21 * found in the server challenge per the rules of RFC 2617. 22 */ 23 [uuid(fef7db8a-a4e2-49d1-9685-19ed7e309b7d)] 24 interface nsIHttpAuthenticator : nsISupports 25 { 26 /** 27 * Upon receipt of a server challenge, this function is called to determine 28 * whether or not the current user identity has been rejected. If true, 29 * then the user will be prompted by the channel to enter (or revise) their 30 * identity. Following this, generateCredentials will be called. 31 * 32 * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity 33 * return value will be ignored, and user prompting will be suppressed. 34 * 35 * @param aChannel 36 * the http channel that received the challenge. 37 * @param aChallenge 38 * the challenge from the WWW-Authenticate/Proxy-Authenticate 39 * server response header. (possibly from the auth cache.) 40 * @param aProxyAuth 41 * flag indicating whether or not aChallenge is from a proxy. 42 * @param aSessionState 43 * see description below for generateCredentials. 44 * @param aContinuationState 45 * see description below for generateCredentials. 46 * @param aInvalidateIdentity 47 * return value indicating whether or not to prompt the user for a 48 * revised identity. 49 */ 50 [must_use] 51 void challengeReceived(in nsIHttpAuthenticableChannel aChannel, 52 in ACString aChallenge, 53 in boolean aProxyAuth, 54 inout nsISupports aSessionState, 55 inout nsISupports aContinuationState, 56 out boolean aInvalidatesIdentity); 57 58 /** 59 * Called to generate the authentication credentials for a particular 60 * server/proxy challenge asynchronously. Credentials will be sent back 61 * to the server via an Authorization/Proxy-Authorization header. 62 * 63 * @param aChannel 64 * the http channel requesting credentials 65 * @param aCallback 66 * callback function to be called when credentials are available 67 * @param aChallenge 68 * the challenge from the WWW-Authenticate/Proxy-Authenticate 69 * server response header. (possibly from the auth cache.) 70 * @param aProxyAuth 71 * flag indicating whether or not aChallenge is from a proxy. 72 * @param aDomain 73 * string containing the domain name (if appropriate) 74 * @param aUser 75 * string containing the user name 76 * @param aPassword 77 * string containing the password 78 * @param aSessionState 79 * state stored along side the user's identity in the auth cache 80 * for the lifetime of the browser session. if a new auth cache 81 * entry is created for this challenge, then this parameter will 82 * be null. on return, the result will be stored in the new auth 83 * cache entry. this parameter is non-null when an auth cache entry 84 * is being reused. currently modification of session state is not 85 * communicated to caller, thus caching credentials obtained by 86 * asynchronous way is not supported. 87 * @param aContinuationState 88 * state held by the channel between consecutive calls to 89 * generateCredentials, assuming multiple calls are required 90 * to authenticate. this state is held for at most the lifetime of 91 * the channel. 92 * @pram aCancel 93 * returns cancellable runnable object which caller can use to cancel 94 * calling aCallback when finished. 95 */ 96 [must_use] 97 void generateCredentialsAsync(in nsIHttpAuthenticableChannel aChannel, 98 in nsIHttpAuthenticatorCallback aCallback, 99 in ACString aChallenge, 100 in boolean aProxyAuth, 101 in AString aDomain, 102 in AString aUser, 103 in AString aPassword, 104 in nsISupports aSessionState, 105 in nsISupports aContinuationState, 106 out nsICancelable aCancel); 107 /** 108 * Called to generate the authentication credentials for a particular 109 * server/proxy challenge. This is the value that will be sent back 110 * to the server via an Authorization/Proxy-Authorization header. 111 * 112 * This function may be called using a cached challenge provided the 113 * authenticator sets the REUSABLE_CHALLENGE flag. 114 * 115 * @param aChannel 116 * the http channel requesting credentials 117 * @param aChallenge 118 * the challenge from the WWW-Authenticate/Proxy-Authenticate 119 * server response header. (possibly from the auth cache.) 120 * @param aProxyAuth 121 * flag indicating whether or not aChallenge is from a proxy. 122 * @param aDomain 123 * string containing the domain name (if appropriate) 124 * @param aUser 125 * string containing the user name 126 * @param aPassword 127 * string containing the password 128 * @param aSessionState 129 * state stored along side the user's identity in the auth cache 130 * for the lifetime of the browser session. if a new auth cache 131 * entry is created for this challenge, then this parameter will 132 * be null. on return, the result will be stored in the new auth 133 * cache entry. this parameter is non-null when an auth cache entry 134 * is being reused. 135 * @param aContinuationState 136 * state held by the channel between consecutive calls to 137 * generateCredentials, assuming multiple calls are required 138 * to authenticate. this state is held for at most the lifetime of 139 * the channel. 140 * @param aFlags 141 * authenticator may return one of the generate flags bellow. 142 */ 143 [must_use] 144 ACString generateCredentials(in nsIHttpAuthenticableChannel aChannel, 145 in ACString aChallenge, 146 in boolean aProxyAuth, 147 in AString aDomain, 148 in AString aUser, 149 in AString aPassword, 150 inout nsISupports aSessionState, 151 inout nsISupports aContinuationState, 152 out unsigned long aFlags); 153 154 /** 155 * Generate flags 156 */ 157 158 /** 159 * Indicates that the authenticator has used an out-of-band or internal 160 * source of identity and tells the consumer that it must not cache 161 * the returned identity because it might not be valid and would overwrite 162 * the cached identity. See bug 542318 comment 32. 163 */ 164 const unsigned long USING_INTERNAL_IDENTITY = (1<<0); 165 166 /** 167 * Flags defining various properties of the authenticator. 168 */ 169 [must_use] readonly attribute unsigned long authFlags; 170 171 /** 172 * A request based authentication scheme only authenticates an individual 173 * request (or a set of requests under the same authentication domain as 174 * defined by RFC 2617). BASIC and DIGEST are request based authentication 175 * schemes. 176 */ 177 const unsigned long REQUEST_BASED = (1<<0); 178 179 /** 180 * A connection based authentication scheme authenticates an individual 181 * connection. Multiple requests may be issued over the connection without 182 * repeating the authentication steps. Connection based authentication 183 * schemes can associate state with the connection being authenticated via 184 * the aContinuationState parameter (see generateCredentials). 185 */ 186 const unsigned long CONNECTION_BASED = (1<<1); 187 188 /** 189 * The credentials returned from generateCredentials may be reused with any 190 * other URLs within "the protection space" as defined by RFC 2617 section 191 * 1.2. If this flag is not set, then generateCredentials must be called 192 * for each request within the protection space. REUSABLE_CREDENTIALS 193 * implies REUSABLE_CHALLENGE. 194 */ 195 const unsigned long REUSABLE_CREDENTIALS = (1<<2); 196 197 /** 198 * A challenge may be reused to later generate credentials in anticipation 199 * of a duplicate server challenge for URLs within "the protection space" 200 * as defined by RFC 2617 section 1.2. 201 */ 202 const unsigned long REUSABLE_CHALLENGE = (1<<3); 203 204 /** 205 * This flag indicates that the identity of the user is not required by 206 * this authentication scheme. 207 */ 208 const unsigned long IDENTITY_IGNORED = (1<<10); 209 210 /** 211 * This flag indicates that the identity of the user includes a domain 212 * attribute that the user must supply. 213 */ 214 const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11); 215 216 /** 217 * This flag indicates that the identity will be sent encrypted. It does 218 * not make sense to combine this flag with IDENTITY_IGNORED. 219 */ 220 const unsigned long IDENTITY_ENCRYPTED = (1<<12); 221 };