Symbian OS Changes for Platform Security

This page provides details of the API and functional changes from 7.0s as a result of platform security. Also, see this table of new file locations for Symbian OS v9.0 and beyond.

Note: This page contains references to engineering documents that are available on Symbian OS DevKits, but not on public SDKs.

It includes sections for:

• Application engines

• Application framework

• Application services

• Base

• Bluetooth

• Comms infrastructure

• Connectivity

• J2ME

• Messaging

• Multimedia

• Networking

• Security

• Serial Comms

• SyncML

• System libraries

• Telephony

• Tools

This section describes the changes that must be made to the Application Engines following the introduction of Platform Security. It describes:

• Configuration macros

• Agenda model

• Contacts model

• Data caging

The Application engines APIs must be configured with these macros:

• SYMBIAN_SUPPORT_COREAPPS_API_V1 - if this is defined, the Application engines APIs are not secure and existing code does not need changing.

• SYMBIAN_HIDE_COREAPPS_API_V1 - if this is defined, the Application engines components do not need to be rebuilt, but the non-secure APIs can no longer be used.

• SYMBIAN_REMOVE_COREAPPS_API_V1 - if this is defined, the Application engines APIs are secure, but the Core Applications components and applications using them must be rebuilt.

The APIs that expose the underlying stream stores are no longer supported. You must access the agenda model (Agnmodel) indirectly, through the agenda server. Consequently, the following functions are not supported:

• CAgnEntryModel

  • CAgnEntryModel::OpenL() - overloads with CStreamStore& and TStreamId parameters

  • CAgnEntryModel::SaveAsL(), CAgnEntryModel::SaveTodoListsL() - both overloads

  • CAgnEntryModel::CreateL() - overloads with a CStreamStore& parameter

  • CAgnEntryModel::IsValidL()

  • CAgnEntryModel::SetMode().

• CAgnEntry

  • CAgnEntry::StoreComponentsL()

  • CAgnEntry::RestoreComponentsL()

  • CAgnEntry::SetRichTextStreamId().

• CAgnIndexedModel

  • CAgnIndexedModel::MergeL()

  • CAgnIndexedModel::TidyByDateL() - overloads with a CStreamStore* parameter

  • CAgnIndexedModel::TidyByTodoListL() - overloads with a CStreamStore* parameter

  • CAgnIndexedModel::OpenL() - overloads with a CStreamStore& parameter.

The following functions are new:

• CAgnEntryModel

  • CAgnEntryModel::SecureSaveTodoListsL()

  • CAgnEntryModel::DeleteAgendaFileL()

  • CAgnEntryModel::GetDefaultFileNameL()

  • CAgnEntryModel::ListAgendaFilesL().

• CAgnIndexedModel::TidyByTodoListL(), CAgnIndexedModel::TidyByDateL() - new overloads with a file name parameter.

The filename of an agenda file must now be a combination of a drive letter and a filename, without a full path; for example: c:agenda. This affects the functions: CAgnEntryModel::OpenL() and CAgnIndexedModel::OpenL().

This section describes the following aspects of the Contacts Model (Cntmodel):

• New asynchronous functions for opening a contact database

• Working with device backup and restore

New asynchronous functions for opening a contact database

Two new functions introduced with Platform Security use the new CContactOpenOperation active object class to open a contact database asynchronously:

• CContactOpenOperation* CContactDatabase::Open(TRequestStatus& aClientStatus, TThreadAccess aAccess)

• CContactOpenOperation* CContactDatabase::Open(const TDesC& aFileName, TRequestStatus& aClientStatus, TThreadAccess aAccess).

Use these functions when you expect the database to open slowly, for example, when it has been corrupted.

The client must store the CContactOpenOperation object pointer. The TRequestStatus passed to these functions typically belongs to an active object. When the CContactDatabase::Open() completes or fails, the active object is scheduled to run. If the result is KErrNone, the client can take ownership of the opened database with the function:

CContactDatabase* CContactOpenOperation::TakeDatabase()

The CContactOpenOperation object should then be deleted. If it is deleted before CContactOpenOperation::TakeDatabase() succeeds, the Open() is cancelled. If it is deleted after the Open() has completed, the database is closed.

Working with device backup and restore

Contact databases cannot be written to during device Backup or used during device Restore. At these times most applications are closed on the device by the User Interface framework, but some clients of the Contact Model use system services which continue running during Backup and Restore. On Symbian OS up to v8.0 the correct behaviour of these is to get the database filename and observe backup and restore operations affecting that file.

Getting the contact database name and registering for backup/restore notification uses code like this:

class CXyz {
    ...
    CBaBackupSessionWrapper* iBackup;
    TFilename iDatabaseName;
    ...
    }

CContactDatabase::GetDefaultNameL(iDatabaseName);
iBackup = CBaBackupSessionWrapper::NewL();
iBackup->RegisterFileL(iDatabaseName, *this);

Before a Backup or Restore starts, you must close the CContactDatabase. You can re-open it when the operation is complete. New Backup & Restore behaviour was introduced in Symbian OS v8.1 for the Contact Model, and from v9.0 the CContactDatabase::FindContactFile() function is deprecated and you should use CContactDatabase::GetDefaultNameL() instead. The CContactDatabase can be kept during Backup and Restore, but the following new notifications, (in TContactDbObserverEventType), must be acted upon:

• EContactDbObserverEventBackupBeginning - The Contacts database is about to be backed-up, any add or edit operation must be closed for the backup to succeed. Only read access is available until the matching EContactDbObserverEventBackupRestoreCompleted notification.

• EContactDbObserverEventRestoreBeginning - The Contacts database is about to be restored, any add or edit operation must be closed. No access should be made until the matching EContactDbObserverEventBackupRestoreCompleted notification. If the restored database is unreadable the EContactDbObserverEventRestoreBadDatabase is received instead.

• EContactDbObserverEventBackupRestoreCompleted - The backup/restore operation has completed.

