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