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

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:

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:

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:

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:

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

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.

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:

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.

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

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

Calls to RSocket::Ioctl()

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

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 function that creates a consumer object

   • ContentAccess::CAgentManager::IsRecognizedL(RFile& aFile) = 0 - identifies whether or not the given file handle is to be handled by the agent.

1. Additional functions have been added to the certificate store interfaces to allow clients to get and set capabilities associated with certificates and a "mandatory for software install" setting. These additional functions are necessary to support software install for platform security.

   Implementers of these interfaces will have to provide implementations of the new functions. Callers of the MCTWritableCertStore interface will need to recompile their code.

   • virtual void MCertStore::Capabilities(const CCTCertInfo& aCertInfo, TUint& aCapbilitiesOut, RequestStatus& aStatus) = 0

   • virtual void MCertStore::CancelCapabilities() = 0

   • virtual void MCertStore::IsMandatory(const CCTCertInfo& aCertInfo, TBool& aMandatoryOut, RequestStatus& aStatus) = 0

   • virtual void MCertStore::CancelIsMandatory() = 0

2. The implementation of class TCertificateAppInfo has been moved from certstore.dll to ctframework.dll [Plaform: cedar only, v8.1b and onwards]. This is necessary to support platform security. The TCB software install server makes use of the file tokens client, fstokencli, and this uses the TCertificateAppInfo class. This class is currently implemented in certstore.dll, but this library depends on ecom.dll, which is not trusted for use by TCB. Therefore, it is necessary to move the implementation of this class to a DLL that is trusted.

   The def file for certstore.dll has been refrozen. This is an SC break for clients of the moved EXPORTs - they should link against ctframework. This is a BC break for all clients of certstore.dll - they should recompile.

   • TCertificateAppInfo::TCertificateAppInfo(const TUid& aUid, const TName& aName)

   • TCertificateAppInfo& TCertificateAppInfo::operator = (const TCertificateAppInfo& aClient)

   • TCertificateAppInfo::TCertificateAppInfo()

   • const TUid& TCertificateAppInfo::Id() const

   • const TName& TCertificateAppInfo::Name() const

   • void TCertificateAppInfo::ExternalizeL(RWriteStream& aStream) const

   • void TCertificateAppInfo::InternalizeL(RReadStream& aStream)

3. The following functions have been removed from CUnifiedKeyStore. These are present in v8.0 and v7.0s and marked deprecated. Callers of the removed functions should change to use their non-deprecated overloads.

   • void CUnifiedKeyStore::ExportKey(TCTTokenObjectHandle aHandle, TDes8& aKey, TRequestStatus& aStatus)

   • void CUnifiedKeyStore::ExportEncryptedKey(TCTTokenObjectHandle aHandle, HBufC8*& aKey, TRequestStatus& aStatus)

   • void CUnifiedKeyStore::ExportEncryptedKey(TCTTokenObjectHandle aHandle), TDes8& aKey, TRequestStatus& aStatus)

   • void CUnifiedKeyStore::ImportKey(TInt aKeyStoreIndex, const TDesC8& aKeyData, TBool aIsEncrypted, TKeyUsagePKCS15 aUsage, TUint aSize, const TDesC& aLabel, CCTKeyInfo::EKeyAlgorithm aAlgorithm, TInt aAccessType, TTime aStartDate, TTime aEndDate, CCTKeyInfo*& aKeyInfoOut, TRequestStatus& aStatus)

