#include <Checklist.h>

Inheritance diagram for ACLChecklist:

Collaboration diagram for ACLChecklist:

[legend]

Classes
class	AsyncState

class	Breadcrumb
	Position of a child node within an ACL tree. More...

class	NullState

Public Member Functions
	ACLChecklist ()

virtual	~ACLChecklist ()

void	nonBlockingCheck (ACLCB callback, void callback_data)

Acl::Answer const &	fastCheck ()

Acl::Answer const &	fastCheck (const Acl::Tree *list)

bool	goAsync (AsyncState *)

bool	matchChild (const Acl::InnerNode parent, Acl::Nodes::const_iterator pos, const ACL child)

bool	keepMatching () const
	Whether we should continue to match tree nodes or stop/pause. More...

bool	finished () const
	whether markFinished() was called More...

bool	asyncInProgress () const
	async call has been started and has not finished (or failed) yet More...

void	markFinished (const Acl::Answer &newAnswer, const char *reason)

const Acl::Answer &	currentAnswer () const

bool	bannedAction (const Acl::Answer &action) const
	whether the action is banned or not More...

void	banAction (const Acl::Answer &action)
	add action to the list of banned actions More...

virtual bool	hasRequest () const =0

virtual bool	hasReply () const =0

virtual bool	hasAle () const =0

virtual void	syncAle (HttpRequest adaptedRequest, const char logUri) const =0
	assigns uninitialized adapted_request and url ALE components More...

virtual void	verifyAle () const =0
	warns if there are uninitialized ALE components and fills them More...

const Acl::Tree *	changeAcl (const Acl::Tree *t)

void	resumeNonBlockingCheck (AsyncState *state)

Public Attributes
ACLCB *	callback

void *	callback_data

Private Types
enum	NodeMatchingResult { nmrMatch , nmrMismatch , nmrFinished , nmrNeedsAsync }
	possible outcomes when trying to match a single ACL node in a list More...

enum	AsyncStage { asyncNone , asyncStarting , asyncRunning , asyncFailed }

Private Member Functions
void	checkCallback (Acl::Answer answer)
	Calls non-blocking check callback with the answer and destroys self. More...

void	matchAndFinish ()
	performs (or resumes) an ACL tree match and, if successful, sets the action More...

void	changeState (AsyncState *)

AsyncState *	asyncState () const

void	preCheck (const char *what)
	prepare for checking ACLs; called once per check More...

bool	prepNonBlocking ()
	common parts of nonBlockingCheck() and resumeNonBlockingCheck() More...

void	completeNonBlocking ()

void	calcImplicitAnswer ()

bool	callerGone ()

Private Attributes
const Acl::Tree *	accessList

bool	asyncCaller_
	whether the caller supports async/slow ACLs More...

bool	occupied_
	whether a check (fast or non-blocking) is in progress More...

bool	finished_

Acl::Answer	answer_

AsyncStage	asyncStage_

AsyncState *	state_

Breadcrumb	matchLoc_
	location of the node running matches() now More...

Breadcrumb	asyncLoc_
	currentNode_ that called goAsync() More...

unsigned	asyncLoopDepth_
	how many times the current async state has resumed More...

std::stack< Breadcrumb >	matchPath
	suspended (due to an async lookup) matches() in the ACL tree More...

std::vector< Acl::Answer >	bannedActions_
	the list of actions which must ignored during acl checks More...

Detailed Description

Base class for maintaining Squid and transaction state for access checks. Provides basic ACL checking methods. Its only child, ACLFilledChecklist, keeps the actual state data. The split is necessary to avoid exposing all ACL-related code to virtually Squid data types.

Definition at line 26 of file Checklist.h.

Member Enumeration Documentation

◆ AsyncStage

enum ACLChecklist::AsyncStage

private

Enumerator
asyncNone
asyncStarting
asyncRunning
asyncFailed

Definition at line 233 of file Checklist.h.

◆ NodeMatchingResult

enum ACLChecklist::NodeMatchingResult

private

Enumerator
nmrMatch
nmrMismatch
nmrFinished
nmrNeedsAsync

Definition at line 219 of file Checklist.h.

Constructor & Destructor Documentation

◆ ACLChecklist()

ACLChecklist::ACLChecklist ( )

Definition at line 176 of file Checklist.cc.

◆ ~ACLChecklist()