• EContactDbObserverEventRestoreBadDatabase - The restore operation has completed but the database could not be opened. The problem could be anything from the restored database being corrupt to an out of memory error.

This section describes the Platform Security data caging used to secure the Agenda and Contacts data files and any plugins used by them.

Capability Level

Under Platform Security, all executables and DLLs have a capability level, which defines their trustworthiness and prevents malicious or badly implemented binaries from using Symbian-provided servers.

Note: The total capability of a process is equal to that of the sub-component with the lowest capability.

Accessing agenda data files

Agenda data files are created and stored on the secure platform in the agenda server’s private directory, which can be on any drive. Only the agenda server can access these private files. Several APIs are used to create, list and delete files in the private directory.

The user capabilities ReadUserData and WriteUserData are required to add, modify and delete agenda and to-do items.

Accessing contacts data files

The default contacts data file (Contacts.cdb) is managed by the Syslibs DBMS component. On the secure platform, this file is stored in the DBMS server’s private directory, which can be on any drive. Contacts databases cannot be created or stored outside this directory. Several APIs are used to create, list and delete files in the private directory.

The CntModel.ini file contains several settings used by the contacts lock server, such as the drive that holds the default database. On the secure platform, CntModel.ini is stored in the contacts lock server’s private directory on the C: drive.

The user capabilities ReadUserData and WriteUserData are required to add, modify and delete contact items, and to create, modify and delete contact views.

Contact database functions affected by platform security

In the data caged environment most applications cannot determine which contact databases exist. Applications with the All Files capability should not assume specific file locations, as these may change. As with the Agenda Model, database filenames passed to the Contact Model no longer contain pathnames.

This affects the following functions:

• CContactDatabase::OpenL()

• CContactDatabase::ReplaceL()

• CContactDatabase::CreateL()

• CContactDatabase::RecreateSystemTemplateL()

• CContactDatabase::GetDefaultNameL()

• CContactDatabase::ListDatabasesL()

• CContactDatabase::DeleteDatabaseL()

• CContactDatabase::ContactDatabaseExistsL().

Several new functions assist clients:

• TBool CContactDatabase::DefaultContactDatabaseExistsL()

• TBool CContactDatabase::ContactDatabaseExistsL(const TDesC& aFileName)

• CDesCArray* CContactDatabase::ListDatabasesL(TDriveUnit aDriveUnit)

• CDesCArray* CContactDatabase::ListDatabasesL()

• void CContactDatabase::DeleteDatabaseL(const TDesC& aFileName).

There already is a corresponding delete function for the default database: void CContactDatabase::DeleteDefaultFileL().

In the non-data-caged environment of Symbian OS v8.1, these functions dealt with full pathnames and the ListDatabasesL() functions search for contact databases in any directory on the device.

Note: Owing to data caging, the behaviour of the void CContactDatabase::GetDefaultNameL(TDes &aDes) function may no longer be what you expect.

The TBool CContactDatabase::FindContactFile(TDes &aFileName) function was removed in Symbian OS v9.0. Known callers should use GetDefaultNameL() instead.

Data files used by the App-Engines subsystem

Description Component File Name Location in un-secured platform Location in secured platform Agenda data files Agnmodel Any name Anywhere C:\Private\10003A5B\ (agenda server’s private directory) Contact database Cntmodel Contacts.cdb C:\System\Data C:\Private\100012a5\ (DBMS server’s private directory) Contact lock server INI file Cntmodel Cntmodel.ini C:\System\Data C:\Private\10003A73 (contact lock server’s private directory) Contact model resource file Cntmodel Cntmodel.rsc Z:\System\Data Z:\Resource\Cntmodel Sheet engine resource file Sheng Sheng.rsc Z:\System\Apps\Sheet Z:\Resource\Sheng

Backup and restore

To ensure that they are backed-up, Agenda and Contacts data files have corresponding backup registration files (backup_registration.xml) in their private data areas (which are automatically protected). These registration files contain details of the files to be backed up, and the backup/restore mode that is supported (in this case it is passive mode).

In addition, Contacts uses the new, configurable notification mechanism, involving the Publish & Subscribe API, to handle file access during a Backup/Restore. This ensures that views behave safely, and makes Contacts more robust.

Capabilities granted to DLLs and executables

The following App-Engines DLLs have the Platform Security capability All – TCB:

AGNMODEL.DLL AGNVERSIT.DLL CALINTERIMAPI.DLL CHART.DLL CNTPHONE.DLL CNTVCARD.DLL CNTVIEW.DLL CNTMODEL.DLL TXTWORD.CNV DAMODL.DLL SHENG.DLL WPENG.DLL

This means that all files are visible, except those under /sys and /resource, and that extra write access is granted to files under /private. These DLLs have a high capability so that most applications can link to them.

The capabilities for subsystem executables are as follows:

Component Executable Capabilities Rationale Agnmodel Agsvexe.exe Protserv ReadUserData WriteUserData WriteDeviceData ReadUserData, WriteUserData and WriteDeviceData capabilities are required because the agenda server adds and removes alarms using the alarm server. Agsvexe.exe statically links to agnmodel.dll; which links to alarmclient.dll. AlarmServer.exe prevents access to clients without ReadUserData, WriteDeviceData and WriteUserData capabilities, so AlarmClient.dll must have these capabilities. Therefore, the agenda server must also have ReadUserData/WriteUserData capabilities. Cntmodel Cntsrv.exe Protserv ReadUserData WriteUserData ReadUserData and WriteUserData capabilities are required to read and write SIM card entries. Cntsrv.exe links to cntmodel.dll, which dynamically loads Phbksyncplugin.DLL, which uses RPhoneBookSession. RPhoneBookSession prevents access to clients without ReadUserData and WriteUserData capabilities. Therefore, cntsrv.exe needs these capabilities.

Plugin security

Agnmodel and Cntmodel provide several plugins for modularity and licensee extension. On the secure platform, these plugins have all been migrated to the ECOM framework, which uses a file registry rather than a loading process to scan the file system.