4. Removal of deprecated functions in the certificate store interfaces. These have been present since v7.0 and were deprecated in v8.0. Redundant EXPORTs and virtuals in CUnifiedCertStore have been changed.

   The following deprecated functions have been removed. This is an SC break for clients that implement MCTWritableCertStore - they should update their code to use the other version of the function. This is an SC break for callers of the deprecated version of MCTWritableCertStore::SetApplicability() and CUnifiedCertStore::SetApplicability() - they should update to use the non-deprecated overload. This is a BC break for clients of certstore.dll - they should recompile.

   • virtual void MCTWritableCertStore::SetApplicability(const CCTCertInfo& aCertInfo, RArray* aApplications, TRequestStatus &aStatus) = 0

   • virtual void CUnifiedCertStore::SetApplicability(const CCTCertInfo& aCertInfo, RArray* aApplications, TRequestStatus& aStatus)

   The following virtual functions in CUnifiedCertStore will no longer be EXPORTed (this is uncessesary, as they are virtual). This is a BC break for clients of certstore.dll - they should recompile.

   • virtual void CUnifiedCertStore::List(RMPointerArray& aCertInfos, const CCertAttributeFilter& aFilter, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelList()

   • virtual void CUnifiedCertStore::GetCert(CCTCertInfo*& aCertInfo, const TCTTokenObjectHandle& aHandle, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelGetCert()

   • virtual void CUnifiedCertStore::Applications(const CCTCertInfo& aCertInfo, RArray& aApplications, TRequestStatus &aStatus)

   • virtual void CUnifiedCertStore::CancelApplications()

   • virtual void CUnifiedCertStore::IsApplicable(const CCTCertInfo& aCertInfo, TUid aApplication, TBool& aIsApplicable, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelIsApplicable()

   • virtual void CUnifiedCertStore::Trusted(const CCTCertInfo& aCertInfo, TBool& aTrusted, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelTrusted()

   • virtual void CUnifiedCertStore::Retrieve(const CCTCertInfo& aCertInfo, TDes8& aEncodedCert, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelRetrieve()

   The following EXPORTed functions in CUnifedCertStore will no longer be declared as virtual (this is uncessary, as they are EXPORTed). This is a BC break for clients of certstore.dll - they should recompile.

   • virtual void CUnifiedCertStore::Remove(const CCTCertInfo& aCertInfo, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelRemove()

   • virtual void CUnifiedCertStore::SetApplicability(const CCTCertInfo& aCertInfo, RArray* aApplications, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelSetApplicability()

   • virtual void CUnifiedCertStore::SetTrust(const CCTCertInfo& aCertInfo, TBool aTrusted, TRequestStatus& aStatus)

   • virtual void CUnifiedCertStore::CancelSetTrust()

5. The keystore APIs have been changed to allow the policy for key use and key management operations to be specified in terms of capability, secure id and vendor id.

   The first release of the key store restricted key use with a scheme of key owners and key users. This was the best approach at the time, given that platform security was not available. Now this has arrived there have been new requirements raised to police the keystore APIs in terms of capability, secure id and vendor id.

   The following API-items have been removed/replaced. This is an SC break for callers of the removed functions. They must update their code to call the new APIs.

   • inline TUid CKeyInfoBase::Owner()

   • const inline const RArray& CKeyInfoBase::Users()

   • const CKeyInfoBase::CKeyInfoBase(TKeyIdentifier aID, TKeyUsagePKCS15 aUsage, TUint aSize, HBufC* aLabel, TInt aHandle, TUid aOwner, const RArray& aUsers, EKeyAlgorithm aAlgorithm, TInt aAccessType, TBool aNative, TTime aStartDate, TTime aEndDate, HBufC8* aPKCS8AttributeSet)

   • static CCTKeyInfo* CCTKeyInfo::NewL(TKeyIdentifier aID, TKeyUsagePKCS15 aUsage, TUint aSize, MCTAuthenticationObject* aProtector, HBufC* aLabel, MCTToken& aToken, TInt aHandle, TUid aOwner, const RArray& aUsers, EKeyAlgorithm aAlgorithm, TInt aAccessType, TBool aNative, TTime aStartDate, TTime aEndDate, HBufC8* aPKCS8AttributeSet = NULL)

   • TCTKeyAttributeFilter::iOwner

   • const TUid KAnyUsableKey

   • const TUid KAnyKeyIncludingUnusable

   • virtual void MCTKeystoreManager::SetUsers(TCTTokenObjectHandle aHandle, const RArray aUsers, TRequestStatus& aStatus) = 0

   • virtual void MCTKeystoreManager::CancelSetUsers() = 0

   • void CUnifiedKeyStore::SetUsers(TCTTokenObjectHandle aHandle, const RArray aUsers, TRequestStatus& aStatus) = 0

   • void CUnifiedKeyStore::CancelSetUsers() = 0

6. Use of CPtrCArray class in x509 module has been replaced with RArray, removing the dependency on bafl. This is to support platform security - bafl is not trusted with the TCB capability, but x509 is used by TCB software install.

   Callers of the following functions should change their code to make use of the new return type, RArray.

   • CX509RFC822NameSubtree::Rep()

   • CX509DNSNameSubtree::Rep()

7. Other additional functions:

   • CX509CertPolicyInfo::NewL(RReadStream& aStream) - creates a new CX509CertPolicyInfo object from a stream

   • CX509CertPolicyInfo::NewLC(RReadStream& aStream) - creates a new CX509CertPolicyInfo object from a stream

   • CX509CertPolicyInfo::ExternalizeL(RWriteStream& aStream) - Externalises a CX509CertPolicyInfo object to a write stream

   • CX509CertPolicyInfo::InternalizeL(RReadStream& aStream) - Internalises a CX509CertPolicyInfo object to a read stream

   • CX509RFC822NameSubtree::Rep() - gets a reference to the array of pointer descriptors representing the subdomains of the RFC 822 email address.

The def files for ctframework and certstore have been refrozen. This is a BC break for clients of ctframework.dll and certstore.dll - they should recompile.

The implementation of class TCertificateAppInfo has been moved from certstore.dll to ctframework.dll [Plaform: cedar only, v8.1b and onwards] (see Certificate Management above).

1. Interface has been changed from internal to published to allow installation of Java MIDlets in v9.x. The following classes are published and MIDlet installation is now achieved through these interfaces.

   • CJavaInstaller

   • CJavaRemover

   • MJavaInstallerUI

   • MJavaRemoverUI

   • MJarDownloaderUI

   The security/appinst component has been deprecated.

2. Includes install and uninstall functionality.

   • Swi::Launcher::Install(MUiHandler& aUiHandler, > RFile& aFileHandle, const CInstallPrefs& aInstallPrefs) - starts software installation with package data provided by means of IPC

   • Swi::Launcher::Uninstall(MUiHandler& aUiHandler, > const CSisRegistryPackage& aPackage) - uninstalls a specific package

   • Swi::TSignatureValidationResult.EMandatorySignatureMissing - a Software Install signature validation result: a signature resolving to one of the mandatory certificates cannot be found

   • Swi::TErrorDialog.EUiMissingBasePackage - Software Install error dialog type for SISX files: a base package missing when installing an augmentation or a partial upgrade

   • MInstallerUiHandler::DisplayMissingDependencyL( const CAppInfo& aAppInfo, const TDesC& aDependencyName, TVersion aWantedVersionFrom, TVersion aWantedVersionTo, TVersion aInstalledVersion) = 0 - informs the user of a missing dependency needed to install the current package.

SIS and package files

SIS and package files have both changed, as described below:

8.X to 9.X SIS file changes

The SIS file format has significantly changed:

• It now supports multiple (nested) signings and additional file metadata such as platsec capabilities

• It is now based on a Type, Length and Value (TLV) structure, which allows future flexibility.

• Much of the data required to analyze an install is now at the start of the file rather than the end: this facilitates installing over the network without the whole file being present.

Package (.pkg) file enhancements

There are three new directives and some new package-type options. The new directives are specified with the .pkg characters '%', ':' and '=':

• % specifies localised vendor names (corresponding to language)

• : specifies a non-localised (global) vendor name. This is used, in combination with signing, to prevent the unauthorised upgrade of a package by someone other than the rightful vendor.

• = specifies logo files (corresponding to language)

For example:

; This is a comment
; Specify the languages - as previously supported
&EN,FR

; List of localised vendor names - one per language. At least one must be provided  (English [EN]). 
; List must correspond to list of languages specified elsewhere in the .pkg
%{"Vendor-EN", "Vendor-FR"}

; The non-localised, globally unique vendor name (mandatory)
:"Symbian Software Ltd"

; Optional Logofile - display logofile of given type mimetype; if targetname is supplied, 
; install file to that location
; <logofile>,<mimetype>[,<targetname>]
="file\mylogo.jpg","image/jpeg","\public\logos\mylogo.jpg"

Three new package types (as specified in the package header) exist. Two of these apply to read-only (RO) media, and one to standard SIS-based applications.

Pre-installed package types

Applications can be delivered in a pre-installed form on media cards. The application is delivered outside a SIS file, so the SIS file itself just needs to contain metadata describing the application. SWI uses this data to validate an application that it hasn't seen before. The OS loader will not load an application from removable media unless SWI has validated it.

Two package types are use to identify these packages: either

• PA - indicates a pre-installed application, or

• PP - indicates a pre-installed patch application

Developers therefore generate SIS information with these special types when creating packages designed for end-user deployment on read-only media.

These types should not be used when creating standard SIS archives for deployment over the web, from a PC, etc. Similarly, pre-installed SIS controller information should not be compressed.

Partial upgrade package type

Existing types SA, and SP continue to be supported, but are joined by a new package type: PU.

PU now exists for situations where a partial upgrade is intended. It incorporates default (SA) behaviour, but also indicates to the software installer that the developer is only supplying the new or changed files, and not the whole set. The type means that a large package does not have to be sent again to upgrade, perhaps, just a single file.

Without this type specified, software install assumes that the files that were specified in the original install package, but which are not specified in the new version of the package, are to be removed.

SIS controller files

A SIS controller file is a record file that is designed to exist in ROM. It provides information about the applications or components that are pre-installed on the device and is used, for example, in circumstances where new packages depend on certain OS functionality being present, and it is desirable for installation to fail if certain criteria (e.g. version dependencies) are not met.

A SIS controller file contains only metadata. Such files are usually exported into a controller directory as part of the OS build process. They are built by invoking MakeSIS with the -s option.

There are currently no constraints relating to which package-types are valid in a .pkg file when creating a ROM-based SIS Controller. The SA type is recommended as (a) ROM is not removable in the same way that pre-installed media is and (b) this is consistent with SIS controllers in previous releases.

Installing to private directories

Because of data caging, a package cannot generally install a file into another program's private directory area. To allow for cases where it is desirable to do this, however, a package can install files in or below directories named import in another program's private directory (i.e. \private\<SID>\import\).

Note that the following possible issues concerned with uninstallation:

• SWI will try to uninstall data from the import directory if the sending application is uninstalled. Sometimes the receiving application moves files from import to another directory, so SWI will not be able to find the file. In this case, SWI will just skip the removal.

• If the receiving application moves a file from \private\<SID>\import\ into \private\<SID>\, then the file gets removed when the receiving application is removed.

Example 1:

• App Y installs a file into \private\<X>\import\YTheme.dat

• When Y is uninstalled, there will be an attempt to uninstall YTheme.dat (if it exists)

Example 2:

• App Y installs a file into \private\<X>\import\YTheme.dat

• App X moves YTheme.dat to \private\<X>\

• When Y is uninstalled, \private\<X>\YTheme.dat is not found, so SWI skips it

• When X is uninstalled, YTheme.dat is removed because \private\<X>\ is removed

Note: if App X moves YTheme.dat to a public area of the file system, and App X is uninstalled. YTheme.dat is orphaned.

Applications access serial ports with the serial communications server, commonly called C32. This provides a standard interface for all applications. In turn, the serial communications server uses serial protocol modules (commonly called CSYs) to access serial ports. A CSY may control any number of serial ports. See Serial Comms Overview for more information about this system. See also common\generic\ser-comms\c32\documentation\C32_Design_Document.doc for implementation details.

As an example, a phone could use a CSY to access a USB connection to a PC, and another CSY to send and receive serial data from phone calls. Alternatively, a single CSY may provide multiple ports to read and write from both a PC and phone calls. An application calls RComm::Open() or RComm::OpenWhenAvailable() to choose a CSY and to open a port on that CSY.

Applications need capabilities to open ports. Each port requires different capabilities. When an application asks the serial communications server to open a serial port, the server asks the CSY for the port's required capabilities. The server compares these with the application's capabilities: an application must have all necessary capabilities to use the port. Otherwise the application is returned KErrAccessDenied.

The server calls the CSY's CSerial::PortPlatSecCapability() function to read the capabilities required by a port. The server passes the port as a parameter. This returns a TSecurityPolicy containing the capabilities. The capabilities are normally hard-coded into the CSY, but this is the choice of the CSY implementer.

Additions to the serial comms APIs are configured using the __SECURE_TELEPHONY__ macro. No functions are deprecated.

This process is summarised in the diagram:

What do I need to do?

As a CSY implementer:

Implement CSerial::PortPlatSecCapability() in your CSY. You should choose suitable capabilities for each port and return them in a TSecurityPolicy. Typically, ports should require LocalServices to use personal area networks such as Bluetooth and infra-red. Require NetworkServices for serial ports that stream data to and from phone networks.

When you have chosen capabilities, make sure you inform anyone who needs to know these capabilities. This includes application writers who use your serial ports.

As a serial port user:

You do not need to write any special code for platform security. However, your application must have the necessary capabilities to use each port.

The implementer of the CSY can tell you the capabilities needed for the port. Typically, you will need LocalServices to use personal area networks such as Bluetooth and infra-red, and you will need NetworkServices for serial ports that stream data to and from phone networks. However, this may not apply on your phone.

Alternatively, run your application on the emulator and check the debug output. Look for platform security error messages by searching for the string 'PlatSec'. These messages tell you when function calls fail because the application did not have the necessary capabilities.

Section 5 of common\generic\SyncML\DataSync\Documentation\Data_Synchronisation_Architectural_Description.doc describes the changes to data synchronisation caused by platform security.

Section 5 of common\generic\SyncML\DevMan\design\documents\Device_Management_Architectural_Description.doc describes the changes to device management caused by platform security.

Charconv plugins must be migrated to the ECom plugin framework. This is described in common\generic\syslibs\charconv\ongoing\group\Charconv_Plugin_Migration_Howto.doc.

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

Support for specifying access control to repository settings is added to the Central Repository text files used to provision a repository. Access policies:

• are defined separately for reading and writing settings.

• are defined through security capabilities only (up to 7) or as a combination of SID and up to 3 capabilities.

• can be set at repository level, for groups of settings, specified by a range of index values or a mask, and for individual settings. Any individual setting level policies override any range policies, which override any repository level policies.

• any settings without any policy are inaccessible

Repository and range policies are set in a [platsec] section of the file. For example:

[platsec]
# default capabilities for this repository
cap_rd=ReadDeviceData cap_wr = WriteDeviceData

# capabilities defined per range of indexes
0x100 0x200 cap_rd=ReadDeviceData cap_wr=NetworkServices

# or mask
# All zeros in the mask indicate a wild card state to use same semantics as in individual settings
0x0000003 mask=000fffff

This requires clients to have the ReadDeviceData capability to read from the repository, or WriteDeviceData to write to it. However, this default is overridden for settings with identifiers in the range 0x100 to 0x200, which require NetworkServices capability to be written to.

The definitions of individual settings can also specify access policies. If a [platsec] section has been specified, this section must be named [main]. For example:

[main]
6 int 12 0xf cap_rd=NetworkServices
8 real 1.5 1 sid_rd=0x10658945 sid_wr=0x10658945 cap_wr=CommDD,WriteDeviceData

says that the setting 6 requires the NetworkServices capability to be read; while setting 8 requires the client process to have a secure ID of 0x10658945 to read or write, and additionally to have CommDD and WriteDeviceData capabilities for writing.

Functions that take the deprecated CSecurityDecryptBase and CSecurityEncryptBase classes as arguments are removed. The affected functions are RDbDatabase::ChangeSecurity(); RDbNamedDatabase::Create(); RDbNamedDatabase::Replace(); RDbNamedDatabase::Open(); RDbStoreDatabase::CreateL(); RDbStoreDatabase::OpenL(). New versions of the same functions that don't use the removed classes are available. The change is configured with the SYMBIAN_REMOVE_TRIVIAL_ENCRYPTION macro.

With this exception, all pre-existing DBMS functionality continues to function as before. However, some additional measures are offered to assist clients wishing to share their databases with other applications in a secure manner. This functionality is described in common\generic\syslibs\documentation\syslibs_functional_specification.doc. It is configured using the SYMBIAN_SECURE_DBMS macro.

Note for a high level view of ECom, including platform security functionality, see common\generic\syslibs\documentation\syslibs_functional_specification.doc.

Clients:

There is one source compatibility break that requires a change in all clients that create and destroy ECom plugins. Such code is now required to call REComSession::FinalClose() when all implementations that the client has created have been destroyed, and the client is finished using ECom. The function may be called one or more times but only does final cleanup when it detects all plugins have been destroyed. Note that:

• FinalClose() is present in earlier versions of the OS in which it has no affect. Client code that uses the call can still therefore be run on earlier OS versions.

• FinalClose() must not be called within a plugin destructor method.

• Without this modification, the ECom library will retain a small block of memory. In debug builds where heap memory checking macros are in use, this will cause a panic on process exit.

Clients should also note that the same security capability rules apply to loading an ECom plugin as loading any other DLL: i.e. the plugin must have equal or greater capabilities than the loading process.

Plugin providers

Changes required for ECom plugin providers all relate to data caging, to relocate binary and ECom registration resource files. ECOM plugin DLLs are now installed in the \sys\bin folder, and the RSC files are installed in the read-only \resource\plugins\ folder where they will be discovered by the ECOM Server.

The build tools have been changed to handle these changes, so developers only need to make small changes to their mmp and (for ROM-based plugins) .iby files:

mmp file:

• Change the TARGETTYPE from ECOMIIC to PLUGIN

• Remove any unnecessary TARGETPATH lines as the target location is inferred from the TARGETTYPE.

• The ECom resource file should now be built in a START RESOURCE block as follows:

  start resource <uid3filename>.rss
  #ifdef SYMBIAN_SECURE_ECOM
  TARGET <targetname>.rsc
  #endif
  end

  where targetname is the name of executable that your mmp builds.

• Change any other RESOURCE statements to START RESOURCE blocks. Use a TARGETPATH in the block to specify the target location.

iby file:

Remove the file= and data= lines that correspond to ECom plugins. For each ECom plugin, add a line as follows:

ECOM_PLUGIN(<filename>.dll,<uid3filename>.rsc)

This macro is conditionally defined so that the correct entries are made for all OS versions.

The system agent (SA) is withdrawn, and all clients should migrate to using the base Publish and Subscribe (P & S) API. Migration is described in the Developer Library topic Symbian OS guide\System libraries\Using System Agent\Migrating to Publish And Subscribe.

The task scheduler has changed in the following areas:

• APIs for editing, deleting and querying schedule and task data are subjected to security policy checking. For editing, enabling, disabling, and deleting schedules, and scheduling or deleting tasks, the client must have either the same secure ID as the schedule's creator. or have WriteDeviceData capability.

  For APIs that return an array of schedules or tasks, only those schedules or tasks editable by the client are returned.

  Clients without a secure ID (i.e. they have no 3rd UID specified in their MMP file) are able to use the task scheduler APIs but are treated as having a secureID of 0.

  Because it is not possible to prevent any client from launching an exe through the task scheduler API, the security information of the schedule's creator is passed to the launched executable when a task is launched. The launched exe can use this information to make conditional decisions on platform security related behaviour: for example, to only run if scheduled by a specific secure ID.

• The mechanism used to pass CScheduledTask objects from the Task Scheduler to scheduled executables has changed. The mechanism used is still a temporary file, but the file is now stored in a private location. Thus scheduled executables are no longer be passed the file path as a command line argument. Instead they are passed an open read-only RFile which can be used to retrieve the CScheduledTask object.

  For details, see common\generic\syslibs\schsvr\ongoing\Documentation\Task Scheduler How To.doc.

• The Schedules.dat file, used by the task scheduler to store its persistent schedules, is moved from C:\System\Schedules\ to the Task Scheduler's private data cage. This should not affect any clients.

Additions to the telephony APIs are configured using the __SECURE_TELEPHONY__ macro. No functions are deprecated.

Applications will need certain capabilities to call telephony functions. Read the list of capabilities below. It may be obvious which capabilities your application needs.

Read the list of capabilities below. It may be obvious which capabilities your application needs. If not, you can run your application on the emulator and check the debug output. Look for platform security error messages by searching for the string 'PlatSec'. These messages tell you when function calls fail because the application did not have the necessary capabilities.

TSY implementers will need to read the platform security section of common\generic\telephony\documentation\How_to_write_a_TSY.doc.

Capabilities needed to use Telephony APIs

The following capabilities are needed by some Telephony APIs:

NetworkService

Grants access to the network/operator services. An application with this capability can dial numbers, send messages etc.

ReadUserData

Grants read access to user data. An application with this capability can read the user data stored on the phone/ICC, such as phonebook entries or SMS messages.

WriteUserData

Grants write access to user data. An application with this capability can write the user data stored on the phone/ICC, such as phonebook entries or SMS messages.

ReadDeviceData

Grants read access to sensitive system data. An application with this capability can read the settings stored on the phone/ICC (such as obtaining the service provider name from the ICC) or the network (such as interrogating the status of the supplementary services).

WriteDeviceData

Grants write access to phone settings. An application with this capability can write the settings stored on the phone/ICC (such as setting lock settings) or the network (such as setting the password for supplementary services).

NetworkControl

Grants access to read or write to network protocol controls. Any requests that are too sensitive to be granted the above capabilities require this capability.

Telephony APIs that need capabilities

Some functions in the following classes need one or more of capabilities. See the description of individual functions for to find out the exact capabilities needed:

ETel telephony server

RTelServer RPhone RLine RCall RFax

ETelMM mobile telephony services

RMobileCall RMobileConferenceCall RMobileSmsMessaging RMobileBroadcastMessaging RMobileUssdMessaging RMobilePhone RMobilePhoneStore RMobileONStore RMobileNamStore RMobilePhoneBookStore CAsyncRetrieveVariableLengthBuffer CAsyncRetrievePhoneList CRetrieveMobilePhoneDetectedNetworks CRetrieveMobilePhoneCFList CRetrieveMobilePhoneCBList CRetrieveMobilePhoneCWList CRetrieveMobilePhoneCcbsList CRetrieveMobilePhoneSmspList CRetrieveMobilePhoneBroadcastIdList CRetrieveMobilePhoneNamList CRetrieveMobilePhonePreferredNetworks

ETelPckt packet-switched telephony services

RPacketContext RPacketService RPacketQoS

ETelSat SIM application toolkit services

RSat

PhBkSync phone book synchroniser

RPhoneBookSession

Fax

CFaxTransfer

ETelISV simple telephony API for third parties

CTelephony

ETelCDMA telephony for CDMA networks

RCdmaMobilePhone CRetrieveMobilePhonePreferredLanguages RCdmaMobilePhone RCdmaMobileCall

There are a number of settings relating to platform security that can be configured when building a ROM or running the Emulator:

• turning off checking of specified capabilities

• enabling diagnostic messages. The messages appear in the debug output. The log will contain an error message whenever an application attempts to perform an action for which is does not have the required capabilities. Applications writers can use this to help determine the capabilities needed by their applications.

• disabling enforcement of platform security

• disabling insecure APIs inherited from EKA1

• enforcing the location of binary executables in the \Sys\Bin\ directory

The settings mechanism is described in cedar\generic\base\documentation\Base_How_To_Configure_Platform_Security_Settings.doc.

Many projects will require updates to their mmp files in order to build. The changes include the new keywords capability and vendorid. See cedar\generic\base\documentation\Base_How_To_Configure_Platform_Security_Settings.doc.

Many types of project, including GUI applications, will need to alter their targettype and change from using resource and systemresource to using start resource. For details, see the documents listed under Application framework.

The Capability Management tools are available for anyone involved in assigning or managing capabilities for Symbian OS ROM images and applications.