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/http/http_auth.h"
  13 #include "net/log/net_log.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 { return auth_challenge_; }
  91
  92   // Numeric rank based on the challenge's security level. Higher
  93   // numbers are better. Used by HttpAuth::ChooseBestChallenge().
  94   int score() const {
  95     return score_;
  96   }
  97
  98   HttpAuth::Target target() const {
  99     return target_;
 100   }
 101
 102   // Returns the proxy or server which issued the authentication challenge
 103   // that this HttpAuthHandler is handling. The URL includes scheme, host, and
 104   // port, but does not include path.
 105   const GURL& origin() const {
 106     return origin_;
 107   }
 108
 109   // Returns true if the authentication scheme does not send the username and
 110   // password in the clear.
 111   bool encrypts_identity() const {
 112     return (properties_ & ENCRYPTS_IDENTITY) != 0;
 113   }
 114
 115   // Returns true if the authentication scheme is connection-based, for
 116   // example, NTLM.  A connection-based authentication scheme does not support
 117   // preemptive authentication, and must use the same handler object
 118   // throughout the life of an HTTP transaction.
 119   bool is_connection_based() const {
 120     return (properties_ & IS_CONNECTION_BASED) != 0;
 121   }
 122
 123   // Returns true if the response to the current authentication challenge
 124   // requires an identity.
 125   // TODO(wtc): Find a better way to handle a multi-round challenge-response
 126   // sequence used by a connection-based authentication scheme.
 127   virtual bool NeedsIdentity();
 128
 129   // Returns whether the default credentials may be used for the |origin| passed
 130   // into |InitFromChallenge|. If true, the user does not need to be prompted
 131   // for username and password to establish credentials.
 132   // NOTE: SSO is a potential security risk.
 133   // TODO(cbentzel): Add a pointer to Firefox documentation about risk.
 134   virtual bool AllowsDefaultCredentials();
 135
 136   // Returns whether explicit credentials can be used with this handler.  If
 137   // true the user may be prompted for credentials if an implicit identity
 138   // cannot be determined.
 139   virtual bool AllowsExplicitCredentials();
 140
 141  protected:
 142   enum Property {
 143     ENCRYPTS_IDENTITY = 1 << 0,
 144     IS_CONNECTION_BASED = 1 << 1,
 145   };
 146
 147   // Initializes the handler using a challenge issued by a server.
 148   // |challenge| must be non-NULL and have already tokenized the
 149   // authentication scheme, but none of the tokens occurring after the
 150   // authentication scheme.
 151   // Implementations are expected to initialize the following members:
 152   // scheme_, realm_, score_, properties_
 153   virtual bool Init(HttpAuthChallengeTokenizer* challenge) = 0;
 154
 155   // |GenerateAuthTokenImpl()} is the auth-scheme specific implementation
 156   // of generating the next auth token. Callers should use |GenerateAuthToken()|
 157   // which will in turn call |GenerateAuthTokenImpl()|
 158   virtual int GenerateAuthTokenImpl(const AuthCredentials* credentials,
 159                                     const HttpRequestInfo* request,
 160                                     const CompletionCallback& callback,
 161                                     std::string* auth_token) = 0;
 162
 163   // The auth-scheme as an enumerated value.
 164   HttpAuth::Scheme auth_scheme_;
 165
 166   // The realm, encoded as UTF-8. Used by "basic" and "digest".
 167   std::string realm_;
 168
 169   // The auth challenge.
 170   std::string auth_challenge_;
 171
 172   // The {scheme, host, port} for the authentication target.  Used by "ntlm"
 173   // and "negotiate" to construct the service principal name.
 174   GURL origin_;
 175
 176   // The score for this challenge. Higher numbers are better.
 177   int score_;
 178
 179   // Whether this authentication request is for a proxy server, or an
 180   // origin server.
 181   HttpAuth::Target target_;
 182
 183   // A bitmask of the properties of the authentication scheme.
 184   int properties_;
 185
 186   BoundNetLog net_log_;
 187
 188  private:
 189   void OnGenerateAuthTokenComplete(int rv);
 190   void FinishGenerateAuthToken();
 191
 192   CompletionCallback callback_;
 193 };
 194
 195 }  // namespace net
 196
 197 #endif  // NET_HTTP_HTTP_AUTH_HANDLER_H_