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