A security policy framework built on top of the normal CServer2 class. More...

#include <e32base.h>

Inheritance diagram for CPolicyServer:

Classes
class	TPolicy
	Object specifying which security checks to perform on each request number and what action to take if the check fails. More...

class	TPolicyElement
	Class specifying a security check and the action to take. More...

Public Types
enum	TFailureAction { EFailClient = 0 , EPanicClient = 1 }
	Enumeration specifying action to take if a security check fails. More...

enum	TCustomResult { EPass = 0 , EFail = 1 , EAsync = 2 }
	Enumeration of acceptable return codes from both of CustomSecurityCheckL() and CustomFailureActionL(). More...

enum	TSpecialCase { ECustomCheck =255u , ENotSupported =254u , EAlwaysPass =253u , ESpecialCaseLimit =252u , ESpecialCaseHardLimit =250u }
	Special case values which can be used instead of a policy element index contained in the array TPolicy::iElementsIndex. More...

Public Types inherited from CServer2
enum	TServerType { EUnsharableSessions = EIpcSession_Unsharable , ESharableSessions = EIpcSession_Sharable , EGlobalSharableSessions = EIpcSession_GlobalSharable }
	This enumeration defines the maximum sharability of sessions opened with this server; for backwards compatibilty, these should be have the same values as the corresponding EIpcSessionType enumeration. More...

enum	TPanic { EBadMessageNumber , ESessionNotConnected , ESessionAlreadyConnected , EClientDoesntHaveRequiredCaps }

Public Types inherited from CActive
enum	TPriority { EPriorityIdle =-100 , EPriorityLow =-20 , EPriorityStandard =0 , EPriorityUserInput =10 , EPriorityHigh =20 }
	Defines standard priorities for active objects. More...

Public Member Functions
IMPORT_C void	ProcessL (const RMessage2 &aMsg)
	Process an accepted message which has passed its policy check.

IMPORT_C void	CheckFailedL (const RMessage2 &aMsg, TInt aAction, const TSecurityInfo &aMissing)
	Called when a security check has failed.

IMPORT_C void	ProcessError (const RMessage2 &aMsg, TInt aError)
	Called if a leave occurs during processing of a message.

Public Member Functions inherited from CServer2
virtual IMPORT_C	~CServer2 ()=0
	Frees resources prior to destruction.

IMPORT_C TInt	Start (const TDesC &aName)
	Adds the server with the specified name to the active scheduler, and issues the first request for messages.

IMPORT_C void	StartL (const TDesC &aName)
	Adds the server with the specified name to the active scheduler, and issues the first request for messages, and leaves if the operation fails.

IMPORT_C void	ReStart ()
	Restarts the server.

IMPORT_C void	SetPinClientDescriptors (TBool aPin)
	Sets whether the kernel will pin descriptors passed to this server in the context of the client thread.

RServer2	Server () const
	Gets a handle to the server.

IMPORT_C void	SetMaster (const CServer2 *aServer)
	Assigns a role (master or slave) for this server.

Public Member Functions inherited from CActive
IMPORT_C	~CActive ()
	Frees resources prior to destruction.

IMPORT_C void	Cancel ()
	Cancels the wait for completion of an outstanding request.

IMPORT_C void	Deque ()
	Removes the active object from the active scheduler's list of active objects.

IMPORT_C void	SetPriority (TInt aPriority)
	Sets the priority of the active object.

TBool	IsActive () const
	Determines whether the active object has a request outstanding.

TBool	IsAdded () const
	Determines whether the active object has been added to the active scheduler's list of active objects.

TInt	Priority () const
	Gets the priority of the active object.

Public Member Functions inherited from CBase
	CBase ()
	Default constructor.

virtual IMPORT_C	~CBase ()
	Virtual destructor.

TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.

TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Protected Member Functions
IMPORT_C	CPolicyServer (TInt aPriority, const TPolicy &aPolicy, TServerType aType=EUnsharableSessions)
	Construct a policy server.

virtual IMPORT_C TCustomResult	CustomSecurityCheckL (const RMessage2 &aMsg, TInt &aAction, TSecurityInfo &aMissing)
	Performs a custom security check.

virtual IMPORT_C TCustomResult	CustomFailureActionL (const RMessage2 &aMsg, TInt aAction, const TSecurityInfo &aMissing)
	Performs a custom action after the failure of a security check.

virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)
	Extension function.

