src/net/http/http_auth_handler.h

   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.
  80   HttpAuth::Scheme auth_scheme() const {
  81     return auth_scheme_;
  82   }
  83
  84   // The realm, encoded as UTF-8. This may be empty.
  85   const std::string& realm() const {
  86     return realm_;
  87   }
  88
  89   // The challenge which was issued when creating the handler.
  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().
  96   int score() const {
  97     return score_;
  98   }
  99
 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.
 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.
 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.
 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_