Collapse all Symbian^3 Product Developer Library

TSecurityPolicy Class Reference

class TSecurityPolicy

Class representing a generic security policy

This class can specify a security policy consisting of either:

A check for between 0 and 7 capabilities
A check for a given Secure ID along with 0-3 capabilities
A check for a given Vendor ID along with 0-3 capabilities

If multiple capabilities are specified, all of them must be present for the security check to succeed ('AND' relation).

The envisaged use case for this class is to specify access rights to an object managed either by the kernel or by a server but in principle owned by a client and usable in a limited way by other clients. For example

Publish and Subscribe properties
DBMS databases

In these cases the owning client would pass one (or more) of these objects to the server to specify which security checks should be done on other clients before allowing access to the object.

To pass a TSecurityPolicy object via IPC, a client should obtain a descriptor for the object using Package() and send this. When a server receives this descriptor it should read the descriptor contents into a TSecurityPolicyBuf and then Set() should be used to create a policy object from this.

Because this class has non-default constructors, compilers will not initialise this object at compile time, instead code will be generated to construct the object at run-time. This is wasteful - and Symbian OS DLLs are not permitted to have such uninitialised data. To overcome these problems a set of macros are provided to construct a const object which behaves like a TSecurityPolicy. These are:

_LIT_SECURITY_POLICY_C1 through _LIT_SECURITY_POLICY_C7, _LIT_SECURITY_POLICY_S0 through _LIT_SECURITY_POLICY_S3 and _LIT_SECURITY_POLICY_V0 through _LIT_SECURITY_POLICY_V3.

Also, the macros _LIT_SECURITY_POLICY_PASS and _LIT_SECURITY_POLICY_FAIL are provided in order to allow easy construction of a const object which can be used as a TSecuityPolicy which always passes or always fails, respectively.

If a security policy object is needed to be embedded in another class then the TStaticSecurityPolicy structure can be used. This behaves in the same way as a TSecurityPolicy object but may be initialised at compile time.

TStaticSecurityPolicy TSecurityPolicyBuf _LIT_SECURITY_POLICY_PASS _LIT_SECURITY_POLICY_FAIL _LIT_SECURITY_POLICY_C1 _LIT_SECURITY_POLICY_C2 _LIT_SECURITY_POLICY_C3 _LIT_SECURITY_POLICY_C4 _LIT_SECURITY_POLICY_C5 _LIT_SECURITY_POLICY_C6 _LIT_SECURITY_POLICY_C7 _LIT_SECURITY_POLICY_S0 _LIT_SECURITY_POLICY_S1 _LIT_SECURITY_POLICY_S2 _LIT_SECURITY_POLICY_S3 _LIT_SECURITY_POLICY_V0 _LIT_SECURITY_POLICY_V1 _LIT_SECURITY_POLICY_V2 _LIT_SECURITY_POLICY_V3

Public Member Functions
	TSecurityPolicy()
	TSecurityPolicy(TSecPolicyType)
	TSecurityPolicy(TCapability, TCapability, TCapability)
	TSecurityPolicy(TCapability, TCapability, TCapability, TCapability, TCapability, TCapability, TCapability)
	TSecurityPolicy(TSecureId, TCapability, TCapability, TCapability)
	TSecurityPolicy(TVendorId, TCapability, TCapability, TCapability)
TBool	CheckPolicy(RProcess, const char *)
TBool	CheckPolicy(RThread, const char *)
TBool	CheckPolicy(RMessagePtr2, const char *)
TBool	CheckPolicy(RMessagePtr2, TSecurityInfo &, const char *)
TInt	CheckPolicy(RSessionBase)
TBool	CheckPolicyCreator(const char *)
IMPORT_C TPtrC8	Package()
IMPORT_C TInt	Set(const TDesC8 &)
TBool	Validate()

Protected Member Functions
TBool	CheckPolicy(const SSecurityInfo &, SSecurityInfo &)

Private Member Functions
void	ConstructAndCheck3(TCapability, TCapability, TCapability)
IMPORT_C TBool	DoCheckPolicy(RProcess, const char *)
IMPORT_C TBool	DoCheckPolicy(RProcess)
IMPORT_C TBool	DoCheckPolicy(RThread, const char *)
IMPORT_C TBool	DoCheckPolicy(RThread)
IMPORT_C TBool	DoCheckPolicy(RMessagePtr2, const char *)
IMPORT_C TBool	DoCheckPolicy(RMessagePtr2)
TBool	DoCheckPolicy(RMessagePtr2, TSecurityInfo &, const char *)
TBool	DoCheckPolicy(RMessagePtr2, TSecurityInfo &)
IMPORT_C TBool	DoCheckPolicyCreator(const char *)
IMPORT_C TBool	DoCheckPolicyCreator()

