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/base/net_log.h"
13#include "net/http/http_auth.h"
14
15namespace net {
16
17struct HttpRequestInfo;
18
19// HttpAuthHandler is the interface for the authentication schemes
20// (basic, digest, NTLM, Negotiate).
21// HttpAuthHandler objects are typically created by an HttpAuthHandlerFactory.
22class NET_EXPORT_PRIVATE HttpAuthHandler {
23 public:
24  HttpAuthHandler();
25  virtual ~HttpAuthHandler();
26
27  // Initializes the handler using a challenge issued by a server.
28  // |challenge| must be non-NULL and have already tokenized the
29  // authentication scheme, but none of the tokens occurring after the
30  // authentication scheme. |target| and |origin| are both stored
31  // for later use, and are not part of the initial challenge.
32  bool InitFromChallenge(HttpAuth::ChallengeTokenizer* challenge,
33                         HttpAuth::Target target,
34                         const GURL& origin,
35                         const BoundNetLog& net_log);
36
37  // Determines how the previous authorization attempt was received.
38  //
39  // This is called when the server/proxy responds with a 401/407 after an
40  // earlier authorization attempt. Although this normally means that the
41  // previous attempt was rejected, in multi-round schemes such as
42  // NTLM+Negotiate it may indicate that another round of challenge+response
43  // is required. For Digest authentication it may also mean that the previous
44  // attempt used a stale nonce (and nonce-count) and that a new attempt should
45  // be made with a different nonce provided in the challenge.
46  //
47  // |challenge| must be non-NULL and have already tokenized the
48  // authentication scheme, but none of the tokens occurring after the
49  // authentication scheme.
50  virtual HttpAuth::AuthorizationResult HandleAnotherChallenge(
51      HttpAuth::ChallengeTokenizer* challenge) = 0;
52
53  // Generates an authentication token, potentially asynchronously.
54  //
55  // When |credentials| is NULL, the default credentials for the currently
56  // logged in user are used. |AllowsDefaultCredentials()| MUST be true in this
57  // case.
58  //
59  // |request|, |callback|, and |auth_token| must be non-NULL.
60  //
61  // The return value is a net error code.
62  //
63  // If |OK| is returned, |*auth_token| is filled in with an authentication
64  // token which can be inserted in the HTTP request.
65  //
66  // If |ERR_IO_PENDING| is returned, |*auth_token| will be filled in
67  // asynchronously and |callback| will be invoked. The lifetime of
68  // |request|, |callback|, and |auth_token| must last until |callback| is
69  // invoked, but |credentials| is only used during the initial call.
70  //
71  // All other return codes indicate that there was a problem generating a
72  // token, and the value of |*auth_token| is unspecified.
73  int GenerateAuthToken(const AuthCredentials* credentials,
74                        const HttpRequestInfo* request,
75                        const 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, encoded as UTF-8. This may be empty.
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  // Returns whether explicit credentials can be used with this handler.  If
138  // true the user may be prompted for credentials if an implicit identity
139  // cannot be determined.
140  virtual bool AllowsExplicitCredentials();
141
142 protected:
143  enum Property {
144    ENCRYPTS_IDENTITY = 1 << 0,
145    IS_CONNECTION_BASED = 1 << 1,
146  };
147
148  // Initializes the handler using a challenge issued by a server.
149  // |challenge| must be non-NULL and have already tokenized the
150  // authentication scheme, but none of the tokens occurring after the
151  // authentication scheme.
152  // Implementations are expected to initialize the following members:
153  // scheme_, realm_, score_, properties_
154  virtual bool Init(HttpAuth::ChallengeTokenizer* challenge) = 0;
155
156  // |GenerateAuthTokenImpl()} is the auth-scheme specific implementation
157  // of generating the next auth token. Callers should use |GenerateAuthToken()|
158  // which will in turn call |GenerateAuthTokenImpl()|
159  virtual int GenerateAuthTokenImpl(const AuthCredentials* credentials,
160                                    const HttpRequestInfo* request,
161                                    const CompletionCallback& callback,
162                                    std::string* auth_token) = 0;
163
164  // The auth-scheme as an enumerated value.
165  HttpAuth::Scheme auth_scheme_;
166
167  // The realm, encoded as UTF-8. Used by "basic" and "digest".
168  std::string realm_;
169
170  // The auth challenge.
171  std::string auth_challenge_;
172
173  // The {scheme, host, port} for the authentication target.  Used by "ntlm"
174  // and "negotiate" to construct the service principal name.
175  GURL origin_;
176
177  // The score for this challenge. Higher numbers are better.
178  int score_;
179
180  // Whether this authentication request is for a proxy server, or an
181  // origin server.
182  HttpAuth::Target target_;
183
184  // A bitmask of the properties of the authentication scheme.
185  int properties_;
186
187  BoundNetLog net_log_;
188
189 private:
190  void OnGenerateAuthTokenComplete(int rv);
191  void FinishGenerateAuthToken();
192
193  CompletionCallback callback_;
194};
195
196}  // namespace net
197
198#endif  // NET_HTTP_HTTP_AUTH_HANDLER_H_
199