Home | History | Annotate | Download | only in http 
      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_HANDLER_H_
      6 #define NET_HTTP_HTTP_AUTH_HANDLER_H_
      7 #pragma once
      8 
      9 #include <string>
     10 
     11 #include "base/string16.h"
     12 #include "net/base/completion_callback.h"
     13 #include "net/base/net_log.h"
     14 #include "net/http/http_auth.h"
     15 
     16 namespace net {
     17 
     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 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 occuring 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(HttpAuth::ChallengeTokenizer* 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 occuring after the
     50   // authentication scheme.
     51   virtual HttpAuth::AuthorizationResult HandleAnotherChallenge(
     52       HttpAuth::ChallengeTokenizer* challenge) = 0;
     53 
     54   // Generates an authentication token, potentially asynchronously.
     55   //
     56   // When |username| and |password| are NULL, the default credentials for
     57   // the currently logged in user are used. |AllowsDefaultCredentials()| MUST be
     58   // true in this case.
     59   //
     60   // |request|, |callback|, and |auth_token| must be non-NULL.
     61   //
     62   // The return value is a net error code.
     63   // If |OK| is returned, |*auth_token| is filled in with an authentication
     64   // token which can be inserted in the HTTP request.
     65   // If |ERR_IO_PENDING| is returned, |*auth_token| will be filled in
     66   // asynchronously and |callback| will be invoked. The lifetime of
     67   // |request|, |callback|, and |auth_token| must last until |callback| is
     68   // invoked, but |username| and |password| are only used during the initial
     69   // call.
     70   // Otherwise, there was a problem generating a token synchronously, and the
     71   // value of |*auth_token| is unspecified.
     72   int GenerateAuthToken(const string16* username,
     73                         const string16* password,
     74                         const HttpRequestInfo* request,
     75                         CompletionCallback* callback,
     76                         std::string* auth_token);
     77 
     78   // The authentication scheme as an enumerated value.
     79   HttpAuth::Scheme auth_scheme() const {
     80     return auth_scheme_;
     81   }
     82 
     83   // The realm value that was parsed during Init().
     84   const std::string& realm() const {
     85     return realm_;
     86   }
     87 
     88   // The challenge which was issued when creating the handler.
     89   const std::string challenge() const {
     90     return auth_challenge_;
     91   }
     92 
     93   // Numeric rank based on the challenge's security level. Higher
     94   // numbers are better. Used by HttpAuth::ChooseBestChallenge().
     95   int score() const {
     96     return score_;
     97   }
     98 
     99   HttpAuth::Target target() const {
    100     return target_;
    101   }
    102 
    103   // Returns the proxy or server which issued the authentication challenge
    104   // that this HttpAuthHandler is handling. The URL includes scheme, host, and
    105   // port, but does not include path.
    106   const GURL& origin() const {
    107     return origin_;
    108   }
    109 
    110   // Returns true if the authentication scheme does not send the username and
    111   // password in the clear.
    112   bool encrypts_identity() const {
    113     return (properties_ & ENCRYPTS_IDENTITY) != 0;
    114   }
    115 
    116   // Returns true if the authentication scheme is connection-based, for
    117   // example, NTLM.  A connection-based authentication scheme does not support
    118   // preemptive authentication, and must use the same handler object
    119   // throughout the life of an HTTP transaction.
    120   bool is_connection_based() const {
    121     return (properties_ & IS_CONNECTION_BASED) != 0;
    122   }
    123 
    124   // Returns true if the response to the current authentication challenge
    125   // requires an identity.
    126   // TODO(wtc): Find a better way to handle a multi-round challenge-response
    127   // sequence used by a connection-based authentication scheme.
    128   virtual bool NeedsIdentity();
    129 
    130   // Returns whether the default credentials may be used for the |origin| passed
    131   // into |InitFromChallenge|. If true, the user does not need to be prompted
    132   // for username and password to establish credentials.
    133   // NOTE: SSO is a potential security risk.
    134   // TODO(cbentzel): Add a pointer to Firefox documentation about risk.
    135   virtual bool AllowsDefaultCredentials();
    136 
    137  protected:
    138   enum Property {
    139     ENCRYPTS_IDENTITY = 1 << 0,
    140     IS_CONNECTION_BASED = 1 << 1,
    141   };
    142 
    143   // Initializes the handler using a challenge issued by a server.
    144   // |challenge| must be non-NULL and have already tokenized the
    145   // authentication scheme, but none of the tokens occuring after the
    146   // authentication scheme.
    147   // Implementations are expcted to initialize the following members:
    148   // scheme_, realm_, score_, properties_
    149   virtual bool Init(HttpAuth::ChallengeTokenizer* challenge) = 0;
    150 
    151   // |GenerateAuthTokenImpl()} is the auth-scheme specific implementation
    152   // of generating the next auth token. Callers sohuld use |GenerateAuthToken()|
    153   // which will in turn call |GenerateAuthTokenImpl()|
    154   virtual int GenerateAuthTokenImpl(const string16* username,
    155                                     const string16* password,
    156                                     const HttpRequestInfo* request,
    157                                     CompletionCallback* callback,
    158                                     std::string* auth_token) = 0;
    159 
    160   // The auth-scheme as an enumerated value.
    161   HttpAuth::Scheme auth_scheme_;
    162 
    163   // The realm.  Used by "basic" and "digest".
    164   std::string realm_;
    165 
    166   // The auth challenge.
    167   std::string auth_challenge_;
    168 
    169   // The {scheme, host, port} for the authentication target.  Used by "ntlm"
    170   // and "negotiate" to construct the service principal name.
    171   GURL origin_;
    172 
    173   // The score for this challenge. Higher numbers are better.
    174   int score_;
    175 
    176   // Whether this authentication request is for a proxy server, or an
    177   // origin server.
    178   HttpAuth::Target target_;
    179 
    180   // A bitmask of the properties of the authentication scheme.
    181   int properties_;
    182 
    183   BoundNetLog net_log_;
    184 
    185  private:
    186   void OnGenerateAuthTokenComplete(int rv);
    187   void FinishGenerateAuthToken();
    188 
    189   CompletionCallback* original_callback_;
    190   CompletionCallbackImpl<HttpAuthHandler> wrapper_callback_;
    191 };
    192 
    193 }  // namespace net
    194 
    195 #endif  // NET_HTTP_HTTP_AUTH_HANDLER_H_
    196