Public Member Enumerations
enum	TSecPolicyType { EAlwaysFail = 0, EAlwaysPass = 1 }
enum	TType { ETypeFail = 0, ETypePass = 1, ETypeC3 = 2, ETypeC7 = 3, ETypeS3 = 4, ETypeV3 = 5, ETypeLimit }

Public Attributes
TUint8	iExtraCaps
TUint32	iSecureId
TUint32	iVendorId

Private Attributes
union TSecurityPolicy::@15	@16
TUint8	iCaps
TUint8	iType

Constructor & Destructor Documentation

TSecurityPolicy()

TSecurityPolicy

(

)

[inline]

Constructs a TSecurityPolicy that will always fail, irrespective of the checked object's attributes.

TSecurityPolicy(TSecPolicyType)

IMPORT_C

TSecurityPolicy

(

TSecPolicyType

aType

)

Constructs a TSecurityPolicy to either always pass or always fail checks made against it, depending on the value of aType.

panic: USER 191 if aType is not a valid value

Parameters

TSecPolicyType aType

Must be one of EAlwaysPass or EAlwaysFail

TSecurityPolicy(TCapability, TCapability, TCapability)

IMPORT_C	TSecurityPolicy	(	TCapability	aCap1,
			TCapability	aCap2 = ECapability_None,
			TCapability	aCap3 = ECapability_None
		)

Construct a TSecurityPolicy object to check up to 3 capabilties.

panic: USER 189 If any of the supplied capabilities are not valid.

Parameters

TCapability aCap1	The first capability to add to this policy
TCapability aCap2 = ECapability_None	An optional second capability to add to this policy
TCapability aCap3 = ECapability_None	An optional third capability to add to this policy

TSecurityPolicy(TCapability, TCapability, TCapability, TCapability, TCapability, TCapability, TCapability)

IMPORT_C	TSecurityPolicy	(	TCapability	aCap1,
			TCapability	aCap2,
			TCapability	aCap3,
			TCapability	aCap4,
			TCapability	aCap5 = ECapability_None,
			TCapability	aCap6 = ECapability_None,
			TCapability	aCap7 = ECapability_None
		)

Construct a TSecurityPolicy object to check up to 7 capabilties.

panic: USER 189 If any of the supplied capabilities are not valid.

Parameters

TCapability aCap1	The first capability to add to this policy
TCapability aCap2	The second capability to add to this policy
TCapability aCap3	The third capability to add to this policy
TCapability aCap4	The fourth capability to add to this policy
TCapability aCap5 = ECapability_None	An optional fifth capability to add to this policy
TCapability aCap6 = ECapability_None	An optional sixth capability to add to this policy
TCapability aCap7 = ECapability_None	An optional seventh capability to add to this policy

TSecurityPolicy(TSecureId, TCapability, TCapability, TCapability)

IMPORT_C	TSecurityPolicy	(	TSecureId	aSecureId,
			TCapability	aCap1 = ECapability_None,
			TCapability	aCap2 = ECapability_None,
			TCapability	aCap3 = ECapability_None
		)

Construct a TSecurityPolicy object to check a secure id and up to 3 capabilties.

panic: USER 189 If any of the supplied capabilities are not valid.

Parameters

TSecureId aSecureId	The secure id to add to this policy
TCapability aCap1 = ECapability_None	The first capability to add to this policy
TCapability aCap2 = ECapability_None	The second capability to add to this policy
TCapability aCap3 = ECapability_None	The third capability to add to this policy

TSecurityPolicy(TVendorId, TCapability, TCapability, TCapability)

IMPORT_C	TSecurityPolicy	(	TVendorId	aVendorId,
			TCapability	aCap1 = ECapability_None,
			TCapability	aCap2 = ECapability_None,
			TCapability	aCap3 = ECapability_None
		)

Construct a TSecurityPolicy object to check a vendor id and up to 3 capabilties.

panic: USER 189 If any of the supplied capabilities are not valid.

Parameters

TVendorId aVendorId	The vendor id to add to this policy
TCapability aCap1 = ECapability_None	The first capability to add to this policy
TCapability aCap2 = ECapability_None	The second capability to add to this policy
TCapability aCap3 = ECapability_None	The third capability to add to this policy

Member Functions Documentation

CheckPolicy(RProcess, const char *)

TBool	CheckPolicy	(	RProcess	aProcess,
			const char *	aDiagnostic = 0
		)	const [inline]

