src/auth/UserRequest.h

   1 /*
   2  * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_AUTH_USERREQUEST_H
  10 #define SQUID_AUTH_USERREQUEST_H
  11
  12 #if USE_AUTH
  13
  14 #include "AccessLogEntry.h"
  15 #include "auth/AuthAclState.h"
  16 #include "auth/Scheme.h"
  17 #include "auth/User.h"
  18 #include "dlink.h"
  19 #include "helper/forward.h"
  20 #include "HttpHeader.h"
  21 #include "ip/Address.h"
  22
  23 class ConnStateData;
  24 class HttpReply;
  25 class HttpRequest;
  26
  27 /**
  28  * Maximum length (buffer size) for token strings.
  29  */
  30 // XXX: Keep in sync with all others: bzr grep 'define MAX_AUTHTOKEN_LEN'
  31 #define MAX_AUTHTOKEN_LEN   65535
  32
  33 /**
  34  * Node used to link an IP address to some user credentials
  35  * for the max_user_ip ACL feature.
  36  */
  37 class AuthUserIP
  38 {
  39     MEMPROXY_CLASS(AuthUserIP);
  40
  41 public:
  42     AuthUserIP(const Ip::Address &ip, time_t t) : ipaddr(ip), ip_expiretime(t) {}
  43
  44     dlink_node node;
  45
  46     /// IP address this user authenticated from
  47     Ip::Address ipaddr;
  48
  49     /** When this IP should be forgotten.
  50      * Set to the time of last request made from this
  51      * (user,IP) pair plus authenticate_ip_ttl seconds
  52      */
  53     time_t ip_expiretime;
  54 };
  55
  56 // TODO: make auth schedule AsyncCalls?
  57 typedef void AUTHCB(void*);
  58
  59 namespace Auth
  60 {
  61
  62 // NP: numeric values specified for old code backward compatibility.
  63 //  remove after transition is complete
  64 enum Direction {
  65     CRED_CHALLENGE = 1, ///< Client needs to be challenged. secure token.
  66     CRED_VALID = 0,     ///< Credentials are valid and a up to date. The OK/Failed state is accurate.
  67     CRED_LOOKUP = -1,   ///< Credentials need to be validated with the backend helper
  68     CRED_ERROR = -2     ///< ERROR in the auth module. Cannot determine the state of this request.
  69 };
  70
  71 /**
  72  * This is a short lived structure is the visible aspect of the authentication framework.
  73  *
  74  * It and its children hold the state data while processing authentication for a client request.
  75  * The AuthenticationStateData object is merely a CBDATA wrapper for one of these.
  76  */
  77 class UserRequest : public RefCountable
  78 {
  79 public:
  80     typedef RefCount<Auth::UserRequest> Pointer;
  81
  82     UserRequest();
  83     virtual ~UserRequest();
  84     void *operator new(size_t byteCount);
  85     void operator delete(void *address);
  86
  87 public:
  88     /**
  89      * This is the object passed around by client_side and acl functions
  90      * it has request specific data, and links to user specific data
  91      * the user
  92      */
  93     User::Pointer _auth_user;
  94
  95     /**
  96      *  Used by squid to determine what the next step in performing authentication for a given scheme is.
  97      *
  98      * \retval CRED_ERROR   ERROR in the auth module. Cannot determine request direction.
  99      * \retval CRED_LOOKUP  The auth module needs to send data to an external helper.
 100      *              Squid will prepare for a callback on the request and call the AUTHSSTART function.
 101      * \retval CRED_VALID   The auth module has all the information it needs to perform the authentication
 102      *              and provide a succeed/fail result.
 103      * \retval CRED_CHALLENGE   The auth module needs to send a new challenge to the request originator.
 104      *              Squid will return the appropriate status code (401 or 407) and call the registered
 105      *              FixError function to allow the auth module to insert it's challenge.
 106      */
 107     Direction direction();
 108
 109     /**
 110      * Used by squid to determine whether the auth scheme has successfully authenticated the user request.
 111      *
 112      \retval true   User has successfully been authenticated.
 113      \retval false  Timeouts on cached credentials have occurred or for any reason the credentials are not valid.
 114      */
 115     virtual int authenticated() const = 0;
 116
 117     /**
 118      * Check a auth_user pointer for validity.
 119      * Does not check passwords, just data sensability. Broken or Unknown auth_types are not valid for use...
 120      *
 121      * \retval false    User credentials are missing.
 122      * \retval false    User credentials use an unknown scheme type.
 123      * \retval false    User credentials are broken for their scheme.
 124      *
 125      * \retval true User credentials exist and may be able to authenticate.
 126      */
 127     bool valid() const;
 128
 129     virtual void authenticate(HttpRequest * request, ConnStateData * conn, Http::HdrType type) = 0;
 130
 131     /* template method - what needs to be done next? advertise schemes, challenge, handle error, nothing? */
 132     virtual Direction module_direction() = 0;
 133
 134     /* add the [Proxy-]Authentication-Info header */
 135     virtual void addAuthenticationInfoHeader(HttpReply * rep, int accel);
 136
 137     /* add the [Proxy-]Authentication-Info trailer */
 138     virtual void addAuthenticationInfoTrailer(HttpReply * rep, int accel);
 139
 140     virtual void releaseAuthServer();
 141
 142     // User credentials object this UserRequest is managing
 143     virtual User::Pointer user() {return _auth_user;}
 144     virtual const User::Pointer user() const {return _auth_user;}
 145     virtual void user(User::Pointer aUser) {_auth_user=aUser;}
 146
 147     /**
 148      * Locate user credentials in one of several locations. Begin authentication if needed.
 149      *
 150      * Credentials may be found in one of the following locations (listed by order of preference):
 151      * - the source passed as parameter aUR
 152      * - cached in the HttpRequest parameter from a previous authentication of this request
 153      * - cached in the ConnStateData paremeter from a previous authentication of this connection
 154      *   (only applies to some situations. ie NTLM, Negotiate, Kerberos auth schemes,
 155      *    or decrypted SSL requests from inside an authenticated CONNECT tunnel)
 156      * - cached in the user credentials cache from a previous authentication of the same credentials
 157      *   (only applies to cacheable authentication methods, ie Basic auth)
 158      * - new credentials created from HTTP headers in this request
 159      *
 160      * The found credentials are returned in aUR and if successfully authenticated
 161      * may now be cached in one or more of the above locations.
 162      *
 163      * \return Some AUTH_ACL_* state
 164      */
 165     static AuthAclState tryToAuthenticateAndSetAuthUser(UserRequest::Pointer *aUR, Http::HdrType, HttpRequest *, ConnStateData *, Ip::Address &, AccessLogEntry::Pointer &);
 166
 167     /// Add the appropriate [Proxy-]Authenticate header to the given reply
 168     static void AddReplyAuthHeader(HttpReply * rep, UserRequest::Pointer auth_user_request, HttpRequest * request, int accelerated, int internal);
 169
 170     /** Start an asynchronous helper lookup to verify the user credentials
 171      *
 172      * Uses startHelperLookup() for scheme-specific actions.
 173      *
 174      * The given callback will be called when the auth module has performed
 175      * it's external activities.
 176      *
 177      * \param handler   Handler to process the callback when its run
 178      * \param data  CBDATA for handler
 179      */
 180     void start(HttpRequest *request, AccessLogEntry::Pointer &al, AUTHCB *handler, void *data);
 181
 182     char const * denyMessage(char const * const default_message = NULL) const;
 183
 184     /** Possibly overrideable in future */
 185     void setDenyMessage(char const *);
 186
 187     /** Possibly overrideable in future */
 188     char const * getDenyMessage() const;
 189
 190     /**
 191      * Squid does not make assumptions about where the username is stored.
 192      * This function must return a pointer to a NULL terminated string to be used in logging the request.
 193      * The string should NOT be allocated each time this function is called.
 194      *
 195      \retval NULL   No username/usercode is known.
 196      \retval *      Null-terminated username string.
 197      */
 198     char const *username() const;
 199
 200     Scheme::Pointer scheme() const;
 201
 202     virtual const char * connLastHeader();
 203
 204     /**
 205      * The string representation of the credentials send by client
 206      */
 207     virtual const char *credentialsStr() = 0;
 208
 209     const char *helperRequestKeyExtras(HttpRequest *, AccessLogEntry::Pointer &al);
 210
 211     /// Sets the reason of 'authentication denied' helper response.
 212     void denyMessageFromHelper(char const *proto, const Helper::Reply &reply);
 213
 214 protected:
 215     /**
 216      * The scheme-specific actions to be performed when sending helper lookup.
 217      *
 218      * \see void start(HttpRequest *, AccessLogEntry::Pointer &, AUTHCB *, void *);
 219      */
 220     virtual void startHelperLookup(HttpRequest *request, AccessLogEntry::Pointer &al, AUTHCB *handler, void *data) = 0;
 221
 222 private:
 223
 224     static AuthAclState authenticate(UserRequest::Pointer * auth_user_request, Http::HdrType headertype, HttpRequest * request, ConnStateData * conn, Ip::Address &src_addr, AccessLogEntry::Pointer &al);
 225
 226     /** return a message on the 407 error pages */
 227     char *message;
 228
 229     /**
 230      * We only attempt authentication once per http request. This
 231      * is to allow multiple auth acl references from different _access areas
 232      * when using connection based authentication
 233      */
 234     AuthAclState lastReply;
 235 };
 236
 237 } // namespace Auth
 238
 239 /* AuthUserRequest */
 240
 241 /// \ingroup AuthAPI
 242 void authenticateAuthUserRequestRemoveIp(Auth::UserRequest::Pointer, Ip::Address const &);
 243 /// \ingroup AuthAPI
 244 void authenticateAuthUserRequestClearIp(Auth::UserRequest::Pointer);
 245 /// \ingroup AuthAPI
 246 int authenticateAuthUserRequestIPCount(Auth::UserRequest::Pointer);
 247
 248 /// \ingroup AuthAPI
 249 /// See Auth::UserRequest::authenticated()
 250 int authenticateUserAuthenticated(Auth::UserRequest::Pointer);
 251
 252 #endif /* USE_AUTH */
 253 #endif /* SQUID_AUTHUSERREQUEST_H */
 254