src/acl/Checklist.h

   1 /*
   2  * $Id$
   3  *
   4  *
   5  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   6  * ----------------------------------------------------------
   7  *
   8  *  Squid is the result of efforts by numerous individuals from
   9  *  the Internet community; see the CONTRIBUTORS file for full
  10  *  details.   Many organizations have provided support for Squid's
  11  *  development; see the SPONSORS file for full details.  Squid is
  12  *  Copyrighted (C) 2001 by the Regents of the University of
  13  *  California; see the COPYRIGHT file for full details.  Squid
  14  *  incorporates software developed and/or copyrighted by other
  15  *  sources; see the CREDITS file for full details.
  16  *
  17  *  This program is free software; you can redistribute it and/or modify
  18  *  it under the terms of the GNU General Public License as published by
  19  *  the Free Software Foundation; either version 2 of the License, or
  20  *  (at your option) any later version.
  21  *
  22  *  This program is distributed in the hope that it will be useful,
  23  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  *  GNU General Public License for more details.
  26  *
  27  *  You should have received a copy of the GNU General Public License
  28  *  along with this program; if not, write to the Free Software
  29  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  30  *
  31  */
  32
  33 #ifndef SQUID_ACLCHECKLIST_H
  34 #define SQUID_ACLCHECKLIST_H
  35
  36 #include "acl/Acl.h"
  37
  38 /** \ingroup ACLAPI
  39     Base class for maintaining Squid and transaction state for access checks.
  40         Provides basic ACL checking methods. Its only child, ACLFilledChecklist,
  41         keeps the actual state data. The split is necessary to avoid exposing
  42     all ACL-related code to virtually Squid data types. */
  43 class ACLChecklist
  44 {
  45
  46 public:
  47
  48     /**
  49      * State class.
  50      * This abstract class defines the behaviour of
  51      * async lookups - which can vary for different ACL types.
  52      * Today, every state object must be a singleton.
  53      * See NULLState for an example.
  54      *
  55      \note *no* state should be stored in the state object,
  56      * they are used to change the behaviour of the checklist, not
  57      * to hold information. If you need to store information in the
  58      * state object, consider subclassing ACLChecklist, converting it
  59      * to a composite, or changing the state objects from singletons to
  60      * refcounted objects.
  61      */
  62
  63     class AsyncState
  64     {
  65
  66     public:
  67         virtual void checkForAsync(ACLChecklist *) const = 0;
  68         virtual ~AsyncState() {}
  69
  70     protected:
  71         void changeState (ACLChecklist *, AsyncState *) const;
  72     };
  73
  74     class NullState : public AsyncState
  75     {
  76
  77     public:
  78         static NullState *Instance();
  79         virtual void checkForAsync(ACLChecklist *) const;
  80         virtual ~NullState() {}
  81
  82     private:
  83         static NullState _instance;
  84     };
  85
  86
  87 public:
  88     ACLChecklist();
  89     virtual ~ACLChecklist();
  90
  91     /**
  92      * Trigger off a non-blocking access check for a set of *_access options..
  93      * The callback specified will be called with true/false
  94      * when the results of the ACL tests are known.
  95      */
  96     void nonBlockingCheck(PF * callback, void *callback_data);
  97
  98     /**
  99      * Trigger a blocking access check for a set of *_access options.
 100      *
 101      * ACLs which cannot be satisfied directly from available data are ignored.
 102      * This means any proxy_auth, external_acl, DNS lookups, Ident lookups etc
 103      * which have not already been performed and cached will not be checked.
 104      *
 105      * If there is no access list to check the default is to return DENIED.
 106      * However callers should perform their own check and default based on local
 107      * knowledge of the ACL usage rather than depend on this default.
 108      * That will also save on work setting up ACLChecklist fields for a no-op.
 109      *
 110      * \retval  1/true    Access Allowed
 111      * \retval 0/false    Access Denied
 112      */
 113     int fastCheck();
 114
 115     /**
 116      * Trigger a blocking access check for a single ACL line (a AND b AND c).
 117      *
 118      * ACLs which cannot be satisfied directly from available data are ignored.
 119      * This means any proxy_auth, external_acl, DNS lookups, Ident lookups etc
 120      * which have not already been performed and cached will not be checked.
 121      *
 122      * \retval  1/true    Access Allowed
 123      * \retval 0/false    Access Denied
 124      */
 125     bool matchAclListFast(const ACLList * list);
 126
 127     /**
 128      * Attempt to check the current checklist against current data.
 129      * This is the core routine behind all ACL test routines.
 130      * As much as possible of current tests are performed immediately
 131      * and the result is maybe delayed to wait for async lookups.
 132      *
 133      * When all tests are done callback is presented with one of:
 134      * \item ACCESS_ALLOWED     Access explicitly Allowed
 135      * \item ACCESS_DENIED      Access explicitly Denied
 136      */
 137     void check();
 138
 139     bool asyncInProgress() const;
 140     void asyncInProgress(bool const);
 141
 142     bool finished() const;
 143     void markFinished();
 144
 145     allow_t const & currentAnswer() const;
 146     void currentAnswer(allow_t const);
 147
 148     void changeState(AsyncState *);
 149     AsyncState *asyncState() const;
 150
 151         // XXX: ACLs that need request or reply have to use ACLFilledChecklist and
 152         // should do their own checks so that we do not have to povide these two
 153     // for ACL::checklistMatches to use
 154         virtual bool hasRequest() const = 0;
 155         virtual bool hasReply() const = 0;
 156
 157 private:
 158     virtual void checkCallback(allow_t answer);
 159     void checkAccessList();
 160     void checkForAsync();
 161
 162 public:
 163     const acl_access *accessList;
 164
 165     PF *callback;
 166     void *callback_data;
 167
 168 private: /* internal methods */
 169     void preCheck();
 170     void matchAclList(const ACLList * list, bool const fast);
 171     void matchAclListSlow(const ACLList * list);
 172
 173     bool async_;
 174     bool finished_;
 175     allow_t allow_;
 176     AsyncState *state_;
 177
 178     bool checking_;
 179     bool checking() const;
 180     void checking (bool const);
 181
 182     bool lastACLResult_;
 183     bool callerGone();
 184
 185 public:
 186     bool lastACLResult(bool x) { return lastACLResult_ = x; }
 187
 188     bool lastACLResult() const { return lastACLResult_; }
 189 };
 190
 191 #endif /* SQUID_ACLCHECKLIST_H */