net/http/http_auth.h

   1 // Copyright (c) 2010 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_H_
   6 #define NET_HTTP_HTTP_AUTH_H_
   7 #pragma once
   8
   9 #include <set>
  10 #include <string>
  11
  12 #include "base/scoped_ptr.h"
  13 #include "base/string16.h"
  14 #include "net/http/http_util.h"
  15
  16 template <class T> class scoped_refptr;
  17
  18 namespace net {
  19
  20 class BoundNetLog;
  21 class HttpAuthHandler;
  22 class HttpAuthHandlerFactory;
  23 class HttpResponseHeaders;
  24
  25 // Utility class for http authentication.
  26 class HttpAuth {
  27  public:
  28   // Http authentication can be done the the proxy server, origin server,
  29   // or both. This enum tracks who the target is.
  30   enum Target {
  31     AUTH_NONE = -1,
  32     // We depend on the valid targets (!= AUTH_NONE) being usable as indexes
  33     // in an array, so start from 0.
  34     AUTH_PROXY = 0,
  35     AUTH_SERVER = 1,
  36     AUTH_NUM_TARGETS = 2,
  37   };
  38
  39   // What the HTTP WWW-Authenticate/Proxy-Authenticate headers indicate about
  40   // the previous authorization attempt.
  41   enum AuthorizationResult {
  42     AUTHORIZATION_RESULT_ACCEPT,   // The authorization attempt was accepted,
  43                                    // although there still may be additional
  44                                    // rounds of challenges.
  45
  46     AUTHORIZATION_RESULT_REJECT,   // The authorization attempt was rejected.
  47
  48     AUTHORIZATION_RESULT_STALE,    // (Digest) The nonce used in the
  49                                    // authorization attempt is stale, but
  50                                    // otherwise the attempt was valid.
  51
  52     AUTHORIZATION_RESULT_INVALID,  // The authentication challenge headers are
  53                                    // poorly formed (the authorization attempt
  54                                    // itself may have been fine).
  55   };
  56
  57   // Describes where the identity used for authentication came from.
  58   enum IdentitySource {
  59     // Came from nowhere -- the identity is not initialized.
  60     IDENT_SRC_NONE,
  61
  62     // The identity came from the auth cache, by doing a path-based
  63     // lookup (premptive authorization).
  64     IDENT_SRC_PATH_LOOKUP,
  65
  66     // The identity was extracted from a URL of the form:
  67     // http://<username>:<password>@host:port
  68     IDENT_SRC_URL,
  69
  70     // The identity was retrieved from the auth cache, by doing a
  71     // realm lookup.
  72     IDENT_SRC_REALM_LOOKUP,
  73
  74     // The identity was provided by RestartWithAuth -- it likely
  75     // came from a prompt (or maybe the password manager).
  76     IDENT_SRC_EXTERNAL,
  77
  78     // The identity used the default credentials for the computer,
  79     // on schemes that support single sign-on.
  80     IDENT_SRC_DEFAULT_CREDENTIALS,
  81   };
  82
  83   // Helper structure used by HttpNetworkTransaction to track
  84   // the current identity being used for authorization.
  85   struct Identity {
  86     Identity();
  87
  88     IdentitySource source;
  89     bool invalid;
  90     string16 username;
  91     string16 password;
  92   };
  93
  94   // Get the name of the header containing the auth challenge
  95   // (either WWW-Authenticate or Proxy-Authenticate).
  96   static std::string GetChallengeHeaderName(Target target);
  97
  98   // Get the name of the header where the credentials go
  99   // (either Authorization or Proxy-Authorization).
 100   static std::string GetAuthorizationHeaderName(Target target);
 101
 102   // Returns a string representation of a Target value that can be used in log
 103   // messages.
 104   static std::string GetAuthTargetString(Target target);
 105
 106   // Iterate through the challenge headers, and pick the best one that
 107   // we support. Obtains the implementation class for handling the challenge,
 108   // and passes it back in |*handler|. If no supported challenge was found,
 109   // |*handler| is set to NULL.
 110   //
 111   // |disabled_schemes| is the set of schemes that we should not use.
 112   //
 113   // |origin| is used by the NTLM and Negotiation authentication scheme to
 114   // construct the service principal name.  It is ignored by other schemes.
 115   static void ChooseBestChallenge(
 116       HttpAuthHandlerFactory* http_auth_handler_factory,
 117       const HttpResponseHeaders* headers,
 118       Target target,
 119       const GURL& origin,
 120       const std::set<std::string>& disabled_schemes,
 121       const BoundNetLog& net_log,
 122       scoped_ptr<HttpAuthHandler>* handler);
 123
 124   // Handle a 401/407 response from a server/proxy after a previous
 125   // authentication attempt. For connection-based authentication schemes, the
 126   // new response may be another round in a multi-round authentication sequence.
 127   // For request-based schemes, a 401/407 response is typically treated like a
 128   // rejection of the previous challenge, except in the Digest case when a
 129   // "stale" attribute is present.
 130   //
 131   // |handler| must be non-NULL, and is the HttpAuthHandler from the previous
 132   // authentication round.
 133   //
 134   // |headers| must be non-NULL and contain the new HTTP response.
 135   //
 136   // |target| specifies whether the authentication challenge response came
 137   // from a server or a proxy.
 138   //
 139   // |disabled_schemes| are the authentication schemes to ignore.
 140   //
 141   // |challenge_used| is the text of the authentication challenge used in
 142   // support of the returned AuthorizationResult. If no headers were used for
 143   // the result (for example, all headers have unknown authentication schemes),
 144   // the value is cleared.
 145   static AuthorizationResult HandleChallengeResponse(
 146       HttpAuthHandler* handler,
 147       const HttpResponseHeaders* headers,
 148       Target target,
 149       const std::set<std::string>& disabled_schemes,
 150       std::string* challenge_used);
 151
 152   // Breaks up a challenge string into the the auth scheme and parameter list,
 153   // according to RFC 2617 Sec 1.2:
 154   //    challenge = auth-scheme 1*SP 1#auth-param
 155   //
 156   // Depending on the challenge scheme, it may be appropriate to interpret the
 157   // parameters as either a base-64 encoded string or a comma-delimited list
 158   // of name-value pairs. param_pairs() and base64_param() methods are provided
 159   // to support either usage.
 160   class ChallengeTokenizer {
 161    public:
 162     ChallengeTokenizer(std::string::const_iterator begin,
 163                        std::string::const_iterator end)
 164         : begin_(begin),
 165           end_(end),
 166           scheme_begin_(begin),
 167           scheme_end_(begin),
 168           params_begin_(end),
 169           params_end_(end) {
 170       Init(begin, end);
 171     }
 172
 173     // Get the original text.
 174     std::string challenge_text() const {
 175       return std::string(begin_, end_);
 176     }
 177
 178     // Get the auth scheme of the challenge.
 179     std::string::const_iterator scheme_begin() const { return scheme_begin_; }
 180     std::string::const_iterator scheme_end() const { return scheme_end_; }
 181     std::string scheme() const {
 182       return std::string(scheme_begin_, scheme_end_);
 183     }
 184
 185     HttpUtil::NameValuePairsIterator param_pairs() const;
 186     std::string base64_param() const;
 187
 188    private:
 189     void Init(std::string::const_iterator begin,
 190               std::string::const_iterator end);
 191
 192     std::string::const_iterator begin_;
 193     std::string::const_iterator end_;
 194
 195     std::string::const_iterator scheme_begin_;
 196     std::string::const_iterator scheme_end_;
 197
 198     std::string::const_iterator params_begin_;
 199     std::string::const_iterator params_end_;
 200   };
 201 };
 202
 203 }  // namespace net
 204
 205 #endif  // NET_HTTP_HTTP_AUTH_H_