net/http/http_auth.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_H_
   6 #define NET_HTTP_HTTP_AUTH_H_
   7
   8 #include <set>
   9 #include <string>
  10
  11 #include "base/memory/scoped_ptr.h"
  12 #include "net/base/auth.h"
  13 #include "net/base/net_export.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 NET_EXPORT_PRIVATE 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     AUTHORIZATION_RESULT_DIFFERENT_REALM,  // The authorization
  57                                            // attempt was rejected,
  58                                            // but the realm associated
  59                                            // with the new challenge
  60                                            // is different from the
  61                                            // previous attempt.
  62   };
  63
  64   // Describes where the identity used for authentication came from.
  65   enum IdentitySource {
  66     // Came from nowhere -- the identity is not initialized.
  67     IDENT_SRC_NONE,
  68
  69     // The identity came from the auth cache, by doing a path-based
  70     // lookup (premptive authorization).
  71     IDENT_SRC_PATH_LOOKUP,
  72
  73     // The identity was extracted from a URL of the form:
  74     // http://<username>:<password>@host:port
  75     IDENT_SRC_URL,
  76
  77     // The identity was retrieved from the auth cache, by doing a
  78     // realm lookup.
  79     IDENT_SRC_REALM_LOOKUP,
  80
  81     // The identity was provided by RestartWithAuth -- it likely
  82     // came from a prompt (or maybe the password manager).
  83     IDENT_SRC_EXTERNAL,
  84
  85     // The identity used the default credentials for the computer,
  86     // on schemes that support single sign-on.
  87     IDENT_SRC_DEFAULT_CREDENTIALS,
  88   };
  89
  90   enum Scheme {
  91     AUTH_SCHEME_BASIC = 0,
  92     AUTH_SCHEME_DIGEST,
  93     AUTH_SCHEME_NTLM,
  94     AUTH_SCHEME_NEGOTIATE,
  95     AUTH_SCHEME_SPDYPROXY,
  96     AUTH_SCHEME_MOCK,
  97     AUTH_SCHEME_MAX,
  98   };
  99
 100   // Helper structure used by HttpNetworkTransaction to track
 101   // the current identity being used for authorization.
 102   struct Identity {
 103     Identity();
 104
 105     IdentitySource source;
 106     bool invalid;
 107     AuthCredentials credentials;
 108   };
 109
 110   // Get the name of the header containing the auth challenge
 111   // (either WWW-Authenticate or Proxy-Authenticate).
 112   static std::string GetChallengeHeaderName(Target target);
 113
 114   // Get the name of the header where the credentials go
 115   // (either Authorization or Proxy-Authorization).
 116   static std::string GetAuthorizationHeaderName(Target target);
 117
 118   // Returns a string representation of a Target value that can be used in log
 119   // messages.
 120   static std::string GetAuthTargetString(Target target);
 121
 122   // Returns a string representation of an authentication Scheme.
 123   static const char* SchemeToString(Scheme scheme);
 124
 125   // Iterate through the challenge headers, and pick the best one that
 126   // we support. Obtains the implementation class for handling the challenge,
 127   // and passes it back in |*handler|. If no supported challenge was found,
 128   // |*handler| is set to NULL.
 129   //
 130   // |disabled_schemes| is the set of schemes that we should not use.
 131   //
 132   // |origin| is used by the NTLM and Negotiation authentication scheme to
 133   // construct the service principal name.  It is ignored by other schemes.
 134   static void ChooseBestChallenge(
 135       HttpAuthHandlerFactory* http_auth_handler_factory,
 136       const HttpResponseHeaders* headers,
 137       Target target,
 138       const GURL& origin,
 139       const std::set<Scheme>& disabled_schemes,
 140       const BoundNetLog& net_log,
 141       scoped_ptr<HttpAuthHandler>* handler);
 142
 143   // Handle a 401/407 response from a server/proxy after a previous
 144   // authentication attempt. For connection-based authentication schemes, the
 145   // new response may be another round in a multi-round authentication sequence.
 146   // For request-based schemes, a 401/407 response is typically treated like a
 147   // rejection of the previous challenge, except in the Digest case when a
 148   // "stale" attribute is present.
 149   //
 150   // |handler| must be non-NULL, and is the HttpAuthHandler from the previous
 151   // authentication round.
 152   //
 153   // |headers| must be non-NULL and contain the new HTTP response.
 154   //
 155   // |target| specifies whether the authentication challenge response came
 156   // from a server or a proxy.
 157   //
 158   // |disabled_schemes| are the authentication schemes to ignore.
 159   //
 160   // |challenge_used| is the text of the authentication challenge used in
 161   // support of the returned AuthorizationResult. If no headers were used for
 162   // the result (for example, all headers have unknown authentication schemes),
 163   // the value is cleared.
 164   static AuthorizationResult HandleChallengeResponse(
 165       HttpAuthHandler* handler,
 166       const HttpResponseHeaders* headers,
 167       Target target,
 168       const std::set<Scheme>& disabled_schemes,
 169       std::string* challenge_used);
 170 };
 171
 172 }  // namespace net
 173
 174 #endif  // NET_HTTP_HTTP_AUTH_H_