A summary of the status of each plugin is given below:

Component Plugin Name Framework type, unsecure platform API classification Implementation impacted Agnmodel Agenda Observer Custom Published All Licensee, Third party Agnmodel Connectivity Filter Custom Published Partner Symbian, Licensee, Third Party Agnmodel vCalendar converter (Agnversit) Custom Published Partner Symbian, Licensee Cntmodel vCard import/export (Cntvcard) Custom Published Partner Symbian Cntmodel Phone parser Custom Published Partner Symbian Cntmodel Phonebook Synchronisation (implemented by Telephony/Phbksync) Custom Published Partner Symbian Cntmodel Contact view find configuration ECOM Published All Licensee

The application framework in previous releases supported many types of plugin, including GUI applications, that were implemented as polymorphic DLLs. Under platform security, this simple use of polymorphic DLLs is avoided, as:

• The polymorphic DLL would need security capabilities as least as great as its loading process (which would be high). This could unnecessarily restrict who could use the framework.

  A solution is to change the DLL to be an EXE, which can run as a process with just those security capabilities it needs.

• Frameworks used to search a directory (or directories) to find polymorphic DLLs. With platform security, all binaries are located in \sys\bin\, and only processes with the AllFiles capability are able to read from that location. This means that most processes are not able to scan for binaries themselves.

  The solution is to change the DLL into an ECom plugin. ECom provides a means for plugins to register that they exist and that they support a particular interface, and a means for processes to discover and load appropriate plugins.

Details of changes for particular frameworks are given below:

• common\generic\app-framework\Documentation\How to port guide - apps to exes.doc

  Describes how to convert applications from .dlls into .exes.

• common\generic\app-framework\Documentation\How to port guide - data caged applications.doc

  Describes how to change applications to conform to data caging requirements, including how to change AIF files into registration files.

Details of API breaks are:

CEikApplication::OpenAppInfoFileLC; CApaApplication::OpenAppInfoFileL; CApaApplication::OpenAppInfoFileLC; CApaAppInfoFileReader Users should migrate to RApaLsSession's inquiry APIs. CApaCommandLine::New; CApaCommandLine::NewL; CApaCommandLine::NewLC; CApaCommandLine::SetFullCommandLine; CApaCommandLine::SetFullCommandLineL; CApaCommandLine::FullCommandLine The equivalent to the old New[L[C]] functions taking a descriptor parameter (which would previously have been passed the descriptor returned by RProcess::CommandLine or User::CommandLine) is CApaCommandLine::GetCommandLineFromProcessEnvironment(). Similarly, the new equivalent of FullCommandLine (and passing this descriptor into the second parameter of RProcess::Create) is to call CApaCommandLine::SetProcessEnvironmentL(). CApaCommandLine::SetLibraryNameL; CApaCommandLine::LibraryName Users should instead use the equivalent CApaCommandLine::ExecutableName functions. CApaScanningControlFinder Users of this class should migrate to RApaLsSession::GetFilteredApps(TApaAppCapability::EControlPanelItem, TApaAppCapability::EControlPanelItem,...). CApaScanningAppFinder Users of this class should migrate to RApaLsSession::GetAllApps or GetFilteredApps or GetEmbeddableApps. CApaSystemControlList::NewL The three-parameter overload is obsolete. Use the one-parameter version. CApaProcess::NewL; CApaProcess::AddNewDocumentL; CApaProcess::TempFilePath; CApaProcess::CApaProcess Users of the obsolete overloads of NewL, AddNewDocumentL and the obsolete constructor, should migrate to the corresponding non-obsolete overloads. Users of TempFilePath should migrate to RFs::PrivatePath(), etc. CCoeAppUiBase; CCoeAppUiSimple Users of these classes should migrate to CCoeAppUi. CCoeEnv::FileNamesOfAvailableFepsL; CCoeEnv::InstallFepL; CCoeEnv::NameOfInstalledFepL; CCoeEnv::ExecuteFepSettingsDialogL Users of the file name overloads of InstallFepL and ExecuteFepSettingsDialogL should migrate to the uid-based overloads. Users of FileNamesOfAvailableFepsL and NameOfInstalledFepL should migrate to CCoeEnv::AvailableFepsL and CCoeEnv::FepUid respectively. EikDll::StartDocL; EikDll::StartExeL; EikDll::StartAppL; EikDll::RunAppInsideThread Users of StartExeL should migrate to using RProcess directly. Users of StartAppL should migrate to RApaLsSession::StartApp(). Users of StartDocL should migrate to RApaLsSession::StartDocument(). Users of RunAppInsideThread should migrate to EikStart::RunApplication(). EikStart::RunApplication The overload with the command-line buffer parameter is obsolete (this overload was only ever to be called from the WinsMain of an exedll in WINS/EKA1.) CEikonEnv::ConstructAppFromCommandLineL The one-parameter overload is obsolete. TApaApplicationFactory is typically created by passing the address of the function that an app used to export when it was a DLL. CApaAppInfoFileWriter; CApaProcess::AppFinder; CApaScanningFileRecognizer::SetRecognizersFromListL; CApaScanningFileRecognizer::SetRecognizerL; CApaScanningDataRecognizer::SetRecognizersFromListL; CApaScanningDataRecognizer::SetRecognizersFromList; CApaScanningDataRecognizer::SetRecognizerL; AppInfoFileUtils; CEikonEnv::StartAppL; KAppFileExtension; KAppInfoFileExtension; KSystemControlFileExtension; KApaCaptionFileSuffix; KApparcExtraLengthOfCaptionFileName; KAppDllSearchPath; KAppDllSearchAnyFile; KAppDllSearchString; KUidAppInfoFile; KUidAppInfoFile8; KUidAppInfoFile16; KUidAppInfoFileVersion2; TAifVersion; EAifVersionOriginal; EAifVersionAddsDataType; EAifVersionAddsViewData; EAifVersionAddsFileOwnershipInfo These functions have been withdrawn without replacement. For further migration information, see "How to" porting guides . CApaCommandLine::SetReserveLengthL This function was previously there to enable other leaving functions to be able to be called without leaving. This can no longer be guaranteed.

