Developer Product Briefs
Migrate Mobile Client Applications
Nokia's S60 3rd Edition represents a binary break to benefit from the Symbian OS security architecture. See how to port your client apps built for the platform's previous editions..
Migrate Mobile Client Applications
Port your applications built for the S60 1st/2nd Editions to the S60 3rd Edition platform to take advantage of the Symbian security architecture.
by Phong Vu
April 17, 2006
The S60 3rd Edition platform is based on the Symbian OS platform security architecture (Symbian OS 9.1), which is rearchitected from its previous versions to meet the security requirements of the open mobile phone platform. The primary aims of the Symbian OS platform security architecture are protecting the integrity of the phone; providing confidentiality for sensitive data; controlling access to sensitive operations; and preventing—as opposed to detecting and reacting to avoid corruption of binaries and data—and avoiding misuse or abuse of operations.
The capability model and data caging scheme are among the core concepts in the platform security. Capabilities determine the privilege of a process to perform sensitive operations on a mobile device, and data caging provides a mechanism of file-access control.
Source code and binary code breaks were inevitable because of the evolution from nonsecure to the secure platform architecture. However, the changes were done deliberately and with great control to minimize the effects on porting client applications from previous releases of the Symbian OS platform.
Porting S60 client applications implemented on the S60 2nd Edition platform to the 3rd Edition can be as simple as doing little modifications in a few places and recompiling the application. However, the porting can be much more complicated depending on the implementation of a particular application, especially if the application involves a client/server solution and the third-party server application was implemented using Symbian Epoc Kernel Architecture 1 (EKA1) used in the S60 2nd Edition.
Let's take a look at the basic components and the differences among client applications developed for S60 1st and 2nd Editions and for the 3rd Edition. This comparison will give you a starting point for your migration work.
Comparing MMPs
If you compare the MMP files among the S60 3rd Edition and the previous two editions, the first feature you'll notice is the change of application types (see Table 1). In S60 1st and 2nd Editions, the target path for an application needs to be defined explicitly in the MMP file; in S60 3rd Edition, all executable programs and DLLs must be located in the \sys\bin\ location, and there is no need to specify the target path in the MMP file.
There are some new keywords to be declared in an MMP file for a S60 3rd Edition application project:
- VENDORID defines a vendor identifier (VID). The VID uniquely identifies the source of the application.
- SECUREID defines the secure identifier (SID), which is a locally unique identifier (that is, in the device where it's installed). Each executable contains a secure identifier. The purpose of a SID is to determine which private directory a process can access and identify the caller applications. If a SECUREID statement is not given, the UID3 specified in the MMP file is used.
- CAPABILITY defines the capabilities for the application. If this keyword is not present in the MMP file, the default CAPABILITY NONE is used.
Application resource files' locations are also changed in the 3rd Edition to comply with the data caging scheme (see Table 2 for a comparison of file locations between both the first and second editions and the third edition of the platform).
Changes in the application information file framework. In S60 3rd Edition, application information files (for example, appname.aif) are replaced by application registration information files (for example, appname_reg.rsc), which support scalable and localizable application icons and captions.
Because the system folders such as \sys\bin, \resource\apps\, resource\plugins, and so on are flat directories—meaning you cannot create any subfolder under those folders and all client applications are installed under the same locations—the potential problem of applications' file names crashing is higher than in the previous platform releases where most of your application components are stored under your own application's folder name. When the installer application detects an existing file that has the same file name as your application's file that is being copied into the same subdirectory (even on a different drive), the installer application will stop the installation process.
Therefore, make sure that your executable program and its components' files names are unique. If your application and its component files (DLLs, or resources that go under \resource\apps\) have popular names—for example, addressbook.exe, appengine.dll, or image1.mbm—using the UID3 of the application or the DLL together with the name of the component to make a unique file name—for example, appengine_ a0000180.dll or image1_ a0000180.mbm—is recommended.
There are two new files to add to a project: icons_mif.mk and appname_reg.rss. The icons_mif.mk file ("mif" stands for multiple images file) holds information about bitmap or SVG images (refer to the S60 3rd Edition SDK's help for more details on the content of an MK file). The AIF keyword is no longer needed in the MMP file. Instead, this line needs to be added to the bld.inf file under the PRJ_MMPFILES section:
gnumakefile icons_mif.mk
Changes in the application framework. Prior to the S60 3rd Edition platform, S60 GUI applications were implemented as polymorphic DLLs (though the file name extension is APP), which always have a DLL's entry point and one export function:
GLDEF_C TInt E32Dll(
TDllReason /*aReason*/ )
{
return KErrNone;
}
EXPORT_C CApaApplication*
NewApplication()
{
return (
static_cast<CApaApplication*>(
new CHelloWorldApp ) );
}
Under the secure platform, every GUI application is an executable program with the standard entry point function to be called by the OS to start the program. Each executable program also implements a static factory function that creates concrete document objects. So you need to modify the two functions shown previously to these forms:
#include <eikstart.h>
GLDEF_C TInt E32Main()
{
return EikStart::RunApplication(
NewApplication );
}
LOCAL_C CApaApplication*
NewApplication()
{
return new CHelloWorldApp;
}
After modifying all the basic parts, you can import the MMP project file using CodeWarrior Development Studio for Symbian OS version 3.1 for the compilation and build.
Reimplementation
The changes just discussed are enough for porting a simple application only. Your application might be more complex with a lot more code to be ported. For instance, if your application includes a MIME-type recognizer, which on the S60 2nd Edition platform was implemented as a polymorphic MDL file, the whole recognizer will need to be reimplemented to comply with the ECOM plug-in framework for the MIME-type recognizer module required in the S60 3rd Edition.
For content-handler applications, the OpenFileL() function that your application derived from CAknDocument needs to be reimplemented to take the new type of parameters conforming to the changes in the document handler framework:
// Implementation for S60 1st/2nd
// Edition
CFileStore*
CHelloWorldDocument::OpenFileL(
TBool /*aDoOpen*/,
const TDesC& aFilename,
RFs& /*aFs*/ )
{
iAppUi->OpenFileL(aFilename);
return 0;
}
// Implementation for S60 3rd
// Edition
void
CHelloWorldDocument::OpenFileL(
CFileStore*& /*aFileStore*/,
RFile& aFile)
{
((CHelloWorldAppUi * )iAppUi)->
OpenFileL(aFile);
The S60 platform provides a number of standard UI components. Some of these components require the client application to be a skin-aware application. Failing to satisfy this requirement might result in incorrect display of UI components or even application crashes; therefore, it is recommended you always call BaseConstructL(EAknEnableSkin); in the ConstructL() function of your application UI class.
Unfortunately, if your application implements a client/server solution using Symbian EKA1, you might need to rewrite most of your code as the changes in the client/server framework in the Symbian EKA2 supporting platform security have caused heavy source code breaks.
Now let's take a look at the new SDK and tool chain. Developing client applications for the S60 3rd Edition requires the new S60 3rd Edition SDK and new code compilers that are included in the SDK package. You can download the SDK for free by visiting the Forum Nokia Web site and following the link to the Tools and SDKs section.
The new x86 complier WINSCW 3.4 is for building applications run on the emulator, and the GNU Compiler Collection (GCCE) compiler is for building applications run on target devices. (Note that applications built for ROM will need to be compiled using the ARM RVCT compiler, which is not available in the SDK.) The new SDK also provides many advanced features such as supporting multiple languages, dynamically changing the screen resolution/orientation, and handling platform security (enable, disable, and diagnostic messages).
It is wise to solve one problem at a time while porting your application, particularly when you are working with a new concept relating to platform security. Start to work with all changes in the source code to make sure the application is compiled without any error and it can run on the emulator.
At this point in time, you can ignore the capabilities that might be required by the system for your code to perform certain sensitive operations (for example, connecting to the Internet). To ignore them, turn off the platform security enforcement so that the emulator will not perform capability checks while your application is running. You can turn on and off the platform security enforcement either by changing it from the emulator's Tools menu (in the Preference dialog that displays when you select Platform Security) or by modifying directly the epoc.ini file located in the Symbian\9.1\S60_3rd\Epoc32\data\ folder in the SDK:
// epoc.ini file content
PlatSecEnforcement OFF
Working With Capabilities
After testing all the functionalities of your application without capability checks, you can now start to work with the required capabilities. There are a couple of ways to detect the capabilities the system requires from your application. Let's look at them.
One way is to check the required capabilities from the API reference in the S60 3rd Edition SDK help document. For example, open the CSenServiceManager class reference where you can find information on the required capabilities: ReadUserData, WriteUserData, and NetworkService. The Symbian developer library reference provides capability requirement information at the function level; for example, the RSocketServ class reference shows that the StartProtocol function requires the NetworkControl capability.
Because the SDK help document doesn't yet cover capability requirements for all APIs and many servers have a complex security policy where a required capability is checked at individual Inter-Process Communication (IPC) operation, here are a few tips and tricks to find out as much information as possible from the SDK's help document:
- If an API reference doesn't document the capability information, the required capability for using that API is probably "none." This condition is, however, not applicable in all cases.
- Search for the class and function name from a Symbian Doxygen analysis of the capabilities document.
- Search for a capabilities keyword from a header file (note that this option can be a time-consuming action, and the keyword is not always found).
The other way to detect for required capabilities is to ask the emulator to perform capability checks and detect missing required capabilities. Note that this approach is reasonable only for porting an application. For new application development, required capabilities should be analyzed during the designing phase or at least when developing the application.
To begin this method of detection, turn off the platform security enforcement feature of the emulator as described previously. Also, remember to enable the log-to-file option so that the emulator will write log information into the epocwind.out file (the path to the file is c:\Documents and Settings\username\Local Settings\Temp\). From the emulator's Preference menu, check the enable epocwind.out logging checkbox or modify the epoc.ini file like this:
// epoc.ini file content
LogToFile 1
Next, define the capability in your project MMP file with "None," and then run the application to test all the functionalities. Finally, open the epocwind.out file, and start to search for the *PlatSec* WARNING term. You will see warning messages throughout the file—for example:
*PlatSec* WARNING - Capability
check would have failed -
A Message (function number=
0x00000001) from Thread
AddressBook[a0000180]0001::
AddressBook, sent to Server
!Sen, was checked by Thread
Sen.EXE[101f96f4]0001::Main
and was found to be missing
the capabilities:
NetworkServices
This information doesn't give you the exact reason or the name of a function that requires the capability, but it does help you identify the missing required capability. Remember also to check the thread name, which identifies the application that would need the capability. In the previous sample, the thread is from the AddressBook testing application.
You can test your application as described previously with the PlatSecEnforcement flag turned ON. However, your application might panic at startup or at some testing function if the required capability is missing. In that case, the log file would look like this:
*PlatSec* ERROR - Capability check
failed - A Message (function
number=0x00000070) from Thread
AddressBook[a0000180]0001::
AddressBook, sent to Server
DosServer, was checked by Thread
DosServer.exe[101f6efa]0001::
DosServer and was found to be
missing the capabilities:
ReadDeviceData WriteDeviceData
ReadUserData WriteUserData
Copy the required capabilities and add them to your project MMP file. Reimport the MMP file, and recompile the application to run the test again until all required capabilities are added.
Package and Installation Changes
The package file (PKG) syntax is changed slightly, and there are also two new directives to be used: the special characters % and :. The meaning of each character is explained in the sample PKG file (see Listing 1). The hardware dependency syntax is changed so that the UID is not contained in round brackets—(UID)—but in square brackets—[UID].
There is a new requirement for an installed application to be covered by the backup/restore facility; a backup_registration.xml file is created and copied into the application's \private\SID\ folder. Application executables, DLLs, and resource files' destinations must be changed to match the requirement of data caging (see Table 2). Here is the simple content of a backup_registration.xml file:
<?xml version="1.0" standalone=
"yes"?>
<backup_registration>
<system_backup/>
<restore requires_reboot =
"no"/>
</backup_registration>
Signing your application is mandatory so that the application can be installed on a target device. The signing process takes several steps:
- Acquire from Symbian's Symbian Signed page a developer certificate/key pair with the capability your application needs, or just make a self-signed certificate/key pair (refer to the SDK help for instructions). Note that a developer certificate/key pair is only for application testing purposes. Also note that self signing is just to make the installation package satisfy the requirement of the application installer, and a self-signed application is the same as an untrusted application. Also, a self-sign application can only have its UID3 in the unprotected range [0xA0000000 - 0xAFFFFFFF or 0xE0000000 - 0xEFFFFFFF] and carry user-grantable capabilities:
[LocalServices NetworkServices
ReadUserData WriteUserData
UserEnvironment]
- Use the makesis.exe tool as normal to make an installation SIS file.
- Use the signsis.exe tool to sign the SIS file—for example:
signsis helloworld.sis
helloworld.sisx
c:\Symbian\9.1\SelfCert\my.cer
c:\Symbian\9.1\SelfCert\my.key
To deploy your application for a commercial purpose, you will need to get your application Symbian-signed. Visit Symbian's Symbian Signed page for details on the signing process.
This discussion gives you a good foundation for porting your applications built for the S60 1st and 2nd Editions to the S60 3rd Edition platform, which was designed to take advantage of the Symbian OS security architecture. Security threats are increasing and critical to mobile phone end-users, and as platform and application developers we are obligated to take actions to suppress the threats and protect end-users' interests. One of the biggest benefits of taking the security measures in your application development that are described here is the trust you will win from the end-users of your application, who have high expectations for reliability, integrity, privacy protection, and security when installing and running your application on their mobile phones.
About the Author
Phong Vu is chief Symbian engineer in the Forum Nokia Technical Services and Consultancy. Phong is a renowned Symbian expert and is based in Finland.