ACLChecklist::~ACLChecklist ( )

virtual

Definition at line 190 of file Checklist.cc.

References assert, asyncInProgress(), changeAcl(), and debugs.

Member Function Documentation

◆ asyncInProgress()

bool ACLChecklist::asyncInProgress ( ) const

inline

Definition at line 151 of file Checklist.h.

References asyncNone, and asyncStage_.

Referenced by ~ACLChecklist(), ACLFilledChecklist::~ACLFilledChecklist(), completeNonBlocking(), goAsync(), keepMatching(), markFinished(), matchChild(), ACL::matches(), nonBlockingCheck(), Acl::InnerNode::resumeMatchingAt(), and resumeNonBlockingCheck().

◆ asyncState()

ACLChecklist::AsyncState * ACLChecklist::asyncState ( ) const

private

Definition at line 226 of file Checklist.cc.

References state_.

Referenced by resumeNonBlockingCheck().

◆ banAction()

void ACLChecklist::banAction ( const Acl::Answer & action )

Definition at line 395 of file Checklist.cc.

References action(), and bannedActions_.

Referenced by Ssl::PeekingPeerConnector::checkForPeekAndSplice(), and ConnStateData::startPeekAndSplice().

◆ bannedAction()

bool ACLChecklist::bannedAction ( const Acl::Answer & action ) const

Definition at line 387 of file Checklist.cc.

References action(), bannedActions_, and debugs.

Referenced by Acl::Tree::bannedAction().

◆ calcImplicitAnswer()

void ACLChecklist::calcImplicitAnswer ( )

private

When no rules matched, the answer is the inversion of the last rule action (or ACCESS_DUNNO if the reversal is not possible).

Definition at line 363 of file Checklist.cc.

References ACCESS_ALLOWED, ACCESS_DENIED, ACCESS_DUNNO, accessList, cbdataReferenceValid(), debugs, Acl::Tree::lastAction(), and markFinished().

Referenced by completeNonBlocking(), and fastCheck().

◆ callerGone()

bool ACLChecklist::callerGone ( )

private

Definition at line 381 of file Checklist.cc.

References callback_data, and cbdataReferenceValid().

Referenced by prepNonBlocking().

◆ changeAcl()

const Acl::Tree * ACLChecklist::changeAcl ( const Acl::Tree * t )

inline

change the current ACL list

Returns: a pointer to the old list value (may be nullptr)

Definition at line 176 of file Checklist.h.

References accessList, cbdataReference, and cbdataReferenceDone.

Referenced by ACLFilledChecklist::ACLFilledChecklist(), ~ACLChecklist(), fastCheck(), HttpStateData::forwardUpgrade(), and ConnStateData::whenClientIpKnown().

◆ changeState()

void ACLChecklist::changeState ( AsyncState * newState )

private

Definition at line 214 of file Checklist.cc.

References assert, ACLChecklist::NullState::Instance(), and state_.

Referenced by goAsync(), and resumeNonBlockingCheck().

◆ checkCallback()

void ACLChecklist::checkCallback ( Acl::Answer answer )

private

Definition at line 158 of file Checklist.cc.

References callback, callback_data, cbdataReferenceValidDone, debugs, and occupied_.

Referenced by completeNonBlocking(), nonBlockingCheck(), and prepNonBlocking().

◆ completeNonBlocking()

void ACLChecklist::completeNonBlocking ( )

private

Definition at line 45 of file Checklist.cc.

References accessList, assert, asyncInProgress(), calcImplicitAnswer(), cbdataReferenceDone, checkCallback(), currentAnswer(), and finished().

Referenced by nonBlockingCheck(), and resumeNonBlockingCheck().

◆ currentAnswer()

const Acl::Answer & ACLChecklist::currentAnswer ( ) const

inline

Definition at line 156 of file Checklist.h.

References answer_.

Referenced by completeNonBlocking(), and fastCheck().

◆ fastCheck() [1/2]

Acl::Answer const & ACLChecklist::fastCheck ( )

Perform a blocking (immediate) check for a list of allow/deny rules. Each rule comes with a list of ACLs.

The first rule where all ACLs match wins. If there is such a rule, the result becomes that rule keyword (ACCESS_ALLOWED or ACCESS_DENIED).

If there are rules but all ACL lists mismatch, an implicit rule is used Its result is the negation of the keyword of the last seen rule.