A new base class CConverterBase2, derived from CConverterBase, is provided for implementing converters as ECom plugins.

Users of the CCnaConvInfoFileReader class should migrate to using CCnaConvInfoFileReader2.

CCnaConvInfoFileWriter and CCnaConverter are withdrawn without replacement.

common\generic\app-framework\Documentation\How to port guide - control panel plug-ins.doc describes how to convert control panel plugins into applications.

In the previous scheme, CONE searches for available FEPs and loads or unloads on the basis of their file names. In the secure platform, each FEP is an ECom plugin, and CONE queries ECom to get the system's available FEPs.

ECom resource file

Each FEP should be having a ECom resource file. This file contains the information about the interface UID, implementation UID, etc. Each FEP should be using the ECom interface ID {0x1020233F}. If the FEP does not use this ID in the ECom resource file, that particular FEP will not be loaded by CONE.

#include <RegistryInfo.rh>

RESOURCE REGISTRY_INFO theInfo
  {
  dll_uid = 0x102024D0; // UID3 of the DLL
  interfaces =
    {
    INTERFACE_INFO
      {
      interface_uid = 0x1020233F; // Same for every FEP
      implementations =
        {
        IMPLEMENTATION_INFO
          {
          implementation_uid = 0x102024D0;
          version_no = 1;
          display_name = "FEPNAME";
          default_data = "";
          opaque_data = "";
          }
        };
      }
    };
  }

Project file

The .mmp file will need modifying as follows:

• TargetType: should be PLUGIN, which specifies that the project is an ECom plugin

• UID: the first UID should be 0x10009D8D, which is common for all the ECom plugins. The second one is the DLL UID.

• Resource: the project should use a start resource block to build the ECom resource file. The target keyword should be used to specify that the built resource file has the same name (without extension) as the DLL.

Example:

target tfep1plugin.dll
targettype plugin
uid 0x10009D8D 0x102024D0

sourcepath ..\source
source TFEP1.CPP TFEP1PlugIn.cpp
systeminclude ..\include \epoc32\include \epoc32\include\techview \epoc32\include\ecom

library EUSER.LIB EFSRV.LIB ESTOR.LIB GDI.LIB ETEXT.LIB FBSCLI.LIB BITGDI.LIB WS32.LIB FORM.LIB CONE.LIB FEPBASE.LIB BAFL.LIB EIKDLG.LIB EIKCOCTL.LIB EIKCTL.LIB
library ECOM.LIB

lang 01 10

start resource 102024d0.rss
#ifdef SYMBIAN_SECURE_ECOM
target tfep1plugin.rsc
#endif
END

ECom interface

Previously, FEPs had two exported functions, NewFepL and SynchronouslyExecuteSettingsDialogL. These are moved to a C class CCoeFepPlugIn defined in fepplugin.h:

class CCoeFepPlugIn : public CBase
  {
public:
  inline static CCoeFepPlugIn* NewL(TUid aFepUid);
  virtual ~CCoeFepPlugIn();
public:
  virtual CCoeFep* NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters) = 0;
  virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0;

The function SynchronouslyExecuteSettingsDialogL has been redefined and it no longer takes the argument const TDesC& aFullFileNameOfDll. This function should now be providing implementation for locating, loading and unloading the resource files needed for executing the settings dialog.

Each FEP should now:

• define a derived class that implements the CCoeFepPlugIn functions

• provide the standard ECom factory code to create an instance of the derived class

For example:

// Standard ECom factory code
const TInt KTstFepPlugInImplementationValue = 0x102024D0;
const TImplementationProxy ImplementationTable[] =
  {
  IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL )
  };

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)
  {
  aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy);
  return ImplementationTable;
  }

// Implement class derived from CCoeFepPlugIn
CTstFepPlugIn* CTstFepPlugIn::NewL()
  { // static
  return new(ELeave) CTstFepPlugIn;
  }

CCoeFep* CTstFepPlugIn::NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters)
  {
  CTstFep* const fep=new(ELeave) CTstFep(aConeEnvironment);
  CleanupStack::PushL(fep);
  fep->ConstructL(aFepParameters);
  CleanupStack::Pop(fep);
  return fep;
  }

void CTstFepPlugIn::SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment)
  {
  _LIT(KLitResourceFileName,"TFEP1PlugIn.rsc");
  
  TFileName* resourceFileName=new(ELeave) TFileName;
  CleanupStack::PushL(resourceFileName);
  Dll::FileName(*resourceFileName); // Get the drive letter

  TParse* parse=new(ELeave) TParse;
  CleanupStack::PushL(parse);
  User::LeaveIfError(parse->SetNoWild(KLitResourceFileName, &KTestFepResFilePath, resourceFileName));
  resourceFileName->Copy(parse->FullName());
  CleanupStack::PopAndDestroy(parse);
  
  BaflUtils::NearestLanguageFile(aConeEnvironment.FsSession(), *resourceFileName);
  TTstResourceFileId resourceFileId(aConeEnvironment, aConeEnvironment.AddResourceFileL(*resourceFileName)); // object must not be an anonymous temporary passed into CleanupStack::PushL, as its lifetime would be too short
  CleanupStack::PopAndDestroy(resourceFileName);
  CleanupStack::PushL(resourceFileId);
  (new(ELeave) CTstSettingsDialog)->ExecuteLD(R_TFP_SETTINGS_DIALOG);
  CleanupStack::PopAndDestroy(&resourceFileId);
  }

The page How To Port Guide: Notifiers describes how to convert notifiers into ECom plugins.

• The page How to Port Guide: Data Recognizers describes how to convert data recognizers in to ECom plugins.

• The page How to Port Guide: File Recognizers describes how to convert file recognizers in to ECom plugins.

The changes are summarised in section 5 Security, in common\generic\app-services\documentation\App-Services_Architectural_Description.doc.

