/*
* Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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: Defines Runtime security manager's core class. Defines
* APIs for runtime bindings and clients to access security
* management functionalities
*
*/
#ifndef _CRTSECMANAGER_H
#define _CRTSECMANAGER_H
#include <e32base.h>
#include <rtsecmgrcommondef.h>
#include <rtsecmgrtrustinfo.h>
class CRTSecMgrScriptSession;
class MSecMgrPromptHandler;
class CRTSecMgrClientProxy;
class CTrustInfo;
class CPermission;
/**
* Core class of the runtime recurity manager component.
*
* Runtime security manager broadly offers
*
* - Policy management functions
* - Script management functions
* - Access permission check
*
* CRTSecManager offers methods to perform policy management functionalities
* such as
* - Registering runtime security access policy
* - Updating the registered security access policy
* - Un-registering the registered security access policy
*
* Similarly, CRTSecManager offers methods for script management such as
* - Registering a runtime script with security manager
* - Un-registering the registered script
* - Obtaining scipt session associated with the registered script
*
* The main functionality of CRTSecManager is to perform access permission
* check using script session functions
*
* @lib rtsecmgrclient.lib
*/
NONSHARABLE_CLASS(CRTSecManager) : public CBase
{
public:
/**
* Two-phased constructor
*
* Constructs a CRTSecManager instance
*
* Initializes client side security manager session. Starts the security
* manager server, if it is not already running.
*
* @return pointer to an instance of CRTSecManager
*/
IMPORT_C static CRTSecManager* NewL();
/**
* Two-phased constructor
*
* Constructs a CRTSecManager instance and leaves the created instance
* onto the cleanupstack.
*
* Initializes client side security manager session. Starts the security
* manager server, if it is not already running.
*
* @return pointer to an instance of CRTSecManager
*/
IMPORT_C static CRTSecManager* NewLC();
/**
* Destructor
*
* Closes client side security manager session
*/
IMPORT_C ~CRTSecManager();
/**
* Registers a runtime security policy. Runtimes should call this function
* to register their security access and trust policies.
*
* @param aSecPolicy RFile Handle to security policy file
*
* @return TPolicyID generated policy identifier if successul; Otherwise one of
* system wide error codes
*
* \note
* Clients should call ShareProtected on the file session object as shown below.
*
* @code *
* RFs fileSession;
* fileSession.Connect();
* fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy
*
* RFile secPolicyFile;
* secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );
* TPolicyID policyID = secMgr->SetPolicy(secPolicyFile);
*
* if(policyID <= KErrNone)
* {
* //error..
* }
*
* @endcode
*
*/
IMPORT_C TPolicyID SetPolicy(const RFile& aSecPolicy);
/**
* Registers a runtime security policy. Runtimes should call this function
* to register their security access and trust policies.
*
* @param aPolicyBuffer const TDesC& security policy file buffer
*
* @return TPolicyID generated policy identifier if successul; Otherwise one of
* system wide error codes
*
* \note
* Clients should call ShareProtected on the file session object as shown below.
*
* @code *
* RFs fileSession;
* fileSession.Connect();
* fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy
*
* RFile secPolicyFile;
* secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );
* HBufC8* fileBuffer = HBufC8::NewL(KFileBufferMaxLen);
* secPolicyFile.Read(*fileBuffer);
*
* TPolicyID policyID = secMgr->SetPolicy(*fileBuffer);
*
* if(policyID <= KErrNone)
* {
* //error..
* }
*
* @endcode
*
*/
IMPORT_C TPolicyID SetPolicy(const TDesC8& aPolicyBuffer);
/**
* UnRegisters a registered security policy. Runtimes should call this function
* to de-register the already registered security policy.
*
* @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
*
* @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone
*
*/
IMPORT_C TInt UnSetPolicy(TPolicyID aPolicyID);
/**
* Updates an already registered security policy. Runtimes should call this function
* to update their policy.
*
* @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
* @param aSecPolicy RFile Handle to security policy file
*
* @see SetPolicy for file session pre-conditions
*
* @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID
*
*/
IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const RFile& aSecPolicy);
/**
* Updates an already registered security policy. Runtimes should call this function
* to update their policy.
*
* @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
* @param aPolicyBuffer const TDesC& security policy file buffer
*
* @see SetPolicy for file session pre-conditions
*
* @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID
*
*/
IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const TDesC8& aPolicyBuffer);
/**
* Registers a script/executable. Runtimes should specify the trust information
* of the script to be registered.
*
* @param aPolicyID TPolicyID Runtime's registered policy identifier
* @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
*
* @return TExecutableID generated executable identifier if successul; Otherwise one of
* system wide error codes
*
*/
IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo);
/**
* Registers a script/executable. Runtimes should specify the trust information
* of the script to be registered.
*
* @param aPolicyID TPolicyID Runtime's registered policy identifier
* @param aHashMarker const TDesC& Hash value to identify script when starting script session
* @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
*
* @return TExecutableID generated executable identifier if successul; Otherwise one of
* system wide error codes
*
*/
IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const TDesC& aHashMarker, const CTrustInfo& aTrustInfo);
/**
* De-Registers a script/executable. Runtimes should pass the previously registered
* script identifier corresponding to the script to be de-registered.
*
* @param aExeID TExecutableID A valid script identifier
*
* @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone
*
*/
IMPORT_C TInt UnRegisterScript(TExecutableID aExeID, TPolicyID aPolicyID);
/**
* Creates a script session instance. CRTSecMgrScriptSession performs access permission
* check for native platform service invocation. A CRTSecMgrScriptSession instance needs to
* be created for every instance of scripts which could potentially invoke platform service.
*
* @param aPolicyID TPolicyID Valid registered policy identifier
* @param aExeID TExecutableID Script identifier, KAnonymousScript in case of anonymous script session
* @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
* will supply a default prompt handler
*
* @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;
* Otherwise NULL
*/
IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, TExecutableID aExecID, MSecMgrPromptHandler* aPromptHdlr=NULL , const TDesC& aHashValue = KNullDesC);
/**
* Creates a script session instance for an unregisterd trusted script. CRTSecMgrScriptSession performs access permission
* check for native platform service invocation.
*
* @param aPolicyID TPolicyID Valid registered policy identifier
* @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
* @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
* will supply a default prompt handler
*
* @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession;
* NULL in case of invalid policy identifier
*
*
*/
IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo, MSecMgrPromptHandler* aPromptHdlr=NULL);
/**
* Creates a script session instance. CRTSecMgrScriptSession performs access permission
* check for native platform service invocation. A CRTSecMgrScriptSession instance needs to
* be created for every instance of scripts which could potentially invoke platform service.
*
* @param aPolicyID TPolicyID Valid registered policy identifier
* @param aExeID TExecutableID Script identifier, KAnonymousScript in case of anonymous script session
* @param aHashValue TDesC hash value passed while registering the script
* @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
* will supply a default prompt handler
*
* @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;
* Otherwise NULL
IMPORT_C CRTSecMgrScriptSession* GetScriptSession(TPolicyID aPolicyID, TExecutableID aExecID, const TDesC& aHashValue, MSecMgrPromptHandler* aPromptHdlr=NULL);*/
private:
//Private default constructor
CRTSecManager();
//Part of second-phase constructor
void ConstructL();
private:
//Proxy to client side session object
CRTSecMgrClientProxy* iClientProxy;
};
#endif //_CRTSECMANAGER_H