Some ACLs may stop the check prematurely by setting an exceptional check result (e.g., ACCESS_AUTH_REQUIRED) instead of declaring a match or mismatch.

Some ACLs may require an async lookup which is prohibited by this method. In this case, the exceptional check result of ACCESS_DUNNO is immediately returned.

If there are no rules to check at all, the result becomes ACCESS_DUNNO.

Definition at line 332 of file Checklist.cc.

References accessList, asyncCaller_, calcImplicitAnswer(), cbdataReference, cbdataReferenceDone, cbdataReferenceValid(), currentAnswer(), debugs, finished(), matchAndFinish(), occupied_, and preCheck().

Referenced by accessLogLogTo(), aclFindNfMarkConfig(), aclMapTOS(), Client::blockCaching(), ConnStateData::buildSslCertGenerationParams(), HttpReply::calcMaxBodySize(), Adaptation::Icap::Launcher::canRepeat(), FwdState::connectStart(), DelayId::DelayClient(), HttpStateData::finishingBrokenPost(), HttpStateData::forwardUpgrade(), getOutgoingAddress(), HttpRequest::getRangeOffsetLimit(), HttpStateData::handle1xx(), Ftp::Server::handleUploadRequest(), htcpAccessAllowed(), httpHdrAdd(), httpHdrMangle(), icpAccessAllowed(), ClientHttpRequest::logRequest(), HttpRequest::manager(), Note::match(), StoreClient::onCollapsingPath(), peerAllowedToUse(), Http::One::Server::processParsedRequest(), ConnStateData::proxyProtocolValidateClient(), schemesConfig(), Ftp::Client::sendPassive(), ConnStateData::serveDelayedError(), Security::KeyLogger::shouldLog(), snmpDecodePacket(), ssl_verify_cb(), Security::PeerConnector::sslCrtvdCheckForErrors(), FwdState::Start(), ConnStateData::tunnelOnError(), tunnelStart(), and ConnStateData::whenClientIpKnown().

◆ fastCheck() [2/2]

Acl::Answer const & ACLChecklist::fastCheck ( const Acl::Tree * list )

Perform a blocking (immediate) check whether a list of ACLs matches. This method is meant to be used with squid.conf ACL-driven options that lack allow/deny keywords and are tested one ACL list at a time. Whether the checks for other occurrences of the same option continue after this call is up to the caller and option semantics.

If all ACLs match, the result becomes ACCESS_ALLOWED.

If all ACLs mismatch, the result becomes ACCESS_DENIED.

Some ACLs may stop the check prematurely by setting an exceptional check result (e.g., ACCESS_AUTH_REQUIRED) instead of declaring a match or mismatch.

Some ACLs may require an async lookup which is prohibited by this method. In this case, the exceptional check result of ACCESS_DUNNO is immediately returned.

If there are no ACLs to check at all, the result becomes ACCESS_ALLOWED.

Definition at line 307 of file Checklist.cc.

References ACCESS_DENIED, accessList, asyncCaller_, cbdataReferenceValid(), changeAcl(), currentAnswer(), finished(), markFinished(), matchAndFinish(), occupied_, and preCheck().

◆ finished()

bool ACLChecklist::finished ( ) const

inline

Definition at line 149 of file Checklist.h.

References finished_.

Referenced by completeNonBlocking(), fastCheck(), keepMatching(), ACLFilledChecklist::markDestinationDomainChecked(), markFinished(), ACLFilledChecklist::markSourceDomainChecked(), and resumeNonBlockingCheck().

◆ goAsync()

bool ACLChecklist::goAsync ( AsyncState * state )

If slow lookups are allowed, switches into "async in progress" state. Otherwise, returns false; the caller is expected to handle the failure.

Definition at line 114 of file Checklist.cc.

References assert, asyncCaller_, asyncFailed, asyncInProgress(), asyncLoc_, asyncLoopDepth_, asyncNone, asyncRunning, asyncStage_, asyncStarting, changeState(), ACLChecklist::AsyncState::checkForAsync(), debugs, matchLoc_, and ACLChecklist::Breadcrumb::parent.

Referenced by aclMatchExternal(), AuthenticateAcl(), makeExternalAclKey(), ACLDestinationIP::match(), and ACLIdent::match().

◆ hasAle()

virtual bool ACLChecklist::hasAle ( ) const

pure virtual