Protected Member Functions inherited from CServer2
const RMessage2 &	Message () const
	Gets a reference to the server's current message.

IMPORT_C	CServer2 (TInt aPriority, TServerType aType=EUnsharableSessions)
	Constructs the server object, specifying the server type and the active object priority.

IMPORT_C void	DoCancel ()
	Implements cancellation of an outstanding request.

IMPORT_C void	RunL ()
	Handles an active object's request completion event.

IMPORT_C TInt	RunError (TInt aError)
	Handles the situation where a call to CServer2::RunL(), leaves.

virtual IMPORT_C void	DoConnect (const RMessage2 &aMessage)
	Handles the connect request from the client.

Protected Member Functions inherited from CActive
IMPORT_C	CActive (TInt aPriority)
	Constructs the active object with the specified priority.

IMPORT_C void	SetActive ()
	Indicates that the active object has issued a request and that it is now outstanding.

Additional Inherited Members
Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Public Attributes inherited from CActive
TRequestStatus	iStatus
	The request status associated with an asynchronous request.

Protected Attributes inherited from CServer2
TDblQueIter< CSession2 >	iSessionIter

Detailed Description

A security policy framework built on top of the normal CServer2 class.

The two major functions of the Policy Server framework are to check a received message against a security policy and then to perform an action depending on the result of this check. The exact behaviour is defined by the contents of the TPolicy structure given in the constructor for CPolicyServer.

The processing performed when a server receives a message are describe below. This should aid understanding of the interaction of the TPolicy structure and virtual member functions which may be implemented by classes derived from CPolicyServer.

Checking the Security Policy

On receipt of a message, the message function number is used to search the list of ranges pointed to by TPolicy::iRanges. This yields a range number R, which is between 0 and TPolicy::iRangeCount-1. The policy index, X, for this range is then fetched from TPolicy::iElementsIndex[R]. If the message is a Connect message, then X is fetched directly from TPolicy::iOnConnect instead.

The further action taken is determined by the value of X.

If X==TSpecialCase::EAlwaysPass, the message is processed as normal; either by passing it to the ServiceL() method of a session, or, in the case of a connection message, a new session is created.
If X==TSpecialCase::ENotSupported, the message is completed with KErrNotSupported.
If X==TSpecialCase::ECustomCheck, a call to the virtual function CustomSecurityCheckL() is made. The implementation of this method must return one of the TCustomResult enumerations which determine what further action is to be taken:
- TCustomResult::EPass The message is processed as normal; either by passing it to the ServiceL() method of a session, or, in the case of a connection message, a new session is created.
- TCustomResult::EFail This causes CheckFailedL() to be called with the action specified by the aAction reference given to CustomSecurityCheckL() (This defaults to TFailureAction::EFailClient.)
- TCustomResult::EAsync The derived class is responsible for further processing of the message, the Policy Server framework will do nothing more with it.
If X < TSpecialCase::ESpecialCaseHardLimit, X is taken as an index into the array of TPolicyElement objects pointed to by TPolicy::iElements. The platform security attributes of the process which sent the message being processed are checked against the security policy specified in this TPolicyElement. If the process possesses all of the attributes specified then the message processed as normal. Otherwise, CheckFailedL() is called with the action value specified in the TPolicyElement .

Handling Policy Check Failure

The CheckFailedL() method is called when a security check has failed. It performs an action according to the aAction value given to it:

If aAction==TFailureAction::EFailClient, the message is completed with KErrPermissionDenied.
If aAction==TFailureAction::EPanicClient, the client thread is panicked.
If aAction < 0 a call to the virtual function CustomFailureActionL() is made. The implementation of this method must return one of the TCustomResult enumerations which determine what further action is to be taken:
- TCustomResult::EPass The message is processed as normal; either by passing it to the ServiceL() method of a session, or, in the case of a connection message, a new session is created.
- TCustomResult::EFail The message is completed with KErrPermissionDenied.
- TCustomResult::EAsync The derived class is responsible for further processing of the message, the Policy Server framework will do nothing more with it.

API status: Published to all clients. Released API.

Definition at line 2481 of file e32base.h.

Member Enumeration Documentation

◆ TCustomResult

enum CPolicyServer::TCustomResult

Enumeration of acceptable return codes from both of CustomSecurityCheckL() and CustomFailureActionL().

Results of EPass or EFail are handled by the CPolicyServer framework. No other action is required on the part of the derived implementation. However, results of EAsync imply that the derived implementation will call the appropriate function once the result is known. See CustomSecurityCheckL() and CustomFailureActionL for more information.

