net/http/http_auth_handler_factory.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_FACTORY_H_
   6 #define NET_HTTP_HTTP_AUTH_HANDLER_FACTORY_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/memory/scoped_ptr.h"
  13 #include "net/base/net_export.h"
  14 #include "net/http/http_auth.h"
  15 #include "net/http/url_security_manager.h"
  16
  17 class GURL;
  18
  19 namespace net {
  20
  21 class BoundNetLog;
  22 class HostResolver;
  23 class HttpAuthChallengeTokenizer;
  24 class HttpAuthHandler;
  25 class HttpAuthHandlerRegistryFactory;
  26
  27 // An HttpAuthHandlerFactory is used to create HttpAuthHandler objects.
  28 // The HttpAuthHandlerFactory object _must_ outlive any of the HttpAuthHandler
  29 // objects that it creates.
  30 class NET_EXPORT HttpAuthHandlerFactory {
  31  public:
  32   enum CreateReason {
  33     CREATE_CHALLENGE,     // Create a handler in response to a challenge.
  34     CREATE_PREEMPTIVE,    // Create a handler preemptively.
  35   };
  36
  37   HttpAuthHandlerFactory() : url_security_manager_(NULL) {}
  38   virtual ~HttpAuthHandlerFactory() {}
  39
  40   // Sets an URL security manager.  HttpAuthHandlerFactory doesn't own the URL
  41   // security manager, and the URL security manager should outlive this object.
  42   void set_url_security_manager(URLSecurityManager* url_security_manager) {
  43     url_security_manager_ = url_security_manager;
  44   }
  45
  46   // Retrieves the associated URL security manager.
  47   URLSecurityManager* url_security_manager() {
  48     return url_security_manager_;
  49   }
  50
  51   // Creates an HttpAuthHandler object based on the authentication
  52   // challenge specified by |*challenge|. |challenge| must point to a valid
  53   // non-NULL tokenizer.
  54   //
  55   // If an HttpAuthHandler object is successfully created it is passed back to
  56   // the caller through |*handler| and OK is returned.
  57   //
  58   // If |*challenge| specifies an unsupported authentication scheme, |*handler|
  59   // is set to NULL and ERR_UNSUPPORTED_AUTH_SCHEME is returned.
  60   //
  61   // If |*challenge| is improperly formed, |*handler| is set to NULL and
  62   // ERR_INVALID_RESPONSE is returned.
  63   //
  64   // |create_reason| indicates why the handler is being created. This is used
  65   // since NTLM and Negotiate schemes do not support preemptive creation.
  66   //
  67   // |digest_nonce_count| is specifically intended for the Digest authentication
  68   // scheme, and indicates the number of handlers generated for a particular
  69   // server nonce challenge.
  70   //
  71   // For the NTLM and Negotiate handlers:
  72   // If |origin| does not match the authentication method's filters for
  73   // the specified |target|, ERR_INVALID_AUTH_CREDENTIALS is returned.
  74   // NOTE: This will apply to ALL |origin| values if the filters are empty.
  75   //
  76   // |*challenge| should not be reused after a call to |CreateAuthHandler()|,
  77   virtual int CreateAuthHandler(HttpAuthChallengeTokenizer* challenge,
  78                                 HttpAuth::Target target,
  79                                 const GURL& origin,
  80                                 CreateReason create_reason,
  81                                 int digest_nonce_count,
  82                                 const BoundNetLog& net_log,
  83                                 scoped_ptr<HttpAuthHandler>* handler) = 0;
  84
  85   // Creates an HTTP authentication handler based on the authentication
  86   // challenge string |challenge|.
  87   // This is a convenience function which creates a ChallengeTokenizer for
  88   // |challenge| and calls |CreateAuthHandler|. See |CreateAuthHandler| for
  89   // more details on return values.
  90   int CreateAuthHandlerFromString(const std::string& challenge,
  91                                   HttpAuth::Target target,
  92                                   const GURL& origin,
  93                                   const BoundNetLog& net_log,
  94                                   scoped_ptr<HttpAuthHandler>* handler);
  95
  96   // Creates an HTTP authentication handler based on the authentication
  97   // challenge string |challenge|.
  98   // This is a convenience function which creates a ChallengeTokenizer for
  99   // |challenge| and calls |CreateAuthHandler|. See |CreateAuthHandler| for
 100   // more details on return values.
 101   int CreatePreemptiveAuthHandlerFromString(
 102       const std::string& challenge,
 103       HttpAuth::Target target,
 104       const GURL& origin,
 105       int digest_nonce_count,
 106       const BoundNetLog& net_log,
 107       scoped_ptr<HttpAuthHandler>* handler);
 108
 109   // Creates a standard HttpAuthHandlerRegistryFactory. The caller is
 110   // responsible for deleting the factory.
 111   // The default factory supports Basic, Digest, NTLM, and Negotiate schemes.
 112   //
 113   // |resolver| is used by the Negotiate authentication handler to perform
 114   // CNAME lookups to generate a Kerberos SPN for the server. It must be
 115   // non-NULL.  |resolver| must remain valid for the lifetime of the
 116   // HttpAuthHandlerRegistryFactory and any HttpAuthHandlers created by said
 117   // factory.
 118   static HttpAuthHandlerRegistryFactory* CreateDefault(HostResolver* resolver);
 119
 120  private:
 121   // The URL security manager
 122   URLSecurityManager* url_security_manager_;
 123
 124   DISALLOW_COPY_AND_ASSIGN(HttpAuthHandlerFactory);
 125 };
 126
 127 // The HttpAuthHandlerRegistryFactory dispatches create requests out
 128 // to other factories based on the auth scheme.
 129 class NET_EXPORT HttpAuthHandlerRegistryFactory
 130     : public HttpAuthHandlerFactory {
 131  public:
 132   HttpAuthHandlerRegistryFactory();
 133   virtual ~HttpAuthHandlerRegistryFactory();
 134
 135   // Sets an URL security manager into the factory associated with |scheme|.
 136   void SetURLSecurityManager(const std::string& scheme,
 137                              URLSecurityManager* url_security_manager);
 138
 139   // Registers a |factory| that will be used for a particular HTTP
 140   // authentication scheme such as Basic, Digest, or Negotiate.
 141   // The |*factory| object is assumed to be new-allocated, and its lifetime
 142   // will be managed by this HttpAuthHandlerRegistryFactory object (including
 143   // deleting it when it is no longer used.
 144   // A NULL |factory| value means that HttpAuthHandlers's will not be created
 145   // for |scheme|. If a factory object used to exist for |scheme|, it will be
 146   // deleted.
 147   void RegisterSchemeFactory(const std::string& scheme,
 148                              HttpAuthHandlerFactory* factory);
 149
 150   // Retrieve the factory for the specified |scheme|. If no factory exists
 151   // for the |scheme|, NULL is returned. The returned factory must not be
 152   // deleted by the caller, and it is guaranteed to be valid until either
 153   // a new factory is registered for the same scheme, or until this
 154   // registry factory is destroyed.
 155   HttpAuthHandlerFactory* GetSchemeFactory(const std::string& scheme) const;
 156
 157   // Creates an HttpAuthHandlerRegistryFactory.
 158   //
 159   // |supported_schemes| is a list of authentication schemes. Valid values
 160   // include "basic", "digest", "ntlm", and "negotiate", where case matters.
 161   //
 162   // |security_manager| is used by the NTLM and Negotiate authenticators
 163   // to determine which servers Integrated Authentication can be used with. If
 164   // NULL, Integrated Authentication will not be used with any server.
 165   //
 166   // |host_resolver| is used by the Negotiate authentication handler to perform
 167   // CNAME lookups to generate a Kerberos SPN for the server. If the "negotiate"
 168   // scheme is used and |negotiate_disable_cname_lookup| is false,
 169   // |host_resolver| must not be NULL.
 170   //
 171   // |gssapi_library_name| specifies the name of the GSSAPI library that will
 172   // be loaded on all platforms except Windows.
 173   //
 174   // |negotiate_disable_cname_lookup| and |negotiate_enable_port| both control
 175   // how Negotiate does SPN generation, by default these should be false.
 176   static HttpAuthHandlerRegistryFactory* Create(
 177       const std::vector<std::string>& supported_schemes,
 178       URLSecurityManager* security_manager,
 179       HostResolver* host_resolver,
 180       const std::string& gssapi_library_name,
 181       bool negotiate_disable_cname_lookup,
 182       bool negotiate_enable_port);
 183
 184   // Creates an auth handler by dispatching out to the registered factories
 185   // based on the first token in |challenge|.
 186   virtual int CreateAuthHandler(HttpAuthChallengeTokenizer* challenge,
 187                                 HttpAuth::Target target,
 188                                 const GURL& origin,
 189                                 CreateReason reason,
 190                                 int digest_nonce_count,
 191                                 const BoundNetLog& net_log,
 192                                 scoped_ptr<HttpAuthHandler>* handler) OVERRIDE;
 193
 194  private:
 195   typedef std::map<std::string, HttpAuthHandlerFactory*> FactoryMap;
 196
 197   FactoryMap factory_map_;
 198   DISALLOW_COPY_AND_ASSIGN(HttpAuthHandlerRegistryFactory);
 199 };
 200
 201 }  // namespace net
 202
 203 #endif  // NET_HTTP_HTTP_AUTH_HANDLER_FACTORY_H_