![[Index]](../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../a_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
||
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:
This section describes the changes that must be made to the Application Engines following the introduction of Platform Security. It describes:
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):
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.
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.
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.
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.
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::RecreateSystemTemplateL()
Several new functions assist clients:
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.
|
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.
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:
|
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.
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 = "";
}
};
}
};
}
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
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: 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.
|
|
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.
Your applications need the ReadDeviceData capability to read from the Chargecard table.
You do not need any capabilities to read data from other tables.
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.
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.
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.
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:
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.
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.
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.
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 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.
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
|
|
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:
Two topics that apply to all protocols, described in Comms infrastructure:
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.
|
![[Top]](../../../a_stock/arrow_up_2.gif){kind=icon}
RSocket::SetOpt()
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().
|
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().
|
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().
|
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:
|
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:
KTinyTPDiasbledSegmentation (note incorrect
spelling)
These are the capabilities for the cdmasms.prt protocol
module. See CDMA SMS for more
information.
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.
|
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.
|
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.
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
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.
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
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)
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)
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()
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
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()
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).
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.
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 have both changed, as described below:
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.
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.
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.
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.
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.
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:
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.
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.
The following capabilities are needed by some Telephony APIs:
Grants access to the network/operator services. An application with this capability can dial numbers, send messages etc.
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.
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.
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).
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).
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.
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:
RTelServer
RPhone
RLine
RCall
RFax
RMobileCall
RMobileConferenceCall
RMobileSmsMessaging
RMobileBroadcastMessaging
RMobileUssdMessaging
RMobilePhone
RMobilePhoneStore
RMobileONStore
RMobileNamStore
RMobilePhoneBookStore
CAsyncRetrieveVariableLengthBuffer
CAsyncRetrievePhoneList
CRetrieveMobilePhoneDetectedNetworks
CRetrieveMobilePhoneCFList
CRetrieveMobilePhoneCBList
CRetrieveMobilePhoneCWList
CRetrieveMobilePhoneCcbsList
CRetrieveMobilePhoneSmspList
CRetrieveMobilePhoneBroadcastIdList
CRetrieveMobilePhoneNamList
CRetrieveMobilePhonePreferredNetworks
RPacketContext
RPacketService
RPacketQoS
RSat
CFaxTransfer
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.
|
Copyright ©2008 Symbian Software Ltd. |
|
![[Previous]](../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../a_stock/btn_top.gif)
![[Next]](../../../a_stock/btn_next.gif){kind=small}