// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// Wrapper around RMessage2 that provides message validation and error handling
// to improve robustness of system servers under IPC attack
//
//
#if !defined(CLIENTMESSAGE_H)
#define CLIENTMESSAGE_H
#include <e32std.h>
#include <e32base.h>
#include <e32debug.h>
#include <babitflags.h>
namespace BSUL
{
//Version number of the client server framework code
const TInt KClientMessageVersion = 0x1;
//Forward Declarations
class CMessageParameterBase;
//Const Declarations
/**
Returned to caller to indicate that the requested message number is not
supported by the current server
@publishedPartner
@released
*/
const TInt KErrInvalidFunction = -1004;
/**
Returned to caller if a message is passed in containing a non-descriptor
parameter which doesn't meet the constraints specified in the schema
@publishedPartner
@released
*/
const TInt KErrBadParameter = -1005;
/**
Returned to caller in UREL mode when the server attempts to call a
CMessageParameterBase function which is not defined for the given
parameter type. E.g. calling GetIntL() on a Descriptor parameter.
@publishedPartner
@released
*/
const TInt KErrWrongParameterType = -1006;
/**
Returned to caller in UREL mode when a message is found to be
incorrectly defined in the message schema.
@publishedPartner
@released
*/
const TInt KErrBadMessageSchema = -1007;
/**
Returned to caller to indicate that the requested parameter has not yet
been validated
@publishedPartner
@released
*/
const TInt KErrNotValidated = -1008; //Server internal error
/**
Returned to caller to indicate that the ClientMessage framework has
not yet been initialised
@publishedPartner
@released
*/
const TInt KErrNotInitialised = -1009; //Server internal error
//Enum Declarations
/**
This is the list of Panic codes used by the ClientMessage framework
@publishedPartner
@released
*/
enum
{
/**This panic is raised in UDEB mode when the server attempts to call a
CMessageParameterBase function which is not defined for the given
parameter type. E.g. calling GetIntL() on a Descriptor parameter.
*/
ECMPanicWrongParameterType = 0,
/**This panic is raised when the server attempts to read from a
descriptor in the clients process and supplies a target descriptor
that is smaller than the client descriptor.
*/
ECMPanicBadDescriptor,
/**This panic is raised when a TParameterDetails structure for a
given parameter is incorrectly defined in the message schema
*/
ECMPanicBadMessageSchema
};
/**
This Enum lists the currently supported Parameter types.
These enum values are used as indices to the Parameter Factory Function
which instantiates the appropriate CMessageParammeterBase derived
object to represent a given message parameter.
@publishedPartner
@released
*/
enum TParamType
{
EParamNull = 0,
EParamInt,
EParamDes8Read,
EParamDes8,
EParamPckg,
EParamDes16Read,
EParamDes16,
EParamPtr
};
/**
This enum lists the currently supported flags that can be passed to the server
in TClientMessageServerData::iFlags. Note that internally this value is stored
in a TBitFlags32 type but this type cannot be statically initialised in a dll
so the value is passed to the framework in a TInt. The bottom 16 bit flags are
reserved for the framework's internal use.
@publishedPartner
@released
*/
enum TServerFlags
{
/** Default empty flag */
ESrvFlagNone = 0,
/** Setting this flag indicates that for bad message errors, request
should be completed with error code rather than panicking the client */
ESrvFlagDoNotPanicClientOnBadMessageErrors = 0x40000000,
/** Indicates that bad messages should be logged in UDEB */
ESrvFlagLogBadMessages = 0x80000000
};
//Typedef Declarations
/**
This typedef is used to simplify the declaration of custom
parameter validation functions
@publishedPartner
@released
*/
typedef void (*TCustomValidationFn)(CMessageParameterBase* aParameter);
//Struct Declarations
/**
This structure defines the format for storing information for an
individual message parameter.
iType - This defines the parameter type and is used by the CMessageParameterBase
class to instantiate the appropriate derived class via the
KParameterFactoryFunctions factory lookup table.
iMin, iMax - These are two constraints that are used in the ValidateL
method of a class derived from CMessageParameter to validate the message
as required by that parameter.
The constraints that are used depend on the type as follows:
EParamInt:
-iMin = Minimum int value accepted
-iMax = Maximum int value accepted. This must be > iMin
NOTE: Currently unsigned integers are not explicitly supported,
however 16 bit unsigned integers are implicitly supported
by the EParamInt type. Note that the constraint above
(iMax > iMin) means that the maximum supported value for an
unsigned int is 0x7FFFFFFF.
EParamDes8Read:
EParamDes16Read:
-iMin = Minimum length of descriptor in clients address space.
If no minimum restriction exists this should be set to 0 in
the schema. This must be >= 0
-iMax = Maximum length of descriptor in clients address space.
The descriptor supplied by the client must not have a
length that exceeds this value. This must be >= iMin
EParamDes8:
EParamDes16:
-iMin = Minimum MaxLength of descriptor in clients address space.
The descriptor supplied by the client must have a MaxLength
that is at least as big as this value. This must be >= 0
-iMax = Maximum length of descriptor in clients address space.
The descriptor supplied by the client must not have a
length that exceeds this value. This must be >= 0.
NOTE: As the EParamDes* types use MaxLength() as a restriction
They cannot be used if the client intends to pass a TDesC
derived descriptor. If the client intends read only use
then the explicit EParamDes*Read types should be used instead.
EParamPckg:
-iMin = Minimum length of descriptor in clients address space.
If no minimum restriction exists this should be set to 0 in
the schema. This must be >= 0
-iMax = Maximum length of descriptor in clients address space.
The descriptor supplied by the client must not have a
length that exceeds this value. This must be >= iMin
EParamPtr:
-iMin = Unused
-iMax = Unused
@publishedPartner
@released
*/
struct TParameterDetails
{
const TInt iType;
const TInt iMin;
const TInt iMax;
};
/**
This struct is used to represent a single message from the client.
It defines the function number corresponding to the message, the security
policy for the message, the number of paramaters that are passed to the
function and the type and constraint information for each of the parameters
as described above. The server must define an array of these objects to be
used by CClientMessage to validate all incoming messages.
NOTE: It is assumed that the message parameters are contiguous. I.E. if there is one
parameter it is assumed to be located at index 0, if there are 2 parameters they
are located at index 0,1 etc.
@publishedPartner
@released
*/
struct TClientMessageSchema
{
//Version number of the framework
const TInt iVersion;
//The message number described by this schema
const TInt iFunction;
//The security policy for this message. The CClientMessage framework
//uses this security policy to police incoming messages.
const TStaticSecurityPolicy& iPolicy;
//The number of parameters expected by this message
const TInt iParamCount;
//The array of TParameterDetails structs describing the
//parameter types and constraints for this message
const TParameterDetails* iParams;
//Reserved values for future proofing
const TInt iReserved1;
const TInt iReserved2;
};
/**
This struct is used to initialise the ClientMessage Framework.
This struct provides the framework with the message schema and
the custom validation functions for the server as well as the server
name and flags.
The struct should be populated by the server using the SERVER_DATA
macro defined below.
@publishedPartner
@released
*/
struct TClientMessageServerData
{
//Version number of this structure
const TInt iVersion;
//The number of messages accepted by this server
const TInt iMessageCount;
//The array of TClientMessageSchema structs defining the schema for
//each message accpeted by this server
const TClientMessageSchema* iMessageSchema;
//The number of custom validation fucntions suplpied by this server
const TInt iValidationFnCount;
//The array of custom validation functions supplied by this server.
//These validation functions are called from ValidateL to provide
//customised validation of any parameter type.
const TCustomValidationFn* iCustomValidationFns;
//The name of the server using the framework. This string is used both
//in logging bad messages and in panicing the client or the server.
//In line with Panic category strings, this value should be 16 characters or less.
const TUint8* iServerName;
//Flags used to pass settings info into the framework. The supported values are
//defined in the TServerFlags enum above.
const TInt iFlags;
//Reserved values for future proofing
const TInt iReserved1;
const TInt iReserved2;
};
//Macro Definitions
/**
This macro is used to simplify declaration of TClientMessageSchema entries.
The function number, security policy and pointer to array of TParameterDetails
structures is converted into the expected format for the declaration of a
TClientMessageSchema structure.
@publishedPartner
@released
*/
#define MESSAGE_SCHEMA(Function,Policy,Params) {KClientMessageVersion,Function,Policy,sizeof(Params)/sizeof(TParameterDetails),Params,0,0}
/**
This TParameterDetails structure is used to represent a message with no
parameters. This is required as the schema expects a const TParameterDetails*.
@publishedPartner
@released
*/
const TParameterDetails KNoParams[1] = {{EParamNull,0,0}};
/**
This macro is used to simplify declaration of TClientMessageSchema entries
for functions with no parameters. Because the number of parameters is set
to 0, a CMessageParameterBase derived object is not instantiated for this
parameter type.
@publishedPartner
@released
*/
#define MESSAGE_SCHEMA_NO_PARAMS(Function,Policy) {KClientMessageVersion,Function,Policy,0,KNoParams,0,0}
/**
This macro is used to simplify declaration of the TClientMessageServerData structure.
The pointer to the array of TClientMessageSchemas, pointer to array of
TCustomValidationFns, server name and server flags are converted into the
expected format for the declaration of a TClientMessageServerData structure.
@publishedPartner
@released
*/
#define SERVER_DATA(ClientMessages,ValidationFns,ServerName,Flags){KClientMessageVersion,sizeof(ClientMessages)/sizeof(TClientMessageSchema),ClientMessages,sizeof(ValidationFns)/sizeof(TCustomValidationFn),ValidationFns,(TUint8*)ServerName,Flags,0,0}
//Class Declarations
/**
This is the abstract base class for all message parameter classes.
The class defines one pure virtual function, ValidateL, which all derived classes
must implement. This class also defines default implementation for the access
methods which should be properly defined in all derived classes.
This class is not intended for external derivation.
@publishedPartner
@released
*/
NONSHARABLE_CLASS(CMessageParameterBase) : public CBase
{
public:
static CMessageParameterBase* CreateL(const TParameterDetails& aParam, TInt aParamIndex,
const RMessage2& aMessage);
virtual void ValidateL() = 0;
virtual ~CMessageParameterBase(){};
virtual TInt GetIntL();
virtual const TAny* GetPtrL();
virtual const TDesC8& GetDes8L();
virtual const TDesC& GetDes16L();
virtual TInt GetDesLengthL();
virtual TInt GetDesMaxLengthL();
virtual void ReadL(TDes8& aDes, TInt aOffset);
virtual void ReadL(TDes& aDes, TInt aOffset);
virtual void WriteL(const TDesC8& aDes, TInt aOffset);
virtual void WriteL(const TDesC& aDes, TInt aOffset);
virtual TInt Min();
virtual TInt Max();
protected:
CMessageParameterBase(const TParameterDetails& aParam, TInt aParamIndex,
const RMessage2& aMessage, TCustomValidationFn aValidationFn);
private:
static TCustomValidationFn GetValidationFunctionL(const TParameterDetails& aParam);
protected:
//The index of this parameter within the corresponding RMessage2 object
TInt iIndex;
//A reference to the RMessage2 object that contains this parameter
const RMessage2& iMessage;
//A reference to the structure that defines the expected type
//and constraints for this parameter
const TParameterDetails& iParamDetails;
//A custom validation function to allow user defined validation
//this function is called from ValidateL
TCustomValidationFn iValidationFn;
};
/**
This class is used by a server to sanitise incoming messages.
The class provides a wrapper around an RMessage2 object and provides a method
for validation of the message against the constraints defined in the message schema.
This class also provides methods for safely accessing the message arguments,
and for error handling and logging of bad messages.
This class is not intended for derivation.
@publishedPartner
@released
*/
NONSHARABLE_CLASS(CClientMessage) : public CBase
{
public:
IMPORT_C static void InitialiseFrameworkL(const TClientMessageServerData& aServerData);
IMPORT_C static CClientMessage* NewL(const RMessage2& aMessage);
IMPORT_C virtual ~CClientMessage();
IMPORT_C TInt Function();
IMPORT_C const RMessage2& Message();
IMPORT_C virtual void ValidateL();
IMPORT_C virtual void ValidateL(TInt aParam);
IMPORT_C virtual void CompleteRequestL(TInt aError);
IMPORT_C virtual void PanicClient(const TDesC& aServer, TInt aPanic);
IMPORT_C virtual TInt GetIntL(TInt aParam);
IMPORT_C virtual const TAny* GetPtrL(TInt aParam);
IMPORT_C virtual const TDesC8& GetDes8L(TInt aParam);
IMPORT_C virtual const TDesC& GetDes16L(TInt aParam);
IMPORT_C virtual TInt GetDesLengthL(TInt aParam);
IMPORT_C virtual TInt GetDesMaxLengthL(TInt aParam);
IMPORT_C virtual void ReadL(TInt aParam, TDes8& aDes, TInt aOffset = 0);
IMPORT_C virtual void ReadL(TInt aParam, TDes16& aDes, TInt aOffset = 0);
IMPORT_C virtual void WriteL(TInt aParam, const TDesC8& aDes, TInt aOffset = 0);
IMPORT_C virtual void WriteL(TInt aParam, const TDesC16& aDes, TInt aOffset = 0);
private:
virtual void LogBadMessageL(TInt aError);
virtual void CheckSecurityPolicyL(const TSecurityPolicy& aPolicy);
CClientMessage(const RMessage2& aMessage,const TClientMessageServerData& aServerData);
void ConstructL();
const TClientMessageSchema* FindMessageSchema();
void CheckValidatedL(TInt aParam);
TBool LogBadMessages();
private:
//Array of pointers to CMessageParameterBase Derived parameter objects used
// to validate and access the individual message arguments
RPointerArray <CMessageParameterBase> iParameters;
//Reference to the underlying RMessage2 wrapped by this object
const RMessage2& iMessage;
//Reference to TClientMessageServerData structure stored in TLS for
//this thread. This structure is passed in to the framework by the server
//on initialisation.
const TClientMessageServerData& iServerData;
//Bit flags for use internally within CClientMessage.
TBitFlags32 iFlags;
};
/**
This class is used for Base64 based encoding and decoding .
This class provides a method for encoding and decoding
@publishedPartner
@released
*/
class Base64Codec
{
// base64 and UU coding defines.
/**
This is the list of Bitmask used for encoding and decoding
@publishedPartner
@released
*/
enum EMaskValues
{
ESixBitMask = 0x3F,
EEightBitMask = 0xFF
};
/**
This is the list of shift values used for encoding and decoding
@publishedPartner
@released
*/
enum EMaskShiftValues
{
ESix = 6,
EFour = 4,
ETwo = 2,
EZero = 0
};
/**
This enum is used as padding charcter
@publishedPartner
@released
*/
enum
{
EPadChar = 64
};
public:
IMPORT_C static TInt Encode(const TDesC8& aSrcString, TDes8& aDestString);
IMPORT_C static TInt Decode(const TDesC8& aSrcString, TDes8& aDestString);
};
}//namespace
#endif