For information on changes to help files as a result of platform security, see common\generic\app-services\documentation\How to make help files upgradeable on the secure platform.doc

!!!! make the above an xref !!!!

The following functions expose the file system and are not supported:

• RWorldServer::DataFileSaveAs()

• RWorldServer::DataFileOpen()

• RWorldServer::DataFileLocation()

The location of the read-only world server data file, WLD_DATA.DBZ has changed from either Z:\System\Data\, if in ROM, or C:\System\Localization\ if in RAM, to Z:\Resource\worldserver\ or C:\Resource\worldserver\.

The location of the writable file containing user changes to the world server data file, WLD_DATA.DBW has changed from C:\System\Data\ to a directory private to the World Server.

The writable file containing the user's home city, wldsvr.dat, has also been moved to the World Server's private directory.

The document at cedar\generic\base\documentation\Base_Platform_Security_APIs.zip is a zip file that contains a reference of new APIs in Symbian OS that are directly involved with platform security.

The mechanisms available for configuring platform security properties within Symbian OS are described in cedar\generic\base\documentation\Base_How_To_Configure_Platform_Security_Settings.doc.

Symbian OS changes due to platform security - User library (E32) provides details of the API and functional changes as a result of platform security for the User Library.

The Client/Server framework has a revised API that provides a more securable interface. There is a cook-book type guide to migration from the Version 1 to the Version 2 API setdocument at cedar\generic\base\documentation\Base_How_To_Migrate_To_Client-Server_V2_APIs.doc.

In addition, a policy server framework is provided built on top of this Version 2 API. This is designed to make migration to a secure server framework as easy as possible, and is the recommended framework to use for servers from v9. The framework is described in detail in the API reference for CPolicyServer.

Symbian OS changes due to platform security - File Server (F32) provides details of the API and functional changes to Symbian OS as a result of platform security for the File Server.

Platform security migration for device drivers is described in the "Platform security issues" section of the Device Driver Kit documentation.

The publish and subscribe values defined by the Bluetooth stack were changed to secure the usage of the publish and subscribe framework. For details, see common\generic\bluetooth\latest\documentation\Bluetooth_Release_Note.doc.

Note new functionality in this subsystem is configured using the SYMBIAN_NETWORKING_PLATSEC macro.

The communications database, commonly called CommDb, provides system-wide storage for communications-related settings. It holds information about Internet Access Providers (IAPs), Internet Service Providers (ISPs), GPRS, modems, locations, charge-cards, proxies, and WAP settings. Information is held in tables. The tables group together related information items.

Reading data

Your applications need the ReadDeviceData capability to read from the Chargecard table.

You do not need any capabilities to read data from other tables.

Writing data

Your applications need the WriteDeviceData capability to write to the tables.

You need both the WriteDeviceData and NetworkControl capabilities to modify the CommDb schema and to create new CommDb databases.

Database file

The database files (previously \system\data\cdbv3.dat; \system\data\defaultcdbv3.dat) are data caged, and moved to \private\100012A5\dbs_<AccessPolicy-UID>_<filename>.<ext>. Test code that accesses the files will need AllFiles capability.

System Agent properties

The following properties are now published through Publish and Subscribe rather than through the System Agent: KUidCommDbSMSReceiveModeChange; KUidCommDbGPRSAttachModeChange; KUidCommDbModemTsyNameChange; KUidCommDbModemDataAndFaxChange; KUidCommDbModemPhoneServicesAndSMSChange; KUidCommDbGPRSDefaultParamsChange; KUidCommDbModemRecordChange; KUidCommDbProxiesRecordChange.

In the CCommsDatabaseBase class, the protected members iSystemAgentNotifier and iSystemAgent are removed, and iNotifications is changed. This is a BC break. Source code should be changed to not use the data members iSystemAgentNotifier and iSystemAgent and instead use the Publish and Subscribe mechanism.

Migration is described in the Developer Library topic Symbian OS guide\System libraries\Using System Agent\Migrating to Publish And Subscribe.

Three methods of RMBufChain have become virtual. The change is configured using the SYMBIAN_MBUFMGR_API_V2 macro. This change is not related to platform security, but is to avoid a possible memory leak.

In classes deriving from RMBufChain or RMBufPacketBase, make the following methods virtual: Free(), TrimStart() and TrimEnd().

• RNif, deprecated in v7.0s, is removed. Clients should use RConnection.

• The CAgentBase, CNifAgentBase, MNifIfNotify classes are changed. To check capabilities of processes making calls to the DBMS (and potentially other data sources) through ESOCK, the capability set of the calling process must be passed to the actual data source. New functions are defined to allow the passing of additional parameters to data access calls.

Transferring sockets

There are new rules regarding the transfer of sockets. RSocket::Transfer() allows the transfer of a socket from one ESOCK session to another.

• Before platform security:

  Any application could start an ESOCK session and then take control a socket that was opened by another ESOCK session. The two sessions could be in different processes. A session could transfer a socket if it knew the socket's unique global name, obtained by RSocket::Name(). If the transfer was successful then the session that originally opened the socket cannot use the socket any more.

• After platform security:

  There are two mechanisms to secure the transfer of sockets:

  1. Most protocols will only let a socket be transferred to a process that has the necessary capabilities to use the socket.

     For instance, a process needs the NetworkServices capability to open a TCP or UDP socket. Hence a process also needs the NetworkServices capability to transfer a TCP or UDP socket. Similarly, a process needs the NetworkControl capability to open an IP or ICMP socket. Hence a process also needs the NetworkControl capability to transfer a IP or ICMP socket.

  2. The donor session (the ESOCK session that owns the socket before it is transferred) is able to mark a socket as being transferable. Unless this is done, another ESOCK session (the receiver) cannot transfer the socket.

     • The donor process marks a socket by calling RSocket::SetOpt(), passing it an option of KSOEnableTransfer and an option level of KSOLSocket.

     • The donor process unmarks a socket by calling RSocket::SetOpt(), passing it an option of KSOEnableTransfer and an option level of KSOLSocket. This prevents the socket being transferred.

     In addition to simply marking a socket, the donor session can specify the capabilities needed by the receiver in order to transfer the socket. To do this, pass a TSecurityPolicy to RSocket::SetOpt() when marking the socket. Then, when a receiver tries to transfer a socket, RSocket checks the capabilities of the receiver's process. If the receiver's process does not have all the capabilities required by the TSecurityPolicy then the socket cannot be transferred, and the call to RSocket::Transfer() fails with KErrPermissionDenied.