Checks this policy against the platform security attributes of aProcess.

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RProcess aProcess	The RProcess object to check against this TSecurityPolicy.
const char * aDiagnostic = 0	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

CheckPolicy(RThread, const char *)

TBool	CheckPolicy	(	RThread	aThread,
			const char *	aDiagnostic = 0
		)	const [inline]

Checks this policy against the platform security attributes of the process owning aThread.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RThread aThread	The thread whose owning process' platform security attributes are to be checked against this TSecurityPolicy.
const char * aDiagnostic = 0	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

CheckPolicy(RMessagePtr2, const char *)

TBool	CheckPolicy	(	RMessagePtr2	aMsgPtr,
			const char *	aDiagnostic = 0
		)	const [inline]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr	The RMessagePtr2 object to check against this TSecurityPolicy.
const char * aDiagnostic = 0	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

CheckPolicy(RMessagePtr2, TSecurityInfo &, const char *)

TBool	CheckPolicy	(	RMessagePtr2	aMsgPtr,
			TSecurityInfo &	aMissing,
			const char *	aDiagnostic = 0
		)	const [inline]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr	The RMessagePtr2 object to check against this TSecurityPolicy.
TSecurityInfo & aMissing	A TSecurityInfo object which this method fills with any capabilities or IDs it finds to be missing.
const char * aDiagnostic = 0	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

CheckPolicy(RSessionBase)

TInt

CheckPolicy

(

RSessionBase

aSession

)

const

Parameters

RSessionBase aSession

CheckPolicy(const SSecurityInfo &, SSecurityInfo &)

TBool	CheckPolicy	(	const SSecurityInfo &	aSecInfo,
			SSecurityInfo &	aMissing
		)	const [protected]

Checks this policy against the supplied SSecurityInfo.

panic: USER 190 if aSecInfo is an invalid SSecurityInfo object otherwise.

Parameters

const SSecurityInfo & aSecInfo	The SSecurityInfo object to check against this TSecurityPolicy.
SSecurityInfo & aMissing	A SSecurityInfo object which this method fills with any capabilities or IDs it finds to be missing. This is designed to help generating diagnostic messages.

CheckPolicyCreator(const char *)

TBool

CheckPolicyCreator

(

const char *

aDiagnostic = 0

)

const [inline]

Checks this policy against the platform security attributes of this process' creator.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

const char * aDiagnostic = 0

A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

ConstructAndCheck3(TCapability, TCapability, TCapability)

void	ConstructAndCheck3	(	TCapability	aCap1,
			TCapability	aCap2,
			TCapability	aCap3
		)	[private]

Sets up iCaps[0-2] with supplied values and checks for their validity.

panic: USER 189 If any of the supplied capabilities are invalid.

Parameters

TCapability aCap1
TCapability aCap2
TCapability aCap3

DoCheckPolicy(RProcess, const char *)

IMPORT_C TBool	DoCheckPolicy	(	RProcess	aProcess,
			const char *	aDiagnostic
		)	const [private]

Checks this policy against the platform security attributes of aProcess.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RProcess aProcess	The RProcess object to check against this TSecurityPolicy.
const char * aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

DoCheckPolicy(RProcess)

IMPORT_C TBool

DoCheckPolicy

(

RProcess

aProcess

)

const [private]

Checks this policy against the platform security attributes of aProcess.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RProcess aProcess

The RProcess object to check against this TSecurityPolicy.

DoCheckPolicy(RThread, const char *)

IMPORT_C TBool	DoCheckPolicy	(	RThread	aThread,
			const char *	aDiagnostic
		)	const [private]

Checks this policy against the platform security attributes of the process owning aThread.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RThread aThread	The thread whose owning process' platform security attributes are to be checked against this TSecurityPolicy.
const char * aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

DoCheckPolicy(RThread)

IMPORT_C TBool

DoCheckPolicy

(

RThread

aThread

)

const [private]

Checks this policy against the platform security attributes of the process owning aThread.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RThread aThread

The thread whose owning process' platform security attributes are to be checked against this TSecurityPolicy.

DoCheckPolicy(RMessagePtr2, const char *)

IMPORT_C TBool	DoCheckPolicy	(	RMessagePtr2	aMsgPtr,
			const char *	aDiagnostic
		)	const [private]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr	The RMessagePtr2 object to check against this TSecurityPolicy.
const char * aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

DoCheckPolicy(RMessagePtr2)

IMPORT_C TBool

DoCheckPolicy

(

RMessagePtr2

aMsgPtr

)

const [private]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr

The RMessagePtr2 object to check against this TSecurityPolicy.

DoCheckPolicy(RMessagePtr2, TSecurityInfo &, const char *)

