1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/lowlevellibsandfws/apputils/bsul/inc/clientmessage.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,528 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Wrapper around RMessage2 that provides message validation and error handling
1.18 +// to improve robustness of system servers under IPC attack
1.19 +//
1.20 +//
1.21 +
1.22 +#if !defined(CLIENTMESSAGE_H)
1.23 +#define CLIENTMESSAGE_H
1.24 +
1.25 +#include <e32std.h>
1.26 +#include <e32base.h>
1.27 +#include <e32debug.h>
1.28 +#include <babitflags.h>
1.29 +
1.30 +namespace BSUL
1.31 + {
1.32 +
1.33 + //Version number of the client server framework code
1.34 + const TInt KClientMessageVersion = 0x1;
1.35 +
1.36 + //Forward Declarations
1.37 + class CMessageParameterBase;
1.38 +
1.39 + //Const Declarations
1.40 +
1.41 + /**
1.42 + Returned to caller to indicate that the requested message number is not
1.43 + supported by the current server
1.44 + @publishedPartner
1.45 + @released
1.46 + */
1.47 + const TInt KErrInvalidFunction = -1004;
1.48 +
1.49 + /**
1.50 + Returned to caller if a message is passed in containing a non-descriptor
1.51 + parameter which doesn't meet the constraints specified in the schema
1.52 + @publishedPartner
1.53 + @released
1.54 + */
1.55 + const TInt KErrBadParameter = -1005;
1.56 +
1.57 + /**
1.58 + Returned to caller in UREL mode when the server attempts to call a
1.59 + CMessageParameterBase function which is not defined for the given
1.60 + parameter type. E.g. calling GetIntL() on a Descriptor parameter.
1.61 + @publishedPartner
1.62 + @released
1.63 + */
1.64 + const TInt KErrWrongParameterType = -1006;
1.65 +
1.66 + /**
1.67 + Returned to caller in UREL mode when a message is found to be
1.68 + incorrectly defined in the message schema.
1.69 + @publishedPartner
1.70 + @released
1.71 + */
1.72 + const TInt KErrBadMessageSchema = -1007;
1.73 +
1.74 +
1.75 + /**
1.76 + Returned to caller to indicate that the requested parameter has not yet
1.77 + been validated
1.78 + @publishedPartner
1.79 + @released
1.80 + */
1.81 + const TInt KErrNotValidated = -1008; //Server internal error
1.82 +
1.83 + /**
1.84 + Returned to caller to indicate that the ClientMessage framework has
1.85 + not yet been initialised
1.86 + @publishedPartner
1.87 + @released
1.88 + */
1.89 + const TInt KErrNotInitialised = -1009; //Server internal error
1.90 +
1.91 +
1.92 + //Enum Declarations
1.93 +
1.94 + /**
1.95 + This is the list of Panic codes used by the ClientMessage framework
1.96 + @publishedPartner
1.97 + @released
1.98 + */
1.99 + enum
1.100 + {
1.101 + /**This panic is raised in UDEB mode when the server attempts to call a
1.102 + CMessageParameterBase function which is not defined for the given
1.103 + parameter type. E.g. calling GetIntL() on a Descriptor parameter.
1.104 + */
1.105 + ECMPanicWrongParameterType = 0,
1.106 +
1.107 + /**This panic is raised when the server attempts to read from a
1.108 + descriptor in the clients process and supplies a target descriptor
1.109 + that is smaller than the client descriptor.
1.110 + */
1.111 + ECMPanicBadDescriptor,
1.112 +
1.113 + /**This panic is raised when a TParameterDetails structure for a
1.114 + given parameter is incorrectly defined in the message schema
1.115 + */
1.116 + ECMPanicBadMessageSchema
1.117 + };
1.118 +
1.119 + /**
1.120 + This Enum lists the currently supported Parameter types.
1.121 + These enum values are used as indices to the Parameter Factory Function
1.122 + which instantiates the appropriate CMessageParammeterBase derived
1.123 + object to represent a given message parameter.
1.124 + @publishedPartner
1.125 + @released
1.126 + */
1.127 + enum TParamType
1.128 + {
1.129 + EParamNull = 0,
1.130 + EParamInt,
1.131 + EParamDes8Read,
1.132 + EParamDes8,
1.133 + EParamPckg,
1.134 + EParamDes16Read,
1.135 + EParamDes16,
1.136 + EParamPtr
1.137 + };
1.138 +
1.139 + /**
1.140 + This enum lists the currently supported flags that can be passed to the server
1.141 + in TClientMessageServerData::iFlags. Note that internally this value is stored
1.142 + in a TBitFlags32 type but this type cannot be statically initialised in a dll
1.143 + so the value is passed to the framework in a TInt. The bottom 16 bit flags are
1.144 + reserved for the framework's internal use.
1.145 +
1.146 + @publishedPartner
1.147 + @released
1.148 + */
1.149 + enum TServerFlags
1.150 + {
1.151 + /** Default empty flag */
1.152 + ESrvFlagNone = 0,
1.153 + /** Setting this flag indicates that for bad message errors, request
1.154 + should be completed with error code rather than panicking the client */
1.155 + ESrvFlagDoNotPanicClientOnBadMessageErrors = 0x40000000,
1.156 + /** Indicates that bad messages should be logged in UDEB */
1.157 + ESrvFlagLogBadMessages = 0x80000000
1.158 + };
1.159 +
1.160 + //Typedef Declarations
1.161 +
1.162 + /**
1.163 + This typedef is used to simplify the declaration of custom
1.164 + parameter validation functions
1.165 + @publishedPartner
1.166 + @released
1.167 + */
1.168 + typedef void (*TCustomValidationFn)(CMessageParameterBase* aParameter);
1.169 +
1.170 +
1.171 +
1.172 + //Struct Declarations
1.173 +
1.174 + /**
1.175 + This structure defines the format for storing information for an
1.176 + individual message parameter.
1.177 +
1.178 + iType - This defines the parameter type and is used by the CMessageParameterBase
1.179 + class to instantiate the appropriate derived class via the
1.180 + KParameterFactoryFunctions factory lookup table.
1.181 +
1.182 + iMin, iMax - These are two constraints that are used in the ValidateL
1.183 + method of a class derived from CMessageParameter to validate the message
1.184 + as required by that parameter.
1.185 + The constraints that are used depend on the type as follows:
1.186 + EParamInt:
1.187 + -iMin = Minimum int value accepted
1.188 + -iMax = Maximum int value accepted. This must be > iMin
1.189 +
1.190 + NOTE: Currently unsigned integers are not explicitly supported,
1.191 + however 16 bit unsigned integers are implicitly supported
1.192 + by the EParamInt type. Note that the constraint above
1.193 + (iMax > iMin) means that the maximum supported value for an
1.194 + unsigned int is 0x7FFFFFFF.
1.195 +
1.196 + EParamDes8Read:
1.197 + EParamDes16Read:
1.198 + -iMin = Minimum length of descriptor in clients address space.
1.199 + If no minimum restriction exists this should be set to 0 in
1.200 + the schema. This must be >= 0
1.201 + -iMax = Maximum length of descriptor in clients address space.
1.202 + The descriptor supplied by the client must not have a
1.203 + length that exceeds this value. This must be >= iMin
1.204 + EParamDes8:
1.205 + EParamDes16:
1.206 + -iMin = Minimum MaxLength of descriptor in clients address space.
1.207 + The descriptor supplied by the client must have a MaxLength
1.208 + that is at least as big as this value. This must be >= 0
1.209 + -iMax = Maximum length of descriptor in clients address space.
1.210 + The descriptor supplied by the client must not have a
1.211 + length that exceeds this value. This must be >= 0.
1.212 +
1.213 + NOTE: As the EParamDes* types use MaxLength() as a restriction
1.214 + They cannot be used if the client intends to pass a TDesC
1.215 + derived descriptor. If the client intends read only use
1.216 + then the explicit EParamDes*Read types should be used instead.
1.217 +
1.218 + EParamPckg:
1.219 + -iMin = Minimum length of descriptor in clients address space.
1.220 + If no minimum restriction exists this should be set to 0 in
1.221 + the schema. This must be >= 0
1.222 + -iMax = Maximum length of descriptor in clients address space.
1.223 + The descriptor supplied by the client must not have a
1.224 + length that exceeds this value. This must be >= iMin
1.225 +
1.226 + EParamPtr:
1.227 + -iMin = Unused
1.228 + -iMax = Unused
1.229 + @publishedPartner
1.230 + @released
1.231 + */
1.232 + struct TParameterDetails
1.233 + {
1.234 + const TInt iType;
1.235 + const TInt iMin;
1.236 + const TInt iMax;
1.237 + };
1.238 +
1.239 + /**
1.240 + This struct is used to represent a single message from the client.
1.241 + It defines the function number corresponding to the message, the security
1.242 + policy for the message, the number of paramaters that are passed to the
1.243 + function and the type and constraint information for each of the parameters
1.244 + as described above. The server must define an array of these objects to be
1.245 + used by CClientMessage to validate all incoming messages.
1.246 +
1.247 + NOTE: It is assumed that the message parameters are contiguous. I.E. if there is one
1.248 + parameter it is assumed to be located at index 0, if there are 2 parameters they
1.249 + are located at index 0,1 etc.
1.250 +
1.251 + @publishedPartner
1.252 + @released
1.253 + */
1.254 + struct TClientMessageSchema
1.255 + {
1.256 +
1.257 + //Version number of the framework
1.258 + const TInt iVersion;
1.259 +
1.260 + //The message number described by this schema
1.261 + const TInt iFunction;
1.262 +
1.263 + //The security policy for this message. The CClientMessage framework
1.264 + //uses this security policy to police incoming messages.
1.265 + const TStaticSecurityPolicy& iPolicy;
1.266 +
1.267 + //The number of parameters expected by this message
1.268 + const TInt iParamCount;
1.269 +
1.270 + //The array of TParameterDetails structs describing the
1.271 + //parameter types and constraints for this message
1.272 + const TParameterDetails* iParams;
1.273 +
1.274 + //Reserved values for future proofing
1.275 + const TInt iReserved1;
1.276 + const TInt iReserved2;
1.277 + };
1.278 +
1.279 + /**
1.280 + This struct is used to initialise the ClientMessage Framework.
1.281 + This struct provides the framework with the message schema and
1.282 + the custom validation functions for the server as well as the server
1.283 + name and flags.
1.284 + The struct should be populated by the server using the SERVER_DATA
1.285 + macro defined below.
1.286 + @publishedPartner
1.287 + @released
1.288 + */
1.289 + struct TClientMessageServerData
1.290 + {
1.291 + //Version number of this structure
1.292 + const TInt iVersion;
1.293 +
1.294 + //The number of messages accepted by this server
1.295 + const TInt iMessageCount;
1.296 +
1.297 + //The array of TClientMessageSchema structs defining the schema for
1.298 + //each message accpeted by this server
1.299 + const TClientMessageSchema* iMessageSchema;
1.300 +
1.301 + //The number of custom validation fucntions suplpied by this server
1.302 + const TInt iValidationFnCount;
1.303 +
1.304 + //The array of custom validation functions supplied by this server.
1.305 + //These validation functions are called from ValidateL to provide
1.306 + //customised validation of any parameter type.
1.307 + const TCustomValidationFn* iCustomValidationFns;
1.308 +
1.309 + //The name of the server using the framework. This string is used both
1.310 + //in logging bad messages and in panicing the client or the server.
1.311 + //In line with Panic category strings, this value should be 16 characters or less.
1.312 + const TUint8* iServerName;
1.313 +
1.314 + //Flags used to pass settings info into the framework. The supported values are
1.315 + //defined in the TServerFlags enum above.
1.316 + const TInt iFlags;
1.317 +
1.318 + //Reserved values for future proofing
1.319 + const TInt iReserved1;
1.320 + const TInt iReserved2;
1.321 + };
1.322 +
1.323 + //Macro Definitions
1.324 +
1.325 + /**
1.326 + This macro is used to simplify declaration of TClientMessageSchema entries.
1.327 + The function number, security policy and pointer to array of TParameterDetails
1.328 + structures is converted into the expected format for the declaration of a
1.329 + TClientMessageSchema structure.
1.330 + @publishedPartner
1.331 + @released
1.332 + */
1.333 + #define MESSAGE_SCHEMA(Function,Policy,Params) {KClientMessageVersion,Function,Policy,sizeof(Params)/sizeof(TParameterDetails),Params,0,0}
1.334 +
1.335 +
1.336 + /**
1.337 + This TParameterDetails structure is used to represent a message with no
1.338 + parameters. This is required as the schema expects a const TParameterDetails*.
1.339 + @publishedPartner
1.340 + @released
1.341 + */
1.342 + const TParameterDetails KNoParams[1] = {{EParamNull,0,0}};
1.343 +
1.344 + /**
1.345 + This macro is used to simplify declaration of TClientMessageSchema entries
1.346 + for functions with no parameters. Because the number of parameters is set
1.347 + to 0, a CMessageParameterBase derived object is not instantiated for this
1.348 + parameter type.
1.349 + @publishedPartner
1.350 + @released
1.351 + */
1.352 + #define MESSAGE_SCHEMA_NO_PARAMS(Function,Policy) {KClientMessageVersion,Function,Policy,0,KNoParams,0,0}
1.353 +
1.354 +
1.355 + /**
1.356 + This macro is used to simplify declaration of the TClientMessageServerData structure.
1.357 + The pointer to the array of TClientMessageSchemas, pointer to array of
1.358 + TCustomValidationFns, server name and server flags are converted into the
1.359 + expected format for the declaration of a TClientMessageServerData structure.
1.360 + @publishedPartner
1.361 + @released
1.362 + */
1.363 + #define SERVER_DATA(ClientMessages,ValidationFns,ServerName,Flags){KClientMessageVersion,sizeof(ClientMessages)/sizeof(TClientMessageSchema),ClientMessages,sizeof(ValidationFns)/sizeof(TCustomValidationFn),ValidationFns,(TUint8*)ServerName,Flags,0,0}
1.364 +
1.365 +
1.366 + //Class Declarations
1.367 +
1.368 + /**
1.369 + This is the abstract base class for all message parameter classes.
1.370 + The class defines one pure virtual function, ValidateL, which all derived classes
1.371 + must implement. This class also defines default implementation for the access
1.372 + methods which should be properly defined in all derived classes.
1.373 + This class is not intended for external derivation.
1.374 + @publishedPartner
1.375 + @released
1.376 + */
1.377 + NONSHARABLE_CLASS(CMessageParameterBase) : public CBase
1.378 + {
1.379 + public:
1.380 + static CMessageParameterBase* CreateL(const TParameterDetails& aParam, TInt aParamIndex,
1.381 + const RMessage2& aMessage);
1.382 + virtual void ValidateL() = 0;
1.383 + virtual ~CMessageParameterBase(){};
1.384 +
1.385 + virtual TInt GetIntL();
1.386 + virtual const TAny* GetPtrL();
1.387 + virtual const TDesC8& GetDes8L();
1.388 + virtual const TDesC& GetDes16L();
1.389 + virtual TInt GetDesLengthL();
1.390 + virtual TInt GetDesMaxLengthL();
1.391 + virtual void ReadL(TDes8& aDes, TInt aOffset);
1.392 + virtual void ReadL(TDes& aDes, TInt aOffset);
1.393 + virtual void WriteL(const TDesC8& aDes, TInt aOffset);
1.394 + virtual void WriteL(const TDesC& aDes, TInt aOffset);
1.395 +
1.396 + virtual TInt Min();
1.397 + virtual TInt Max();
1.398 +
1.399 + protected:
1.400 + CMessageParameterBase(const TParameterDetails& aParam, TInt aParamIndex,
1.401 + const RMessage2& aMessage, TCustomValidationFn aValidationFn);
1.402 +
1.403 + private:
1.404 + static TCustomValidationFn GetValidationFunctionL(const TParameterDetails& aParam);
1.405 +
1.406 + protected:
1.407 + //The index of this parameter within the corresponding RMessage2 object
1.408 + TInt iIndex;
1.409 +
1.410 + //A reference to the RMessage2 object that contains this parameter
1.411 + const RMessage2& iMessage;
1.412 +
1.413 + //A reference to the structure that defines the expected type
1.414 + //and constraints for this parameter
1.415 + const TParameterDetails& iParamDetails;
1.416 +
1.417 + //A custom validation function to allow user defined validation
1.418 + //this function is called from ValidateL
1.419 + TCustomValidationFn iValidationFn;
1.420 +
1.421 + };
1.422 +
1.423 + /**
1.424 + This class is used by a server to sanitise incoming messages.
1.425 + The class provides a wrapper around an RMessage2 object and provides a method
1.426 + for validation of the message against the constraints defined in the message schema.
1.427 + This class also provides methods for safely accessing the message arguments,
1.428 + and for error handling and logging of bad messages.
1.429 + This class is not intended for derivation.
1.430 + @publishedPartner
1.431 + @released
1.432 + */
1.433 + NONSHARABLE_CLASS(CClientMessage) : public CBase
1.434 + {
1.435 + public:
1.436 + IMPORT_C static void InitialiseFrameworkL(const TClientMessageServerData& aServerData);
1.437 + IMPORT_C static CClientMessage* NewL(const RMessage2& aMessage);
1.438 + IMPORT_C virtual ~CClientMessage();
1.439 +
1.440 + IMPORT_C TInt Function();
1.441 + IMPORT_C const RMessage2& Message();
1.442 + IMPORT_C virtual void ValidateL();
1.443 + IMPORT_C virtual void ValidateL(TInt aParam);
1.444 + IMPORT_C virtual void CompleteRequestL(TInt aError);
1.445 + IMPORT_C virtual void PanicClient(const TDesC& aServer, TInt aPanic);
1.446 +
1.447 + IMPORT_C virtual TInt GetIntL(TInt aParam);
1.448 + IMPORT_C virtual const TAny* GetPtrL(TInt aParam);
1.449 + IMPORT_C virtual const TDesC8& GetDes8L(TInt aParam);
1.450 + IMPORT_C virtual const TDesC& GetDes16L(TInt aParam);
1.451 + IMPORT_C virtual TInt GetDesLengthL(TInt aParam);
1.452 + IMPORT_C virtual TInt GetDesMaxLengthL(TInt aParam);
1.453 + IMPORT_C virtual void ReadL(TInt aParam, TDes8& aDes, TInt aOffset = 0);
1.454 + IMPORT_C virtual void ReadL(TInt aParam, TDes16& aDes, TInt aOffset = 0);
1.455 + IMPORT_C virtual void WriteL(TInt aParam, const TDesC8& aDes, TInt aOffset = 0);
1.456 + IMPORT_C virtual void WriteL(TInt aParam, const TDesC16& aDes, TInt aOffset = 0);
1.457 +
1.458 + private:
1.459 + virtual void LogBadMessageL(TInt aError);
1.460 + virtual void CheckSecurityPolicyL(const TSecurityPolicy& aPolicy);
1.461 + CClientMessage(const RMessage2& aMessage,const TClientMessageServerData& aServerData);
1.462 + void ConstructL();
1.463 + const TClientMessageSchema* FindMessageSchema();
1.464 + void CheckValidatedL(TInt aParam);
1.465 + TBool LogBadMessages();
1.466 +
1.467 + private:
1.468 + //Array of pointers to CMessageParameterBase Derived parameter objects used
1.469 + // to validate and access the individual message arguments
1.470 + RPointerArray <CMessageParameterBase> iParameters;
1.471 +
1.472 + //Reference to the underlying RMessage2 wrapped by this object
1.473 + const RMessage2& iMessage;
1.474 +
1.475 + //Reference to TClientMessageServerData structure stored in TLS for
1.476 + //this thread. This structure is passed in to the framework by the server
1.477 + //on initialisation.
1.478 + const TClientMessageServerData& iServerData;
1.479 +
1.480 + //Bit flags for use internally within CClientMessage.
1.481 + TBitFlags32 iFlags;
1.482 + };
1.483 + /**
1.484 + This class is used for Base64 based encoding and decoding .
1.485 + This class provides a method for encoding and decoding
1.486 + @publishedPartner
1.487 + @released
1.488 + */
1.489 + class Base64Codec
1.490 + {
1.491 + // base64 and UU coding defines.
1.492 + /**
1.493 + This is the list of Bitmask used for encoding and decoding
1.494 + @publishedPartner
1.495 + @released
1.496 + */
1.497 + enum EMaskValues
1.498 + {
1.499 + ESixBitMask = 0x3F,
1.500 + EEightBitMask = 0xFF
1.501 + };
1.502 +
1.503 + /**
1.504 + This is the list of shift values used for encoding and decoding
1.505 + @publishedPartner
1.506 + @released
1.507 + */
1.508 + enum EMaskShiftValues
1.509 + {
1.510 + ESix = 6,
1.511 + EFour = 4,
1.512 + ETwo = 2,
1.513 + EZero = 0
1.514 + };
1.515 +
1.516 + /**
1.517 + This enum is used as padding charcter
1.518 + @publishedPartner
1.519 + @released
1.520 + */
1.521 + enum
1.522 + {
1.523 + EPadChar = 64
1.524 + };
1.525 + public:
1.526 + IMPORT_C static TInt Encode(const TDesC8& aSrcString, TDes8& aDestString);
1.527 + IMPORT_C static TInt Decode(const TDesC8& aSrcString, TDes8& aDestString);
1.528 + };
1.529 + }//namespace
1.530 +
1.531 +#endif