Cloning connections

There are new rules regarding the cloning of connections. They are similar to the new rules for transferring sockets, described above.

RConnection::Open() creates a new RConnection instance. It can create a completely new connection, or it can create another instance of an existing RConnection connection. This second technique is called "cloning a connection". After the operation has completed, the cloned RConnection instance can be used to manage the same underlying interface as that of the original RConnection instance.

• Before platform security:

  Any application could clone and then use connection that was opened by another process. A process could clone a connection if it knew the connection's unique global name, obtained by RConnection::Name().

• After platform security:

  The donor process (the process that opened the connection before it is cloned) is able to mark a connection as being one that can be cloned. Unless this is done, another process (the receiver) cannot clone the connection.

  • The donor process marks a connection by calling RConnection::Control(), passing it an option of KCoEnableCloneOpen and an option level of KCOLConnection.

  • The donor process unmarks a connection by calling RConnection::Control(), passing it an option of KCoDisableCloneOpen and an option level of KCOLConnection. This prevents the connection being cloned.

  In addition to simply marking a connection, the donor process can specify the capabilities needed by the receiver in order to clone the connection. To do this, pass a TSecurityPolicy to RConnection::Control() when marking the socket. Then, when a receiver tries to clone a connection, RConnection checks the capabilities of the receiver's process. If the receiver's process does not have all the capabilities required by the TSecurityPolicy then the connection cannot be cloned, and the call to RConnection::Open() fails.

Socket clients miscellaneous

In addition to the transfer of sockets and cloning of connections, the following socket client functions have changed:

• All users of the old RQosChannel API must migrate to the new RSubConnection API exported by ESOCK.

• When using the TCP/IP local loopback interface, a process must ensure that it performs an RSocket::Bind() operation on the socket specifying the loopback address. This must be done before a connect or send operation.

• There is a BC break for RSocket, as two obsolete private data members have been removed. Rebuild any dependent code. Note that classes that embed a RSocket will become smaller and so code manipulating them will in turn need to be rebuilt.

Socket server protocol (PRT) modules

• Socket server protocol (PRT) modules must change to implement a new virtual function to perform Platform Security checking. The method is SecurityCheck() in the classes CServProviderBase and CResolverProvdBase.

  Note that the change does not cause an immediate SC breakage, as the method has an initial default implementation that does not cause any existing un-modified PRTs to fail. However, in the final v9 release, once all PRTs have been modified to be secure, the default implementation will be altered to fail client requests to PRTs that do not implement SecurityCheck().

• The functions CServProviderBase::SetNotify() and CServProviderBase::SetSockType() are now virtual, to enable a derived class that enables communication with the new sub-connection control side introduced by the QoS API functionality. This causes a BC break only.

Initialisation files

Socket protocol initialisation files, including .esk and .ini files are moved from \system\data\ to the private socket server directory \private\101F7989\ESock\.

Note these change are configured using the SYMBIAN_C32ROOT_API_V2 macro.

• The TRSBindingInfoContainer class used by the RRootServ API gains two additional members detailing the number of queue slots provided in the binding. The fields added are iForwardQLength and iReverseQLength. Users of RRootServ::Bind() need to initialise these fields to appropriate values (1 is the minimum, and is appropriate for most uses). No default constructor is provided because all TRSBindingInfoContainer members must be initialised sensibly: the only permitted client for this API on the secure platform is the RootServer Configurator process.

• The copy constructors created by default by the compiler for RootServer parameter containers TRSStartModuleParams, TRSUnBindingInfo, TRSModuleInfo, and TRSSubModuleAddress are removed, since they do not function in the expected way of assignment. For a compilation error from this change, consider whether you should in fact be using the parameter class that these classes package. If copy construction from these package classes is really still required, then you can do so by using the fully parameterised constructors and passing in the individual attributes of the existing package class.

• The Rootserver publishes information using Publish and Subscribe values. This is secured by changing the value's category to KSystemCategory. Clients that listened to the following old values need to migrate to the new ones as listed. Clients that set these values should not do so, as this was not supported behaviour:

  • Old Category: KUidCommsProcess, old key: KC32RootModuleDeathKey. New Category: KUidSystemCategory, new key: KUidC32RootModuleDeathKey

  • Old Category: KUidC32StartProcess, old key: KC32StartPropertyKey. New Category: KUidSystemCategory, new key: KUidC32StartPropertyKey

  • Old Category: KUidC32StartProcess, old key: KC32StartCMISuppressionKey. New Category: KUidSystemCategory, new key: KUidC32StartCMISuppressionKey

v9.0 introduced a new approach to back-up and restore of phone data. This is described in common\generic\connectivity\documentation\.

Developers of all components that own data files will need to make changes to enable these files to be backed up. The steps are described in How-To Write Backup-aware Software.

Capabilities and data caging for the connectivity components are described in PC_Connectivity_Architectural_Description.doc.

The OS component, the secure backup engine, that manages backup/restore operations has an API that can be used by phone developers. This is described in PC_Connectivity_How-To_Use_The_Secure_Backup_Engine.doc.

The following list is a summary of the changes made to the J2ME subsystem to implement Platform Security:

• 'Caging' of all binaries and sensitive system and user data in private areas so that they are only accessible to their owning process. Shared RMS databases are located in the DBMS data cage.

• The Java MIDlet installer now installs JAD and JAR files to the Java VM's private area.

