Latest revision as of 15:53, 17 January 2011

Building Your Application

Platform security introduces a number of new features for building applications on Symbian OS. These are relatively straightforward to implement and in many cases will not result in significant changes.

The features covered in this chapter are changes that have been made to the build tools to support the specification of platform security attributes in binaries – the scheme for allocating UIDs has changed and the project specification (MMP) file syntax has been extended to include new platform security keywords. For general guidance on building binaries for Symbian OS please refer to your software development kit documentation or to [Harrison 2003].

Application Binary Format

The binary format used for EXEs and DLLs in Symbian OS v9 is the same as that introduced in Symbian OS v8.1b, the ARM Embedded Applications Binary Interface (EABI) format. With the introduction of platform security in Symbian OS v9, the main application binary is now built as an EXE rather than a DLL. This is because, as described in Chapter 2, the capabilities of a process are determined by its EXE and each application therefore has its own EXE so that its capabilities can be individually set.

UID Allocation, SIDs and VIDs

A UID is a 32-bit number allocated by Symbian, which may be used for several purposes in Symbian OS. You may already be familiar with the three UIDs used in the binary header in previous versions of Symbian OS. UID1 identifies the file type (EXE or DLL) and is automatically generated by the build tools. UID2 and UID3 are defined in the project’s MMP file – UID2 represents the interface definition that the binary conforms to, and UID3 is a unique identifier used for file associations and so on. Another existing use of UIDs is the package UID (pUID) of a SIS file, as specified in the PKG file (we will return to PKG files in Section 3.3).

Platform security brings with it two new uses of UIDs in binaries: the SID and the VID. These concepts were introduced in Chapter 2, here we will deal with the practicalities. Because these new uses of UIDs have security implications, the method of allocating UIDs has changed. Previously UIDs were issued by email to uid@symbiandevnet.com, but for Symbian OS v9 and later, UIDs are issued from the web site www.symbiansigned.com. Registration is required, but it is simple and provided your application does not need signing, registration is free.

SID

The SID of an EXE is a ‘Secure Identifier’ which uniquely identifies a process when it is running, and is used to control access to protected resources such as the private directory of the process. The SID value is not relevant for DLLs as a process’s SID will always be that of its EXE. As UID3 is already intended as a unique (but unenforced) identifier, we recommend that the same UID be used for both UID3 and SID, simply to avoid confusion. Every EXE on a particular mobile phone is required to have a different SID from all other EXEs on that phone.

SIDs are divided into two ranges: 0x00000001–0x7FFFFFFF is the ‘protected range’, and the installer (see Chapter 8) will only allow EXEs to be installed with SIDs in this range if the package is signed by a trusted authority (such as Symbian Signed (see Chapter 9)). The range 0x80000000–0xFFFFFFFF may be used by unsigned applications – there are no controls on the use of SIDs in this range, so avoiding collisions relies on voluntary cooperation, and thus the security of these SIDs should not be relied on.

If you have previously been allocated UIDs under the old scheme, they will be in the range 0x10000000–0x1FFFFFFF. If you do not require a SID in the protected range, you are welcome to reuse your existing UIDs by adding 0xE0000000 to them (resulting in the range 0xF0000000–0xFFFFFFFF).

VID

The Vendor Identifier (VID) of an EXE is another attribute that can be used to control access to protected resources for a process. Unlike the SID, the VID is not unique to a particular EXE (all EXEs provided by a particular vendor can share the same VID), and an EXE is not required to have a VID. (In fact there are no services in the underlying Symbian OS which use the VID – it is intended for use by the UI software and add-on packages.) The VID of a DLL is not relevant – similarly to the SID, the VID for a process will always be that of its EXE.

There is no unprotected range for VIDs – if you wish to use a VID, the installation package must be signed by a trusted authority.

Allocation Ranges

Table 3.1 summarizes the use of UIDs allocated under the new scheme.

Note that the testing range should not be used when shipping products, but these ranges are guaranteed not to be officially allocated so that they are safe to use for testing purposes without clashing with other legitimate applications.

MMP File Format