Enumerator
EPass	Security check passed.
EFail	Security check failed.
EAsync	Security checking will be performed asynchronously.

Definition at line 2504 of file e32base.h.

◆ TFailureAction

enum CPolicyServer::TFailureAction

Enumeration specifying action to take if a security check fails.

Values >= 0 are handled by CheckFailedL(). Values < 0 are specific to the derived implementation of the policy server and will result in a call to CustomFailureActionL() if a security check fails. Attempts to use undefined values >= 0 will result in a panic in CheckFailedL().

Enumerator
EFailClient	Complete message with KErrPermissionDenied.
EPanicClient	Panic client.

Definition at line 2490 of file e32base.h.

◆ TSpecialCase

enum CPolicyServer::TSpecialCase

Special case values which can be used instead of a policy element index contained in the array TPolicy::iElementsIndex.

Enumerator
ECustomCheck	Indicates a custom check should be made by calling CustomSecurityCheckL()
ENotSupported	Indicates that message is requesting an unsupported function. The message is completed with KErrNotSupported.
EAlwaysPass	Indicates that the message is requesting an unrestricted function and therefore should be processed without any further checks.
ESpecialCaseLimit	Internal technology API.
ESpecialCaseHardLimit	Internal technology API.

Definition at line 2563 of file e32base.h.

Constructor & Destructor Documentation

◆ CPolicyServer()

IMPORT_C CPolicyServer::CPolicyServer	(	TInt	aPriority,
		const TPolicy &	aPolicy,
		TServerType	aType = `EUnsharableSessions`
	)

protected

Construct a policy server.

Parameters

aPriority	Active object priority for this server
aPolicy	Reference to a policy object describing the security checks required for each message type. The server does not make a copy of policy, and therefore this object must exist for the lifetime of the server. It is recommended that aPolicy is in const static data.
aType	Type of session sharing supported by this server

Member Function Documentation

◆ CheckFailedL()

IMPORT_C void CPolicyServer::CheckFailedL	(	const RMessage2 &	aMsg,
		TInt	aAction,
		const TSecurityInfo &	aMissing
	)

Called when a security check has failed.

The aAction parameter determines the action taken:

If aAction==TFailureAction::EFailClient, the message is completed with KErrPermissionDenied.
If aAction==TFailureAction::EPanicClient, the client thread is panicked.
If aAction < 0 a call to the virtual function CustomFailureActionL() is made.

This function should only ever be called by derived implementations if asynchronous security checks are in use.

Parameters

aMsg	The message which failed its check.
aAction	The action to take. (See description.)
aMissing	A list of the security attributes that were missing from the checked process.

◆ CustomFailureActionL()

virtual IMPORT_C TCustomResult CPolicyServer::CustomFailureActionL	(	const RMessage2 &	aMsg,
		TInt	aAction,
		const TSecurityInfo &	aMissing
	)

protectedvirtual

Performs a custom action after the failure of a security check.

Derived server classes must implement this function if the aAction value passed to CheckFailedL() is less than zero. This can happened if the policy specified a negative number in the iAction member of any of the TPolicyElements, or, if the derived CustomSecurityCheckL() modified the value of aAction prior to returning.

If negative aAction values are used, there are two further cases to consider:

The custom security check can synchronously decide if the message should pass. In this case, the derived implementation must simply return either EPass or EFail depending on the result of the security check.
The custom security check needs to use asynchronous methods in order to determine whether the message should still proceed. In this case, these asysnchronous methods should be started and then the EAsync value returned. Furthermore, implmentations returning EAsync commit to the following:
- If the security check eventually passes, ProcessL() must be called with the appropriate message.
- If the security check eventually fails, or if a fatal error condition occurs, including if the previously mentioned call to ProcessL() leaves; then CPolicyServer::ProcessError() should be called passing the message and relevant error code.
- Pending messages on a given session need to be completed and discarded if the session is closed.
IMPORTANT NOTE. When processing a message asynchronously, a copy must be made of the RMessage2 object. Saving a refernece or pointer to the original message will produce unpredictable defects. This is because the object will be reused for the next message that the server receives.

The default implementation of this function panics the server.

Parameters