• Creation of temporary files is now done by the SystemAMS, rather than by the VM or plugins. This facilitates guaranteed temporary file cleanup after VM termination and MIDletSuite uninstall.

• To comply with system-wide platform security requirements, all notifiers and recognisers have become ECom style plugins and control panel plugins have become applications.

• Secure backup and restore of MIDlet suites.

• Tamper proofing for MIDlets installed onto removable media. Before launching a MIDlet, a hash is generated by the VM and compared with a value stored at installation time in the SystemAMS. If they do not match, the MIDlet is assumed to have been tampered with and will fail to launch.

Platform security changes impact several different types of user of the messaging APIs:

• Messaging clients: need to migrate for changes in the messaging framework and MTM APIs for handling attachments, and for service settings

• SendAs clients: the SendAs API has been completely redesigned, requiring changes to applications or UI platforms that use it.

• MTM providers: need to migrate for changes to the framework classes, relating to attachments, SendAs support, and security capability support.

• Watchers need to migrate to become ECOM plugins.

• BIO message parser plugins need to migrate for changes relating to how they are located and loaded

Messaging changes are configured using the __MESSAGING_API_V2__ macro, except for watcher changes which are configured using the __WATCHER_API_V2__ macro.

Details of migration steps to take are at common\generic\messaging\documentation\Messaging_Platsec_migration.doc. The Architectural Description and Functional Specification documents in the same folder were updated for v9.0.

!!!!! make the above an xref !!!!!

The changes for Platform Security are:

• All multimedia static data and resource files have been stored in the appropriate folder according to the data caging rules. For more detailed information see section 5 of common\generic\Multimedia\Documentation\designs\Use_Cases\Multimedia_Architectural_Description.doc

• A secure Reference DevSound has been implemented. It enforces the decisions of the audio policy server, ensuring untrusted apps don't stop higher priority ones from playing or recording sound as required. It allows hardware acceleration and similar low-level code modules to be protected from malicious code sequences, and ensures such hardware or software modules are not overloaded. For more information on the secure Reference DevSound, see common\generic\Multimedia\Documentation\designs\MMF_Design_AudioServer.doc

• Client APIs that read data have additional functions that accept the file to read specified as an open RFile. These are required as the v9.0 (and later) messaging APIs provide access to data-caged attachment files through open file handles rather than through path specifications.

• MMF code has been altered to allow it to use the new V2 IPC Secure API calls (see \cedar\generic\base\documentation\Base_How_To_Migrate_To_Client-Server_V2_APIs.doc). For information on the MMF Code changes see common\generic\Multimedia\Documentation\designs\MMF_Design_Secure_API.doc

For information on capabilities needed for Multimedia see section 5 of common\generic\Multimedia\Documentation\designs\Use_Cases\Multimedia_Architectural_Description.doc

DND initialisation files are moved from \system\data\ to the private directory \private\10000882\.

The generic agent, RGenericAgent, deprecated in v7.0s, is removed. Clients should use RConnection.

CSecureSocket is no longer derived from MSecureSocket, and its virtual functions are now non-virtual. This is to future proof the API for future changes, and is not related to platform security.

Capabilities are required to open and use sockets. The capabilities depend upon the protocol: for instance, your applications require one range of capabilities to use a Bluetooth socket and another range to use a TCP/IP socket.

The following sections show the capabilities needed for the various protocols. Unless otherwise stated, no capabilities are needed for functions and options that aren't listed:

• TCPIP

• SMS on GSM/WCDMA networks

• SMS on CDMA networks

• WAP over SMS on CDMA networks

• Bluetooth

• Infrared

Two topics that apply to all protocols, described in Comms infrastructure:

• Transferring sockets

• Cloning connections

The sockets implementation is described in Using Sockets Server (ESOCK).

These are the capabilities needed for the tcpip6.prt protocol module. See Using TCP/IP (INSOCK) for more information about TCP/IP on Symbian OS.

Method Capabilities RSocket::Open() TCP and UDP require NetworkServices. IP and ICMP require NetworkControl. RSocket::SetOpt() See the options below. RSocket::Ioctl() Depends upon the I/O control operation. RSocket::Transfer() TCP and UDP require NetworkServices. IP and ICMP require NetworkControl. RHostResolver::Open() NetworkServices RHostResolver::SetHostName() NetworkControl RConnection::Open() Different for normal opening and cloning; see Cloning connections below. RConnection::Start() NetworkServices RConnection::Stop() NetworkControl RConnection::GetIntSetting() If reading from CommDb's Chargecard table then you need ReadDeviceData. Otherwise no capabilities are needed. RConnection::GetBoolSetting() As for RConnection::GetIntSetting() RConnection::GetDesSetting() As for RConnection::GetIntSetting() RConnection::GetLongDesSetting() As for RConnection::GetIntSetting() RConnection::Ioctl() Depends upon the I/O control operation. RConnection::Control() Depends upon control operation. RConnection::GetOpt() Depends upon option. RConnection::SetOpt() Depends upon option. RConnection::Attach() NetworkServices

Calls to RSocket::SetOpt()

The KSolInetIfCtrl option level

These capabilities are needed to set options in the KSolInetIfCtrl option level. Set options by calling RSocket::SetOpt().

No capabilities are needed when reading KSolInetIfCtrl options with RSocket::GetOpt().

Option Capabilities KSoInetEnumInterfaces none KSoInetNextInterface none KSoInetConfigInterface NetworkControl KSoInetDeleteInterface NetworkControl KSoInetChangeInterface NetworkControl KSoInetResetInterface NetworkControl KSoInetStartInterface NetworkControl KSoIpv4LinkLocal NetworkControl

The KSolInetIfQuery option level

These capabilities are needed to set options in the KSolInetIfQuery option level. Set options by calling RSocket::SetOpt().

No capabilities are needed when reading KSolInetIfQuery options with RSocket::GetOpt().

