1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_HTTP_HTTP_AUTH_HANDLER_H_ 6 #define NET_HTTP_HTTP_AUTH_HANDLER_H_ 7 8 #include <string> 9 10 #include "net/base/completion_callback.h" 11 #include "net/base/net_export.h" 12 #include "net/base/net_log.h" 13 #include "net/http/http_auth.h" 14 15 namespace net { 16 17 struct HttpRequestInfo; 18 19 // HttpAuthHandler is the interface for the authentication schemes 20 // (basic, digest, NTLM, Negotiate). 21 // HttpAuthHandler objects are typically created by an HttpAuthHandlerFactory. 22 class NET_EXPORT_PRIVATE HttpAuthHandler { 23 public: 24 HttpAuthHandler(); 25 virtual ~HttpAuthHandler(); 26 27 // Initializes the handler using a challenge issued by a server. 28 // |challenge| must be non-NULL and have already tokenized the 29 // authentication scheme, but none of the tokens occurring after the 30 // authentication scheme. |target| and |origin| are both stored 31 // for later use, and are not part of the initial challenge. 32 bool InitFromChallenge(HttpAuth::ChallengeTokenizer* challenge, 33 HttpAuth::Target target, 34 const GURL& origin, 35 const BoundNetLog& net_log); 36 37 // Determines how the previous authorization attempt was received. 38 // 39 // This is called when the server/proxy responds with a 401/407 after an 40 // earlier authorization attempt. Although this normally means that the 41 // previous attempt was rejected, in multi-round schemes such as 42 // NTLM+Negotiate it may indicate that another round of challenge+response 43 // is required. For Digest authentication it may also mean that the previous 44 // attempt used a stale nonce (and nonce-count) and that a new attempt should 45 // be made with a different nonce provided in the challenge. 46 // 47 // |challenge| must be non-NULL and have already tokenized the 48 // authentication scheme, but none of the tokens occurring after the 49 // authentication scheme. 50 virtual HttpAuth::AuthorizationResult HandleAnotherChallenge( 51 HttpAuth::ChallengeTokenizer* challenge) = 0; 52 53 // Generates an authentication token, potentially asynchronously. 54 // 55 // When |credentials| is NULL, the default credentials for the currently 56 // logged in user are used. |AllowsDefaultCredentials()| MUST be true in this 57 // case. 58 // 59 // |request|, |callback|, and |auth_token| must be non-NULL. 60 // 61 // The return value is a net error code. 62 // 63 // If |OK| is returned, |*auth_token| is filled in with an authentication 64 // token which can be inserted in the HTTP request. 65 // 66 // If |ERR_IO_PENDING| is returned, |*auth_token| will be filled in 67 // asynchronously and |callback| will be invoked. The lifetime of 68 // |request|, |callback|, and |auth_token| must last until |callback| is 69 // invoked, but |credentials| is only used during the initial call. 70 // 71 // All other return codes indicate that there was a problem generating a 72 // token, and the value of |*auth_token| is unspecified. 73 int GenerateAuthToken(const AuthCredentials* credentials, 74 const HttpRequestInfo* request, 75 const CompletionCallback& callback, 76 std::string* auth_token); 77 78 // The authentication scheme as an enumerated value. 79 HttpAuth::Scheme auth_scheme() const { 80 return auth_scheme_; 81 } 82 83 // The realm, encoded as UTF-8. This may be empty. 84 const std::string& realm() const { 85 return realm_; 86 } 87 88 // The challenge which was issued when creating the handler. 89 const std::string challenge() const { 90 return auth_challenge_; 91 } 92 93 // Numeric rank based on the challenge's security level. Higher 94 // numbers are better. Used by HttpAuth::ChooseBestChallenge(). 95 int score() const { 96 return score_; 97 } 98 99 HttpAuth::Target target() const { 100 return target_; 101 } 102 103 // Returns the proxy or server which issued the authentication challenge 104 // that this HttpAuthHandler is handling. The URL includes scheme, host, and 105 // port, but does not include path. 106 const GURL& origin() const { 107 return origin_; 108 } 109 110 // Returns true if the authentication scheme does not send the username and 111 // password in the clear. 112 bool encrypts_identity() const { 113 return (properties_ & ENCRYPTS_IDENTITY) != 0; 114 } 115 116 // Returns true if the authentication scheme is connection-based, for 117 // example, NTLM. A connection-based authentication scheme does not support 118 // preemptive authentication, and must use the same handler object 119 // throughout the life of an HTTP transaction. 120 bool is_connection_based() const { 121 return (properties_ & IS_CONNECTION_BASED) != 0; 122 } 123 124 // Returns true if the response to the current authentication challenge 125 // requires an identity. 126 // TODO(wtc): Find a better way to handle a multi-round challenge-response 127 // sequence used by a connection-based authentication scheme. 128 virtual bool NeedsIdentity(); 129 130 // Returns whether the default credentials may be used for the |origin| passed 131 // into |InitFromChallenge|. If true, the user does not need to be prompted 132 // for username and password to establish credentials. 133 // NOTE: SSO is a potential security risk. 134 // TODO(cbentzel): Add a pointer to Firefox documentation about risk. 135 virtual bool AllowsDefaultCredentials(); 136 137 // Returns whether explicit credentials can be used with this handler. If 138 // true the user may be prompted for credentials if an implicit identity 139 // cannot be determined. 140 virtual bool AllowsExplicitCredentials(); 141 142 protected: 143 enum Property { 144 ENCRYPTS_IDENTITY = 1 << 0, 145 IS_CONNECTION_BASED = 1 << 1, 146 }; 147 148 // Initializes the handler using a challenge issued by a server. 149 // |challenge| must be non-NULL and have already tokenized the 150 // authentication scheme, but none of the tokens occurring after the 151 // authentication scheme. 152 // Implementations are expected to initialize the following members: 153 // scheme_, realm_, score_, properties_ 154 virtual bool Init(HttpAuth::ChallengeTokenizer* challenge) = 0; 155 156 // |GenerateAuthTokenImpl()} is the auth-scheme specific implementation 157 // of generating the next auth token. Callers should use |GenerateAuthToken()| 158 // which will in turn call |GenerateAuthTokenImpl()| 159 virtual int GenerateAuthTokenImpl(const AuthCredentials* credentials, 160 const HttpRequestInfo* request, 161 const CompletionCallback& callback, 162 std::string* auth_token) = 0; 163 164 // The auth-scheme as an enumerated value. 165 HttpAuth::Scheme auth_scheme_; 166 167 // The realm, encoded as UTF-8. Used by "basic" and "digest". 168 std::string realm_; 169 170 // The auth challenge. 171 std::string auth_challenge_; 172 173 // The {scheme, host, port} for the authentication target. Used by "ntlm" 174 // and "negotiate" to construct the service principal name. 175 GURL origin_; 176 177 // The score for this challenge. Higher numbers are better. 178 int score_; 179 180 // Whether this authentication request is for a proxy server, or an 181 // origin server. 182 HttpAuth::Target target_; 183 184 // A bitmask of the properties of the authentication scheme. 185 int properties_; 186 187 BoundNetLog net_log_; 188 189 private: 190 void OnGenerateAuthTokenComplete(int rv); 191 void FinishGenerateAuthToken(); 192 193 CompletionCallback callback_; 194 }; 195 196 } // namespace net 197 198 #endif // NET_HTTP_HTTP_AUTH_HANDLER_H_ 199