Implemented in ACLFilledChecklist.

Referenced by ACL::matches(), and ACLHasComponentData::parseComponent().

◆ hasReply()

virtual bool ACLChecklist::hasReply ( ) const

pure virtual

Implemented in ACLFilledChecklist.

Referenced by ACL::matches(), and ACLHasComponentData::parseComponent().

◆ hasRequest()

virtual bool ACLChecklist::hasRequest ( ) const

pure virtual

Implemented in ACLFilledChecklist.

Referenced by Acl::ConnectionsEncrypted::match(), ACL::matches(), and ACLHasComponentData::parseComponent().

◆ keepMatching()

bool ACLChecklist::keepMatching ( ) const

inline

Definition at line 146 of file Checklist.h.

References asyncInProgress(), and finished().

Referenced by Acl::AllOf::doMatch(), Acl::NotNode::doMatch(), Acl::AndNode::doMatch(), Acl::OrNode::doMatch(), ACLProxyAuth::match(), ACLExternal::match(), and ACLMaxUserIP::match().

◆ markFinished()

void ACLChecklist::markFinished	(	const Acl::Answer &	newAnswer,
		const char *	reason
	)

called when no more ACLs should be checked; sets the final answer and prints a debugging message explaining the reason for that answer

Definition at line 57 of file Checklist.cc.

References answer_, assert, asyncInProgress(), debugs, finished(), and finished_.

Referenced by calcImplicitAnswer(), fastCheck(), ACLProxyAuth::match(), ACLExternal::match(), ACLIdent::match(), ACLMaxUserIP::match(), and matchAndFinish().

◆ matchAndFinish()

void ACLChecklist::matchAndFinish ( )

private

Definition at line 291 of file Checklist.cc.

References accessList, markFinished(), ACL::matches(), matchPath, ACLChecklist::Breadcrumb::parent, ACLChecklist::Breadcrumb::position, Acl::InnerNode::resumeMatchingAt(), and Acl::Tree::winningAction().

Referenced by fastCheck(), nonBlockingCheck(), and resumeNonBlockingCheck().

◆ matchChild()

bool ACLChecklist::matchChild	(	const Acl::InnerNode *	parent,
		Acl::Nodes::const_iterator	pos,
		const ACL *	child
	)

Matches (or resumes matching of) a child node while maintaning resumption breadcrumbs if a [grand]child node goes async.

Definition at line 81 of file Checklist.cc.

References assert, asyncInProgress(), asyncLoc_, asyncLoopDepth_, ACLChecklist::Breadcrumb::clear(), ACL::matches(), matchLoc_, matchPath, ACLChecklist::Breadcrumb::parent, ACLChecklist::Breadcrumb::position, and Acl::InnerNode::resumeMatchingAt().

Referenced by Acl::AllOf::doMatch(), Acl::NotNode::doMatch(), Acl::AndNode::doMatch(), and Acl::OrNode::doMatch().

◆ nonBlockingCheck()

void ACLChecklist::nonBlockingCheck	(	ACLCB *	callback_,
		void *	callback_data_
	)

Start a non-blocking (async) check for a list of allow/deny rules. Each rule comes with a list of ACLs.

The callback specified will be called with the result of the check.

The first rule where all ACLs match wins. If there is such a rule, the result becomes that rule keyword (ACCESS_ALLOWED or ACCESS_DENIED).

If there are rules but all ACL lists mismatch, an implicit rule is used. Its result is the negation of the keyword of the last seen rule.

Some ACLs may stop the check prematurely by setting an exceptional check result (e.g., ACCESS_AUTH_REQUIRED) instead of declaring a match or mismatch.

If there are no rules to check at all, the result becomes ACCESS_DUNNO. Calling this method with no rules to check wastes a lot of CPU cycles and will result in a DBG_CRITICAL debugging message.

Kick off a non-blocking (slow) ACL access list test

NP: this should probably be made Async now.

The ACL List should NEVER be NULL when calling this method. Always caller should check for NULL and handle appropriate to its needs first. We cannot select a sensible default for all callers here.

Definition at line 237 of file Checklist.cc.

References ACCESS_DUNNO, accessList, asyncCaller_, asyncInProgress(), callback, callback_data, cbdataReference, checkCallback(), completeNonBlocking(), DBG_CRITICAL, debugs, matchAndFinish(), preCheck(), and prepNonBlocking().