TBool	DoCheckPolicy	(	RMessagePtr2	aMsgPtr,
			TSecurityInfo &	aMissing,
			const char *	aDiagnostic
		)	const [private]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr	The RMessagePtr2 object to check against this TSecurityPolicy.
TSecurityInfo & aMissing	A TSecurityInfo object which this method fills with any capabilities or IDs it finds to be missing.
const char * aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

DoCheckPolicy(RMessagePtr2, TSecurityInfo &)

TBool	DoCheckPolicy	(	RMessagePtr2	aMsgPtr,
			TSecurityInfo &	aMissing
		)	const [private]

Checks this policy against the platform security attributes of the process which sent the given message.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

RMessagePtr2 aMsgPtr	The RMessagePtr2 object to check against this TSecurityPolicy.
TSecurityInfo & aMissing	A TSecurityInfo object which this method fills with any capabilities or IDs it finds to be missing.

DoCheckPolicyCreator(const char *)

IMPORT_C TBool

DoCheckPolicyCreator

(

const char *

aDiagnostic

)

const [private]

Checks this policy against the platform security attributes of this process' creator.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Parameters

const char * aDiagnostic

DoCheckPolicyCreator()

IMPORT_C TBool

DoCheckPolicyCreator

(

)

const [private]

Checks this policy against the platform security attributes of this process' creator.

panic: USER 190 if 'this' is an invalid SSecurityInfo object

Package()

IMPORT_C TPtrC8

Package

(

)

const

Constructs a TPtrC8 wrapping the platform security attributes of this TSecurityPolicy. Such a descriptor is suitable for passing across the client server boundary.

The format of the descriptor is determined by the first byte which specifies the type of this TSecurityPolicy. The first byte is one of the constants specified in the enum TSecurityPolicy::TType.

For TSecurityPolicy objects of types ETypeC3, ETypeS3, ETypePass or ETypeFail the descriptor will contain the following data in the order listed:

	TUint8 iType; 		// set to ETypeC3, ETypeS3, ETypePass or ETypeFail
	TUint8 iCaps[3];
	TUint32 iSecureId;

ETypeC3 descriptors will contain capabilities in iCaps but have iSecureId set to ECapability_None. ETypeS3 are similar to ETypeC3 descriptors but will have iSecureId set to the secure ID value of the TSecurityPolicy object. ETypePass and ETypeFail objects will have values of all of the elements of iCaps and iSecureId set to ECapability_None.

For TSecurityPolicy objects of type ETypeV3 the descriptor will contain the following data in the order listed:

	TUint8 iType;		// set to ETypeV3
	TUint8 iCaps[3];	// set to the values of 3 capabilities
	TUint32 iVendorId;	// set to the value of the vendor ID of the TSecurityPolicy

For TSecurityPolicy objects of type ETypeC7 the descriptor will contain the following data in the order listed:

	TUint8 iType;			// set to ETypeC7
	TUint8 iCaps[3];		// set to the values of 3 of the objects capabilities
	TUint8 iExtraCaps[4];	// set to the values of 4 of the objects capabilities

TSecurityPolicy::TType TSecurityPolicy::Set()

Set(const TDesC8 &)

IMPORT_C TInt

Set

(

const TDesC8 &

aDes

)

Sets this TSecurityPolicy to a copy of the policy described by the supplied descriptor. Such a descriptor can be obtained from TSecurityPolicy::Package(). TSecurityPolicy::Package()

Parameters

const TDesC8 & aDes

A descriptor representing the state of another TSecurityPolicy.

Validate()

TBool

Validate

(

)

const

Checks that this object is in a valid state

Member Enumerations Documentation

Enum TSecPolicyType

Enumerators

EAlwaysFail = 0
EAlwaysPass = 1

Enum TType

Constants to specify the type of TSecurityPolicy objects.

Enumerators

ETypeFail = 0	Always fail
ETypePass = 1	Always pass
ETypeC3 = 2	Up to 3 capabilities
ETypeC7 = 3	Up to 7 capabilities
ETypeS3 = 4	Secure ID and up to 3 capabilities
ETypeV3 = 5	Vendor ID and up to 3 capabilities
ETypeLimit	The number of possible TSecurityPolicy types This is intended for internal Symbian use only.

Member Data Documentation

union TSecurityPolicy::@15 @16

union TSecurityPolicy::@15

@16

[private]

TUint8 iCaps

TUint8

iCaps

[private]

TUint8 iExtraCaps

TUint8

iExtraCaps

TUint32 iSecureId

TUint32

iSecureId

TUint8 iType

TUint8

iType

[private]

TUint32 iVendorId

TUint32

iVendorId