aMsg	The message to check
aAction	The custom failure action requested. This is either a value from TFailureAction or a negative value which has meaning to the CustomFailureActionL() method of a derived class.
aMissing	A const reference to the list of security attributes missing from the checked process. There are two cases to consider: (a) If this message was checked (and failed) by a static policy applied by the policy server framework, aMissing will contain a list of the security attributes that caused the policy to fail. An completely zeroed aMissing implies that an always fail policy was encountered. (b) If this message was failed by a custom security check, then aMissing will be zeroed unless the CustomSecurityCheckL() method filled it in.

Returns: A value from TCustomResult.
Panic condition: CBase 95 If the default implementation is called.

◆ CustomSecurityCheckL()

virtual IMPORT_C TCustomResult CPolicyServer::CustomSecurityCheckL	(	const RMessage2 &	aMsg,
		TInt &	aAction,
		TSecurityInfo &	aMissing
	)

protectedvirtual

Performs a custom security check.

Derived server classes must implement this function if any element in iElementsIndex has the value CPolicyServer::ECustomCheck. Similarly, if CPolicyServer::ECustomCheck is not used, then this function can be safely ignored.

If CPolicyServer::ECustomCheck is used, there are two further cases to consider:

The custom security check can synchronously decide if the message should pass. In this case, the derived implementation must simply return either EPass or EFail depending on the result of the security check.
The custom security check needs to use asynchronous methods in order to determine whether the message should procceed. In this case, these asysnchronous methods should be started and then the EAsync value returned. Furthermore, implmentations returning EAsync commit to the following:
- If the security check eventually passes, ProcessL() must be called with the appropriate message.
- If the security check eventually fails, CheckFailedL() must be called with that message.
- Pending messages on a given session need to be completed and discarded if the session is closed.
IMPORTANT NOTE. When processing a message asynchronously, a copy must be made of the RMessage2 object. Saving a refernece or pointer to the original message will produce unpredictable defects. This is because the object will be reused for the next message that the server receives.

In both cases, synchronous and asynchronous, the derived implementation has the option of updating the aAction and/or aMissing parameters if that is appropriate.

Parameters

aMsg	The message to check.
aAction	A reference to the action to take if the security check fails. This is either a value from TFailureAction or a negative value which has meaning to the CustomFailureActionL() method of a derived class. The policy server framework gives this value a default of EFailClient. If a derived implementation wishes a different value, then it should change this.
aMissing	A reference to the list of security attributes missing from the checked process. The policy server initialises this object to zero (that is a sid of 0, a vid of 0, and no capabilities). If derived implementations wish to take advantage of a list of missing attributes in their implementation of CustomFailureActionL(), then they should set those missing attributes here in CustomSecurityCheckL().

Returns: A value from TCustomResult.
Panic condition: CBase 95 If the default implementation is called.

◆ Extension_()

IMPORT_C TInt CPolicyServer::Extension_	(	TUint	aExtensionId,
		TAny *&	a0,
		TAny *	a1
	)

protectedvirtual

Extension function.

(generated from Symbian Developer Library)

Reimplemented from CServer2.

◆ ProcessError()

IMPORT_C void CPolicyServer::ProcessError	(	const RMessage2 &	aMsg,
		TInt	aError
	)

Called if a leave occurs during processing of a message.

The underlying framework ensures that leaves which occur during CSession2::ServiceL are passed to CSession2::ServiceError. Leaves occuring prior to this (ie. during CustomSecurityCheckL() or CustomFailureActionL() ) are completed with the leave code.

This function should only ever be called by derived implementations if asynchronous security checks are in use. In this case the RunError() of that other active object must call ProcessError().

Parameters

aMsg	The message being processed when the leave occurred.
aError	The leave code.

◆ ProcessL()

IMPORT_C void CPolicyServer::ProcessL ( const RMessage2 & aMsg )

Process an accepted message which has passed its policy check.

The message is either passed to the ServiceL() method of a session, or, in the case of a connection message, a new session is created.

This is called by RunL() to process a message which has passed its security check. If the server implementation returns EAsync from either CustomSecurityCheckL() or CustomFailureActionL(), then it is the responsibility of the derived server implementation to call ProcessL at a later point if the messages passes the asynchronous check.

This function should only ever be called by derived implementations if asynchronous security checks are in use.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ TCustomResult

◆ TFailureAction

◆ TSpecialCase

Constructor & Destructor Documentation

◆ CPolicyServer()

Member Function Documentation

◆ CheckFailedL()

◆ CustomFailureActionL()

◆ CustomSecurityCheckL()

◆ Extension_()

◆ ProcessError()

◆ ProcessL()