Option Capabilities KSoInetIfQueryByDstAddr NetworkControl KSoInetIfQueryBySrcAddr NetworkControl KSoInetIfQueryByIndex NetworkControl KSoInetIfQueryByName NetworkControl KSoInetInterfaceInfo NetworkControl KSoInetAddressInfo NetworkControl KSoInetRouteInfo NetworkControl

The KSolInetRtCtrl option level

These capabilities are needed to set options in the KSolInetIfQuery option level. Set options by calling RSocket::SetOpt().

No capabilities are needed when reading KSolInetRtCtrl options with RSocket::GetOpt().

Option Capabilities KSoInetEnumRoutes none KSoInetNextRoute none KSoInetAddRoute NetworkControl KSoInetDeleteRoute NetworkControl KSoInetChangeRoute NetworkControl

Other option levels

No capabilities are needed to get or set options in other options levels. These include KSOLSocket, KSolInetTcp, KSolInetIp and KSolInetUdp.

These are the capabilities needed for the smsprot.prt protocol module:

Method Capabilities CSmsProvider::SetLocalName() NetworkServices, WriteUserData and ReadUserData CSmsProvider::Write() WriteUserData CWapSmsProvider::SetLocalName() NetworkServices, WriteUserData and ReadUserData CWapSmsProvider::SetOption() ReadUserData and WriteUserData CWapSmsProvider::Write() NetworkServices and WriteUserData

Calls to RSocket::SetOpt()

These capabilities are needed to make calls to RSocket::SetOpt() when using a SMS socket on GSM/WCDMA networks. All these options are in the KLevelIrlap option level, and they all need the LocalServices and NetworkControl capabilities:

• KUserBaudOpt

• KHostMaxDataSizeOpt

• KHostMaxTATimeOpt

• KLocalBusyDetectedOpt

• KDiscoveryResponseDisableOpt

• KFirstHintByteOpt

• KSecondHintByteOpt

• KTinyTPLocalSegSizeOpt

• KTinyTPDiasbledSegmentation (note incorrect spelling)

These are the capabilities for the cdmasms.prt protocol module. See CDMA SMS for more information.

Calls to RSocket::Ioctl()

These capabilities are needed to make calls to RSocket::Ioctl() when using a CDMA SMS socket; see SMS Stack User Guide for CDMA Networks.

Option Capabilities KIoctlDeleteSmsMessage WriteUserData KIoctlEnumerateSmsMessages ReadUserData KIoctlReadMessageSucceeded ReadUserData KIoctlReadMessageFailed ReadUserData KIoctlSendSmsMessage WriteUserData & NetworkServices KIoctlWriteSmsMessage WriteUserData KIoctlGetMsgId NetworkServices KIoctlGetLastSendError NetworkServices

Calls to RSocket::Bind()

For ECdmaSmsAddrLocalOperation address family, you need the ReadUserData and WriteUserData capabilties.

For all other address types, you need ReadUserData, WriteUserData and NetworkServices.

RSmsSocketWriteStream

Calls to RSmsSocketWriteStream()'s << operator (stream operation to the socket) require WriteUserData.

These are the capabilities are needed for the cdmawapprot.prt protocol module. See CDMA WDP SMS for more information about the WAP over SMS implementation.

Method Capabilities RSocket::SetOpt() ReadUserData and WriteUserData RSocket::Ioctl() ReadUserData is needed for KSOGetLength. RSocket::Bind() ReadUserData, WriteUserData and NetworkServices RSocket::SendTo() (stream operation to the socket) WriteUserData and NetworkServices

These are the capabilities needed for the bt.prt protocol module. See Bluetooth for more information about Symbian's Bluetooth implementation.

Method Capabilities RSocket::Open() LocalServices. RSocket::SetOpt() LocalServices and NetworkControl are needed to set the EBBBeginRaw option in the KSolBtLMProxyoption level. RSocket::Ioctl() LocalServices and NetworkControl are needed for KHCIWaitForVendorSpecificDebugEventIoctl and KHCIWriteVendorSpecificFrameIoctl. RSocket::Transfer() LocalServices RSocket::Shutdown() LocalServices and NetworkControl RHostResolver::Open() LocalServices

These are the capabilities needed for the irda.prt protocol module. See Infrared for more information about Symbian's infrared implementation.

Method Capabilities RSocket::Open() LocalServices RSocket::SetOpt() See the options below. RSocket::Ioctl() LocalService and NetworkControl are needed for the KExclusiveModeIoctl, KIrlapResetRequestIoctl and KIrlapDisconnectRequestIoctl. RSocket::Transfer() LocalServices RHostResolver::Open() LocalServices RNetDatabase::Open() LocalServices

Calls to RSocket::Ioctl()

These capabilities are needed to set options with RSocket::Ioctl() when using an infrared socket:

Option Capabilities KIoctlDeleteSmsMessage WriteUserData KIoctlEnumerateSmsMessages ReadUserData KIoctlReadMessageSucceeded ReadUserData KIoctlReadMessageFailed ReadUserData KIoctlSendSmsMessage WriteUserData & NetworkServices KIoctlWriteSmsMessage WriteUserData KIoctlGetMsgId NetworkServices KIoctlGetLastSendError NetworkServices

The Security subsystem components that have been updated, replaced, or redesigned for Platform Security include the Content Access Framework (CAF), Certificate Management, Software Installation, and SIS/package file formats.

The following subsections outline the new published functionality.

1. Addition of a new pure virtual function in CAgentFactory.

   Licensees need to implement virtual CAgentConsumer* CreateConsumerL(RFile& aFile) or undefine SYMBIAN_SECURITY_CAF_RFILE_HANDLE in the variant.hrh

2. Changes to CAF to support reading from file handles instead of supplying only a file name.

   • ContentAccess::CContent::NewLC(RFile& aFile) - constructs a new CContent object with an open file handle

   • ContentAccess::CContent::NewL(RFile& aFile) - constructs a new CContent object with an open file handle

   • ContentAccess::CAgentFactory::CreateConsumerL(RFile& aFile) = 0 - factory fun