1 /*

     2 * Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:       Defines Runtime security manager's core class. Defines

    15  * 				  APIs for runtime bindings and clients to access security

    16  * 				  management functionalities

    17  *

    18 */

    19 

    20 

    21 

    22 

    23 

    24 

    25 #ifndef _CRTSECMANAGER_H

    26 #define _CRTSECMANAGER_H

    27 

    28 #include <e32base.h>

    29 

    30 #include <rtsecmgrcommondef.h>

    31 #include <rtsecmgrtrustinfo.h>

    32 

    33 class CRTSecMgrScriptSession;

    34 class MSecMgrPromptHandler;

    35 class CRTSecMgrClientProxy;

    36 class CTrustInfo;

    37 class CPermission;

    38 

    39 /**

    40  * Core class of the runtime recurity manager component.

    41  * 

    42  * Runtime security manager broadly offers 

    43  *

    44  *  - Policy management functions

    45  *	- Script management functions

    46  *  - Access permission check

    47  *

    48  * CRTSecManager offers methods to perform policy management functionalities

    49  * such as 

    50  * 	- Registering runtime security access policy

    51  * 	- Updating the registered security access policy

    52  * 	- Un-registering the registered security access policy 

    53  * 

    54  * Similarly, CRTSecManager offers methods for script management such as

    55  * 	- Registering a runtime script with security manager

    56  * 	- Un-registering the registered script

    57  * 	- Obtaining scipt session associated with the registered script

    58  * 

    59  * The main functionality of CRTSecManager is to perform access permission

    60  * check using script session functions

    61  * 

    62  * @lib rtsecmgrclient.lib

    63  */

    64 NONSHARABLE_CLASS(CRTSecManager) : public CBase

    65 	{

    66 public:

    67 

    68 	/**

    69 	 * Two-phased constructor

    70 	 * 

    71 	 * Constructs a CRTSecManager instance

    72 	 *

    73 	 * Initializes client side security manager session. Starts the security

    74 	 * manager server, if it is not already running.

    75 	 * 

    76 	 * @return pointer to an instance of CRTSecManager

    77 	 */

    78 	IMPORT_C static CRTSecManager* NewL();

    79 

    80 	/**

    81 	 * Two-phased constructor

    82 	 * 

    83 	 * Constructs a CRTSecManager instance and leaves the created instance

    84 	 * onto the cleanupstack.

    85 	 *

    86 	 * Initializes client side security manager session. Starts the security

    87 	 * manager server, if it is not already running.

    88 	 * 

    89 	 * @return pointer to an instance of CRTSecManager

    90 	 */

    91 	IMPORT_C static CRTSecManager* NewLC();

    92 

    93 	/**

    94 	 * Destructor

    95 	 * 

    96 	 * Closes client side security manager session

    97 	 */

    98 	IMPORT_C ~CRTSecManager();

    99 

   100 	/**

   101 	 * Registers a runtime security policy. Runtimes should call this function

   102 	 * to register their security access and trust policies.

   103 	 *

   104 	 * @param aSecPolicy RFile Handle to security policy file

   105 	 *

   106 	 * @return TPolicyID generated policy identifier if successul; Otherwise one of

   107 	 *					 system wide error codes

   108 	 *

   109 	 * \note

   110 	 * Clients should call ShareProtected on the file session object as shown below.

   111 	 * 

   112 	 * @code	 * 

   113 	 * 	RFs fileSession;

   114 	 * 	fileSession.Connect();

   115 	 * 	fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy

   116 	 * 

   117 	 * 	RFile secPolicyFile;

   118 	 * 	secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );

   119 	 * 	TPolicyID policyID = secMgr->SetPolicy(secPolicyFile);

   120 	 *

   121 	 *  if(policyID <= KErrNone)

   122 	 *  {

   123 	 *		//error..

   124 	 *	}

   125 	 * 

   126 	 * @endcode

   127 	 * 

   128 	 */

   129 	IMPORT_C TPolicyID SetPolicy(const RFile& aSecPolicy);

   130 	

   131 	/**

   132 	 * Registers a runtime security policy. Runtimes should call this function

   133 	 * to register their security access and trust policies.

   134 	 *

   135 	 * @param aPolicyBuffer const TDesC& security policy file buffer

   136 	 *

   137 	 * @return TPolicyID generated policy identifier if successul; Otherwise one of

   138 	 *					 system wide error codes

   139 	 *

   140 	 * \note

   141 	 * Clients should call ShareProtected on the file session object as shown below.

   142 	 * 

   143 	 * @code	 * 

   144 	 * 	RFs fileSession;

   145 	 * 	fileSession.Connect();

   146 	 * 	fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy

   147 	 * 

   148 	 * 	RFile secPolicyFile;

   149 	 * 	secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );	 

   150 	 *  HBufC8* fileBuffer = HBufC8::NewL(KFileBufferMaxLen);

   151 	 *  secPolicyFile.Read(*fileBuffer);

   152 	 *   

   153 	 * 	TPolicyID policyID = secMgr->SetPolicy(*fileBuffer);

   154 	 *

   155 	 *  if(policyID <= KErrNone)

   156 	 *  {

   157 	 *		//error..

   158 	 *	}

   159 	 * 

   160 	 * @endcode

   161 	 * 

   162 	 */

   163 	IMPORT_C TPolicyID SetPolicy(const TDesC8& aPolicyBuffer);

   164 

   165 	/**

   166 	 * UnRegisters a registered security policy. Runtimes should call this function

   167 	 * to de-register the already registered security policy.

   168 	 *

   169 	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy

   170 	 *

   171 	 * @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone

   172 	 *    

   173 	 */

   174 	IMPORT_C TInt UnSetPolicy(TPolicyID aPolicyID);

   175 

   176 	/**

   177 	 * Updates an already registered security policy. Runtimes should call this function

   178 	 * to update their policy.

   179 	 *

   180 	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy

   181 	 * @param aSecPolicy RFile Handle to security policy file

   182 	 *

   183 	 * @see SetPolicy for file session pre-conditions

   184 	 *

   185 	 * @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID

   186 	 *

   187 	 */

   188 	IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const RFile& aSecPolicy);

   189 

   190 	/**

   191 	 * Updates an already registered security policy. Runtimes should call this function

   192 	 * to update their policy.

   193 	 *

   194 	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy

   195 	 * @param aPolicyBuffer const TDesC& security policy file buffer

   196 	 *

   197 	 * @see SetPolicy for file session pre-conditions

   198 	 *

   199 	 * @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID

   200 	 *

   201 	 */

   202 	IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const TDesC8& aPolicyBuffer);

   203 	

   204 	/**

   205 	 * Registers a script/executable. Runtimes should specify the trust information

   206 	 * of the script to be registered. 

   207 	 *

   208 	 * @param aPolicyID TPolicyID   Runtime's registered policy identifier

   209 	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object

   210 	 *

   211 	 * @return TExecutableID generated executable identifier if successul; Otherwise one of

   212 	 *					 	 system wide error codes

   213 	 *

   214 	 */

   215 	IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo);

   216 

   217 	/**

   218 	 * Registers a script/executable. Runtimes should specify the trust information

   219 	 * of the script to be registered. 

   220 	 *

   221 	 * @param aPolicyID TPolicyID   Runtime's registered policy identifier

   222 	 * @param aHashMarker const TDesC& Hash value to identify script when starting script session

   223 	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object

   224 	 *

   225 	 * @return TExecutableID generated executable identifier if successul; Otherwise one of

   226 	 *					 	 system wide error codes

   227 	 *

   228 	 */

   229 	IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const TDesC& aHashMarker, const CTrustInfo& aTrustInfo);

   230 

   231 	/**

   232 	 * De-Registers a script/executable. Runtimes should pass the previously registered

   233 	 * script identifier corresponding to the script to be de-registered.

   234 	 *

   235 	 * @param aExeID TExecutableID   A valid script identifier

   236 	 *

   237 	 * @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone

   238 	 *     

   239 	 */

   240 	IMPORT_C TInt UnRegisterScript(TExecutableID aExeID, TPolicyID aPolicyID);

   241 

   242 	/**

   243 	 * Creates a script session instance. CRTSecMgrScriptSession performs access permission

   244 	 * check for native platform service invocation. A CRTSecMgrScriptSession instance needs to

   245 	 * be created for every instance of scripts which could potentially invoke platform service.

   246 	 *

   247 	 * @param aPolicyID TPolicyID    Valid registered policy identifier

   248 	 * @param aExeID TExecutableID   Script identifier, KAnonymousScript in case of anonymous script session

   249 	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager

   250 	 *							     will supply a default prompt handler

   251 	 *

   252 	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;

   253 	 * Otherwise NULL

   254 	 */

   255 	IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, TExecutableID aExecID, MSecMgrPromptHandler* aPromptHdlr=NULL , const TDesC& aHashValue = KNullDesC);

   256 

   257 	/**

   258 	 * Creates a script session instance for an unregisterd trusted script. CRTSecMgrScriptSession performs access permission

   259 	 * check for native platform service invocation. 

   260 	 *

   261 	 * @param aPolicyID TPolicyID    Valid registered policy identifier

   262 	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object

   263 	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager

   264 	 *							     will supply a default prompt handler

   265 	 *

   266 	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession;

   267 	 * 								  NULL in case of invalid policy identifier

   268 	 *           

   269 	 *     

   270 	 */

   271 	IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo, MSecMgrPromptHandler* aPromptHdlr=NULL);

   272 

   273 	/**

   274 	 * Creates a script session instance. CRTSecMgrScriptSession performs access permission

   275 	 * check for native platform service invocation. A CRTSecMgrScriptSession instance needs to

   276 	 * be created for every instance of scripts which could potentially invoke platform service.

   277 	 *

   278 	 * @param aPolicyID TPolicyID    Valid registered policy identifier

   279 	 * @param aExeID TExecutableID   Script identifier, KAnonymousScript in case of anonymous script session

   280 	 * @param aHashValue TDesC		 hash value passed while registering the script

   281 	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager

   282 	 *							     will supply a default prompt handler

   283 	 *

   284 	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;

   285 	 * Otherwise NULL

   286 	 

   287 	IMPORT_C CRTSecMgrScriptSession* GetScriptSession(TPolicyID aPolicyID, TExecutableID aExecID, const TDesC& aHashValue, MSecMgrPromptHandler* aPromptHdlr=NULL);*/

   288 private:

   289 	//Private default constructor

   290 	CRTSecManager();

   291 

   292 	//Part of second-phase constructor

   293 	void ConstructL();

   294 

   295 private:

   296 	//Proxy to client side session object

   297 	CRTSecMgrClientProxy* iClientProxy;

   298 	};

   299 #endif //_CRTSECMANAGER_H

   300