Here is an example MMP file for an application that will be signed, using a capability, a protected-range SID, and a VID. The new MMP file syntax is shown in bold:

TARGET project.exe
CAPABILITY ReadUserData
TARGETTYPE EXE

UID 0x100039CE 0x2911003A
VENDORID 0x70B3237D // optional
SECUREID 0x2911003A // optional, defaults to UID3

SOURCEPATH ..\source\project
SOURCE component1_source1.cpp
SOURCE component1_source2.cpp
SOURCE component1_source3.cpp

USERINCLUDE ..\inc
USERINCLUDE ..\source\project

SYSTEMINCLUDE \epoc32\include
SYSTEMINCLUDE \epoc32\include\project

LIBRARY euser.lib
LIBRARY estor.lib

The CAPABILITY parameters can be specified in an inclusive list, as shown above, or an exclusive one through the use of the All keyword. Highly-trusted system DLLs would commonly use a specification such as:

CAPABILITY All -Tcb

Note that Tcb capability is not the same as All, although All does include Tcb. As several system capabilities (which are implicitly included in All) are likely to be reserved by the mobile phone manufacturer, it is safest for add-on software to specify the particular capabilities required, for example:

CAPABILITY LocalServices NetworkServices

You can also use the keyword None, although this is the default.

Developing on the Emulator

Symbian OS v9, like previous versions of the operating system, is supplied with an emulator. The emulator is an invaluable tool for the development and debugging of applications as it simulates mobile phone operation on a Windows-based PC.

With the introduction of platform security in Symbian OS v9 it is no longer possible to deploy an application which performs sensitive operations to a mobile phone without it being signed by a trusted authority. Using the emulator is, therefore, a distinct advantage because you don’t need your application to be signed before testing it. The emulator also has the flexibility to allow platform security to be turned off, which can be useful during development although, for security reasons, this won’t be possible on a mobile phone.

To use the emulator for development you need to ensure that you have established a suitable environment. For more information on setting up the emulator please refer to Chapter 1 of ‘Getting Started’ in [Harrison 2003].

Emulator Configuration

When porting an application from a previous version of Symbian OS it can be useful to temporarily disable platform security. This can be done by modifying the settings in the file \epoc32\data\epoc.ini. In the example below, enforcement of the capabilities ReadUserData and WriteUserData has been disabled for testing purposes.

PlatSecEnforcement ON
PlatSecDiagnostics ON
PlatSecProcessIsolation ON
PlatSecEnforceSysBin ON
PlatSecDisabledCaps ReadUserData+WriteUserData

The following list describes each of these parameters in more detail:

• PlatSecEnforcement – this parameter determines the action that is taken when a capability or other platform security policy check failure occurs. If platform security enforcement is enabled, the appropriate action for the failure is taken, otherwise the system continues as if the check had passed.
• PlatSecDiagnostics – when a capability or other platform security policy check failure occurs, this keyword causes the failure to be logged to the epocwind.out file, located in the temporary directory defined by the Windows %TEMP% environment variable. If PlatSecEnforcement is OFF a warning will be logged instead of an error.
• PlatSecProcessIsolation – this parameter disables insecure APIs inherited from EKA1.
• PlatSecEnforceSysBin – this parameter forces the loader to look for and load binary executables from the \sys\bin directory alone, ignoring any other paths that are specified.
• PlatSecDisabledCaps – this parameter prevents any platform security errors from occurring for each of the listed capabilities by instructing the loader to grant them to all processes. This also means no error or warning is logged to epocwind.out even when PlatSecEnforcement is ON.

Run-time Platform Security Errors

When a process encounters an error due to a platform security issue, this will usually result in a method leaving with the error KErrPermissionDenied (-46). There are two main causes for this – a process loading something that is insufficiently trustworthy, or a process attempting an operation for which is has insufficient capabilities.

Insufficient Trust

When a DLL is loaded into a process (EXE), it must be trusted to use at least the same capabilities as the process. For instance, if an EXE has the capabilities ReadUserData and WriteUserData, it will only be able to load a DLL that has been assigned these capabilities, as shown in Table 3.2.

If you are writing an EXE that uses a third-party DLL with insufficient capabilities you can either review your own capability settings and try to align them with the DLL or contact the DLL vendor. Another alternative is to split the functionality you require by creating a supporting server process (EXE) with capabilities that match the DLL. You should police the APIs on this server to ensure that only your client’s SID or a process with sufficient capabilities has access. Policing of server APIs is described in detail in Chapter 5.

Insufficient Capabilities

Platform security requires all servers to police their APIs to ensure that the calling client has the required capabilities. When a client is found to have insufficient capabilities a KErrPermissionDenied(-46) error is returned. This is illustrated in the following example code:

void SomeClass::WriteFileL(const TDesC& aFileName)
  {
  // open a file server session
  RFs fs;
  User::LeaveIfError(fs.connect());
  CleanupClosePushL(fs);

  // open the output file
  RFile outputFile;
  User::LeaveIfError(outputFile.Open(aFileName, EFileWrite);
  CleanupClosePushL(outputFile);

  // function body omitted for clarity

  // cleanup
  CleanupStack::PopAndDestroy(2, &fs);
  }

void SomeClass::WritePrivateL()
  {
  // set filename to a file in my private directory
  _LIT(KPrivateFile, “c:\\private\\2911003A\\mySettings.ini”);
  WriteFileL(KPrivateFile());
  }

void SomeClass::WriteSystemL()
  {
  // set filename to file in the \sys\bin\ directory
  _LIT(KSysBinFile, “c:\\sys\\bin\\myDLL.dll”);
  WriteFileL(KSysBinFile());
  }

Function WriteSystemL() will leave with KErrPermissionDenied unless the application has Tcb capability, whereas function WritePrivateL() will succeed regardless of what capabilities the application has. For clarity, the private directory path has been hardcoded; normally you would use RFs::PrivatePath() to avoid specifying the SID directly.

Debugging Platform Security Errors

If a platform security error does occur, one of the best methods of resolving it is to view the epocwind.out file, located in your Windows temp directory. Also present in previous versions of Symbian OS, this file now provides detailed information on why platform security errors occur. The file is overwritten each time the emulator is started. Searching the file for ‘*PlatSec* ERROR’ will show which process caused a platformsecurity- related error and, often, details of which API was being called at the time the error occurred:

55.130    *PlatSec* ERROR - Secure Id Check failed - Process X.exe[10208c4e]0001 attempted an operation requiring the
secure id: 01234567. Additional diagnostic message: RProperty::Define with invalid category

You may want to disable platform security either partially or completely to get past such problems during testing.

Assigning and Testing Capabilities

Predicting Required Capabilities

The enhancements introduced with platform security mean that early in the design phase you need to determine what capabilities your application is likely to use. Depending upon the capabilities required it might be necessary for an application to be certified through a program such as Symbian Signed (see Chapter 9).

There are several methods you can use to determine the capabilities an application will need:

• Consider what general operations the application will be performing and select appropriate capabilities. This is usually quite easy to do since the capabilities are coarse-grained and thus there are relatively few to choose from. For instance an instant messaging application might require NetworkServices to access the Internet and ReadUserData for reading from the user’s address book.
• Review each API that you plan to use and record the capabilities required. Note that it may be possible to find a higher-level API which can perform the operation required with fewer capabilities (for example, the Send As server can be used to send SMS messages without requiring the full access to telephony APIs granted by the NetworkServices capability).
• Trial and error, adding capabilities as they are required.

A mixture of the first and second approaches is recommended, examining APIs in detail when it is not clear from inspection alone. Trial and error is strongly discouraged; it is important to plan ahead in a project when the application may need to be approved by a third party (e.g. Symbian Signed, a network operator, or the mobile phone manufacturer) in order to be granted certain capabilities.

Testing Capabilities

When testing your application you may wish to try calling APIs both with and without sufficient capabilities to confirm that the application behaves as expected in both scenarios. This is particularly important when you are testing a server that exposes APIs to clients that may have very different sets of capabilities. The best way to do this is by creating multiple copies of your test harness, each with a different capability set. The petran tool can be used to modify the binary’s E32 header parameters, including its UID, SID, VID and capabilities. This tool can also be used to determine which capabilities are declared in a particular EXE or DLL, using the command:

petran -dump s e32imagefile

This command only works for EABI binaries and does not detail which capability polices each API. For detailed information consult the Symbian OS Library at www.symbian.com/developer/techlib or, for a third-party DLL, consult the vendor. Note that the capabilities declared in a DLL indicate those it is trusted with, not necessarily those it will use.

As there are no capability warnings generated at build time, you will only discover mismatches by run-time testing. This is because many of the capability checks that are made are conditional. For example, calls to file system APIs may or may not require a capability, depending upon the path supplied as an argument (as illustrated in the example code above).

Packaging Your Application

The software installer (covered in detail in Chapter 8) is the ‘pinch point’ for getting an application correctly installed on to a Symbian OS v9 mobile phone. Unlike the emulator, where binaries can simply be copied for testing, on a real mobile phone it is the installer that places files in the correct locations and verifies that binaries have capabilities that do not exceed what is allowed based on the signature. Once a binary’s capabilities have been checked by the installer, the installer’s requirements are satisfied and there is no further action – the binaries are then resident on the mobile phone. The only legitimate method for running an application on a real mobile phone is to pass it through software install first, where it will be subject to these checks. In this section we cover the new platform security features in the tools used to create an installable software package.

Package File Changes

Developers use a Symbian OS package file to give the package creation tool (MakeSIS) the information necessary to build the final SIS file.

The package file (PKG) options are numerous, non-trivial and won’t be covered here. Instead we recommend you refer to the Symbian OS Library documentation under Tools and Utilities, then Installation Reference. Looking at the examples provided in that documentation may also help you understand the large number of software deployment options that can be provided by a single SIS file.

The only significant recent addition to the package file is the inclusion of a field called Non-Localized Vendor Name (which is specified in PKG syntax by the colon ‘:’ directive). The reason for this being a non-localized field is simply that we don’t want signing bodies to have to store and track all the possible names belonging to an international vendor.

Prior to Symbian OS v9, only localized vendor names existed – that is a ‘vendor name’ provided for each of the languages supported by the package. In Symbian OS v9 a single consistent non-localized name is required in addition to the localized names. This field remains consistent the world over and may be used by signing authorities to further identify a package vendor prior to signing (more on that later).

Note that, although this field may not be employed by all signing authorities, the MakeSIS tool and the software installer will check that it is present. Here is an example of the use of this new field in the PKG file:

&EN,FR ; Languages

; Package Header
#{"App Name","Nom d’App"}, (0xE1234567), 1, 0, 0, TYPE=SA
; Localized Vendor Names
%{"Joe’s Software", "Logiciels de Joe"}
; Unique Vendor Name
:”Joe Bloggs PLC, London”

Some changes have been made to the tools for signing packages; as a consequence, signing certificate information is no longer specified in the PKG file. If you wish to reuse existing PKG files from earlier versions of Symbian OS, including any certificate data, the certificate information should be removed or commented out, as follows:

;
; No longer used in Symbian OS v9 PKG file
; * "MyACSPublisherID.key","MyACSPublisherID.cer"
;

Package Creation Tools

Prior to Symbian OS v9, developers would have used two PC-based tools from the developer kit: makekeys.exe and makesis.exe. In Symbian OS v9, however, the signing features of makesis.exe are split out into a new tool called signsis.exe. There is also a wrapper tool for certain environments. A summary of these features is given below.

MakeSIS

makesis.exe generates package archives using the new SIS file format covered in Chapter 8. These archives contain all the information necessary to achieve the installation of the package on a mobile phone – except the digital signing material. If you want to be sure you have the new version of makesis.exe then invoke makesis –v and it should report a version of 4 or above.

MakeSIS is primarily driven by supplying it with the PKG file that specifies all the files, rules, options, and dependencies that you require. The package file format is fully specified in the Symbian OS Library, but as a quick reminder you can always invoke makesis –h to view some help information.

MakeSIS can also be used to create upgrades for packages that are already deployed, and to create the necessary controller files, which are required to deploy packages on removable media cards so that they become available to the mobile phone simply by inserting the media card.

Package Signing Tools

Chapter 2 introduced the concept of capabilities. By no means all of the Symbian OS APIs require capabilities in order to use them – we estimate that around 40% now do. Also keep in mind some of these are so specialized and low-level that only a handful of applications ever have good reason to use them. Some of these capabilities may be granted by the user at the time the application is installed (depending on how the manufacturer or operator has configured the mobile phone – see Section 3.4.1). Other capabilities may require the application package to be digitally signed by a trusted authority (such as Symbian Signed, covered in Chapter 9).

Makekeys

makekeys.exe is unchanged from previous Symbian OS releases, and can still be used by the developer to create digital certificates or PKCS#10 certificate requests.

If you wish to create your own signing certificate to sign your package, then use makekeys.exe to generate a self-signed certificate and private key (although note that packages you sign yourself will not be granted capabilities automatically). Alternatively, if you are planning to have an authority sign your digital certificate, then you can generate a certificate request, which can be sent off to a certificate authority via the web or email.

Note, in some cases, you may receive a signing certificate without using makekeys.exe – this is the case, for example, with developer certificates (covered in Section 3.4.2) issued by Symbian Signed (see Chapter 9).

SignSIS

Package files can now be signed more than once. Symbian considered that making packages and signing packages were two separate activities, so the signing activity was split out into a separate tool called signsis.exe rather than have one very complex makesis.exe with multiple roles and yet more command-line switches.

SignSIS takes a SIS file as input, along with a certificate (or list of certificates) and a private key, and then produces a signed SIS file as output. signsis –h will remind you of the parameter ordering. You’ll notice there is a switch to provide you with some useful information about the output file.

Finally, note that signings are performed in such a way that they encapsulate previous signings. For example, if you sign your SIS file and send it to an authority for signature, their signing will encapsulate both the SIS file and your signature. SignSIS also allows the removal of a signature, but because of this encapsulation only the outer signature can be removed each time – it is not possible to remove an inner signature while leaving outer signatures present.

CreateSIS

For convenience, Symbian also provided a script called CreateSIS (createsis –h for help on the syntax) which will execute Makekeys, MakeSIS and SignSIS in the right order and with the right options for straightforward signing operations. CreateSIS can automate the generation and use of a self-signed certificate and private key when the need is simply to have a signed package rather than to have it signed by a trusted authority.

Testing on Mobile Phone Hardware

The emulator uses binaries compiled for a different target from a real mobile phone and, although most applications can be fully tested on the emulator, it’s imperative that you test your applications on real mobile phone hardware before release. Although the emulator tries to be as close to a ‘real’ phone as possible, there will always be differences in behavior due to the fact that your PC is a much more powerful device, with more memory and storage space at its disposal, and it is based on a different processor architecture to the mobile phone. Only by testing on real hardware can you combat real-world performance problems or design flaws.

The Mobile Phone’s Security Policy

When building a Symbian OS-based phone, the mobile phone manufacturer can make many choices that affect the look and behavior of various features. The security policy settings are among these choices. We, therefore, cannot be definitive regarding the security policy that the manufacturer of your targeted mobile phone will have chosen. Symbian is, however, encouraging mobile phone manufacturers to base their security policies on a common reference point, which is described in a series of documents entitled Symbian Recommended Practices. The latest version of these documents can be found on www.symbian.com, in the ‘Technology’ section.

Be aware, however, that each mobile phone manufacturer may configure the software install certificate store as they please, to determine who is entitled to grant which capabilities. This will in turn determine what authorization is required. Some particularly sensitive capabilities such as Tcb and Drm may be reserved for the mobile phone manufacturer’s own use.

Developer Certificates

The use of trusted authorities to sign packages and to approve the granting of capabilities presents us with an interesting ‘catch 22’ situation. If the installer will only install SIS files that use some of the more sensitive capabilities when they are signed, but, in order to get a SIS file signed to allow access to those sensitive capabilities you must submit it through an industry-agreed test procedure which it must pass, how does a developer test such an application during development? A few options were considered:

• Special hardware could attach to mobile phones and ‘unlock’ the installer. This would not only be a risk in general (for example, users disabling the security model on their mobile phones), but it would also be costly.
• Special software builds could be supplied from licensees for use by developers only, which would disable the security model just for them. Again this would be costly and unworkable
• An interim certification process could enable capabilities, but would not allow reuse of the application by anyone other than the developer.

It was the latter option that was decided upon because it was easy, cheap and elegant, with none of the drawbacks listed for the other options. These temporary, interim certificates, which allow testing on your own mobile phone, are called ‘developer certificates’.

The basic concept of a developer certificate is simple. It is:

• a certificate issued to you (or your organization) by a trusted signing authority (for example, Symbian Signed, or perhaps a mobile phone manufacturer or network operator)
• locked to a specific mobile phone or phones (in the case of GSM phones this is, typically, done by specifying the unique IMEI numbers)
• limited to granting a chosen subset of capabilities for software running on those phones
• valid for a limited period from the date of issue.

You will need to check the availability of developer certificates for the particular mobile phone model you are targeting. However, we expect that in most cases developer certificates will be available from Symbian Signed (see Chapter 9).

Anyone with a copy of SignSIS and a valid developer certificate can sign an existing SIS file. This will aid you, as a developer, during your testing process if, for example, you wish to make your SIS file available to a limited group of external beta testers. Your beta testers will be able to obtain developer certificates for their own handsets and resign any ‘raw’ SIS files you send them to test, thus ensuring they can test your application with the appropriate capabilities. The syntax for SignSIS is as follows:

>signsis “SISFileToBeSigned.sis” “NewSignedSISFile.sis”
    “DevCert.cer” “DevCert.key”

It is worth noting at this stage that the ‘user experience’ of SIS files signed using a developer certificate is not a pretty one – neither is it intended to be! When installing such SIS files, several ‘health warnings’ will be displayed to notify the user that the application is test software, not a shipping product and that there are risks involved in continuing. Such warnings are no problem for developers or experienced testers – but they are in place to ensure developer certificates are not accidentally misused or deliberately abused to distribute software to ‘real’ end users.

Packaging the Completed Application

The final stage of your development process is, of course, the release of your application to your target end-users. Once you have completed thorough testing and debugging on both the emulator and target phone as described in this chapter, you should rebuild a new SIS file with MakeSIS containing your final release build binaries. You will then be guaranteed a ‘clean’ SIS file with the correct binaries inside it and without any developer certificates attached.

Once you have this SIS file you can complete the final steps of the release process. If you are not using any capabilities which require a digital signature for access, your SIS file can be released directly to users (although note that they will still see a warning that the SIS file is from an ‘untrusted’ source). If you are using capabilities, or wish to build user confidence and remove the standard installation warnings, you should complete your release process by submitting your application to an appropriate testing and certification program, in order to have it countersigned officially against the appropriate root certificate in your target device.

Summary

This chapter examines some subtle changes to the development lifecycle in Symbian OS v9, concerning how applications are built, tested and packaged.

In the first section, we covered how to build an application as an EXE and assign its capabilities, SID and VID. This determines the security attributes of the application that will be used at run time.

In the next section, we considered use of the emulator when initially developing an application, how to determine which capabilities are needed and how to test the use of capabilities. The emulator provides diagnostics which are helpful in determining the cause of problems due to incorrect assignment of capabilities.

In the third section, we explained how to use MakeSIS and the new SignSIS tool to create a signed application package. A signature from a trusted authority is required for some capabilities to be used by an application. The SIS file also now includes a new ‘non-localized vendor name’ field.

In the final section, we discussed how to test an application using capabilities on an actual mobile phone, including the new concept of developer certificates which enable you to freely and easily develop and test your applications on your own hardware.

Copyright © 2006, Symbian Ltd.