Latest revision as of 13:03, 20 January 2011

Introduction to the Native Software Installer

What the Installer Does

The native software installer is a Symbian OS component which manages the installation of add-on (‘after-market’) software packages – software which is added to the mobile phone after its manufacture, typically by the phone user, rather than software which is included in the ROM of the phone. A user interface (UI) layer is added by the mobile phone manufacturer, so the controls may look quite different on, say, a Series 60 phone and a UIQ phone, but the same Symbian OS software installer engine is doing the work in both cases.

The software installer is one of the platform security ‘gatekeepers’, as it is responsible for ensuring that add-on native software is copied to the mobile phone with the correct set of security attributes. Before reading this chapter, which contains frequent references to digital certificates, signatures and chains, you may find it useful to refer to Appendix B for a review of some of the basics of cryptography.

In Symbian OS releases prior to v9, installation could take place from a PC connected to your mobile phone. This is still the case, but the interaction you have during a native software install will now take place with the mobile phone and not with the PC, for reasons of trust and security that we will look at later.

We are using the term ‘native’ to indicate that the software which is installed runs directly on Symbian OS itself and to differentiate these applications from other, layered, types of software such as Java MIDlets. Java MIDlets do not run directly on the OS – they are managed and run in a Java Virtual Machine. MIDlets also have different security requirements, which are out of the scope of this book. Consequently, MIDlets have a separate install mechanism, which won’t be covered here.

Now that it’s clear what type of applications we are referring to, we will drop the term ‘native’ and simply refer to the ‘software installer’ (sometimes SWI for short) or just ‘installer’.

In short, the software installer’s key responsibilities are:

• to validate and install native software packages (SIS files) on the mobile phone
• to validate software that is delivered in a pre-installed form on media cards
• to handle upgrades and removals, and provide package management services to the rest of the platform.

The rest of this chapter explains how the installer actually achieves the above responsibilities. First, however, let’s take a brief look at how things have changed from a security perspective.

Platform Security and its Impact on the Installer

Inevitably, improving security in any way requires the introduction of new security checks and Symbian OS platform security is no different in this respect.

As an example, previous versions of the Symbian OS installer placed almost no limitations on where a package author could deliver files into the file system. Data caging clearly changes this situation significantly. In brief, here are a handful of new rules, which we will cover in much more detail as this chapter unfolds:

• For a given drive, binaries (EXEs and DLLs) should be placed in one (and only one) designated file area. If it should prove possible to circumvent this rule – perhaps by getting a program to create an EXE or DLL outside the designated area – the binary certainly won’t be launched by Symbian OS v9.
• The overwriting of files might not be permitted – especially if the file affected belongs to another package.
• The capabilities an application EXE needs may have to be signed for (that is, there are some things an EXE will not be allowed to do without authorization).

In short, the software installer polices software installations to ensure that they conform to platform security rules and, therefore, contributes towards maintaining the integrity of the mobile phone. The installer itself can, clearly, perform privileged operations (such as the copying of files into restricted areas) based on certain criteria, which we will describe later.

As such, it is appropriate to consider the installer as a ‘gatekeeper’ since it examines credentials and enforces rules, and only allows software into the OS environment if it passes these tests.

Installer Configuration – a Warning

A large number of software installer rules and behaviors are described in this chapter. Due to the number of configuration options available to the mobile phone manufacturer, it is possible that the behavior described here is not what you may observe on a specific mobile phone model. Some manufacturers may choose to enable a particular behavior while others may not.

Validating Capabilities

As previous chapters have explained what capabilities are, how they behave, and how they are specified within binaries, it’s time to look at the signing requirements. Failing to get a package adequately signed may lead to installations being aborted. This section should help you understand what needs to be done and how everything actually works.

Who Can Grant Capabilities

In Chapter 2, we mentioned that the mobile phone manufacturer might choose to allow some capabilities to be granted to software by the user at install time. The software installer will check for signing approval for system and user capabilities, and may also seek user approval for some user capabilities, as we’ll see shortly.

The decision about which capabilities may be granted by the user is in the hands of the mobile phone manufacturer and it’s quite possible for them to configure one phone model differently from another (although this is probably unlikely). It’s also possible for some capabilities always to be granted to running processes – essentially making them ignored. Again this configuration choice is in the hands of the manufacturer.

Similarly, the mobile phone manufacturer decides which signing authorities will be trusted to approve which capabilities, and the requirements of the signing authority may vary. We expect that in most cases, the Symbian Signed scheme will be included, and the requirements of that scheme are discussed in Chapter 9.

Assuming that you know what capabilities your package as a whole requires, and thus what approval it needs, let’s now cover what you will need to do to make it generally installable.

What You Need to Do

Firstly, and most simply, if your package contains no binaries, or only binaries requiring no capabilities, then it is not necessary to have it signed by a signing authority (although you may wish to do so simply to avoid the install-time warning which is shown to the user when untrusted packages are installed). However, the mobile phone may be configured to require all packages to be signed – in this case you can ‘self-sign’ your package, and this is covered in more detail later. Even if this isn’t a mandatory requirement, you can still sign it anyway – the software installer won’t complain about extraneous signatures as long as you sign it correctly and the validity dates are current.

User-Granted Capabilities

If your package contains binaries requiring only user-grantable capabilities, then again you do not have to have this package signed by a signing authority. You must be aware, however, that the mobile phone user will be asked whether they wish to allow your package to be installed with those capabilities. If the user says no, the installation will be aborted. Note that if you choose to have your package signed by an authority, and the authority endorses your user capabilities then the user will not be asked for verification at install time.

Signature-Granted Capabilities

Finally, we need to cover the situation where your package contains binaries requiring one or more capabilities that the user is not able to grant. Clearly, for your package to be granted the trust required for these capabilities, you will need to submit it to a signing authority. Once verified and signed, your application will be installable and able to access or employ sensitive parts of the system which impinge on device integrity and user privacy.

Situations Which Always Require Package Signing

In addition to the general situations above, there are other reasons why signing your package may become necessary. These are covered later.

An All-or-Nothing Approach to Package Installation

At install time, your package is evaluated for its suitability to be installed, based on:

• the capabilities your package requires
• how (or if) you had your package signed.

This evaluation is based on looking at the signatures that are present, and in some cases asking the user to agree to your package being installed with the capabilities it requires.

From the installer’s perspective, binaries that arrive within SIS files are requesting permission to be installed with the capabilities that have been declared within them by the developer. The installer, therefore, is either going to grant permission (that is, install all the files present) or deny permission (fail the install).

Note that there is no halfway solution here – the installer either grants permission for all the binaries present to be installed or rejects the entire package. Similarly, for each binary within the SIS file, the installer will either validate the grant of all the capabilities required or none at all. In short, there’s no way that the installer will install some binaries and not others unless conditional statements are present in the SIS file. In addition, the installer will never modify a binary, so there’s never a situation where the installer will remove or downgrade the capabilities of a binary.

Any problems with a package will, therefore, result in the entire package installation being aborted. Any partial changes made up to that point will be rolled back. Incidentally, if power fails during a software install operation, rollback may occur on the next invocation of the installer, or after boot – depending on the particulars of the installation.

Certificate Chaining

The signing certificates themselves can be either self-signed, or signed by another certificate – which itself could be self-signed or signed by another certificate, and so on.

Building the Chain

What we essentially have here is the means to build a certificate chain, and we can do this by:

1. Identifying the certificate’s issuer.
2. Validating the signature of the current certificate (using the issuer’s public key).
3. Checking the current date is within the validity range for the certificate.
4. Going back to step 1, but this time with the certificate of the issuer.

Eventually the chain will terminate either on a self-signed certificate – from which we can go no further – or at some point where we recognize the certificate, trust it and consciously decide to go no further.

Figure 8.1 How Certificates and Keys Relate to Each Other

A Complete Chain

The certificate terminated on is generally referred to as the ‘root’ certificate or ‘trust anchor’ (see Figure 8.1). The certificate we started to build the chain from in the first place is referred to as the ‘end entity’, and the certificates in the middle which link the ‘end entity’ to the ‘root’ are referred to as ‘intermediates’.

In summary, nearly all the decision-making by the installer is based on the fact that the chain is proven to terminate on a known or trusted certificate of which the mobile phone itself has a copy, in its own private store.

Why Chaining?

Chaining does seem remarkably complex, but its main advantage is that you can create one or more intermediate certificates and delegate signing to those, rather than sign everything with the root certificate. This means that you can leave the root certificate’s private key safe in a vault somewhere and only bring it out again if you need to generate more delegates. A key that spends much of its life in a vault is less open to compromise than one that is in use every day.

If one of the delegates does become compromised, you can revoke it and then journey down to the vault to generate a new one! Your root key, therefore, remains in a safer environment. Just imagine the enormous cost of replacing a root certificate in all those shipped mobile phones if it were to be compromised.

In some circumstances, signing may be delegated to you, the developer. You’ll be issued with a certificate and a private key so that you can test your applications. You’re probably wondering what the security implications of such a scheme are, but we’ll look at this shortly when we cover developer certificates.

Where Do the Certificates in a Chain Come From?

Clearly, there’s no way that every mobile phone can keep a database of all known certificates, but it is feasible to provision them with a limited number of root or trust anchor certificates.

As mentioned earlier, it’s essential to provide supporting certificates with anything that has been signed, that is, the end entity and any intermediates. The software installer will, however, try to resolve missing certificates by looking in its internal certificate store, and always check its private store for root certificates.

This is why the SIS file-signing tools accept a certificate chain; these entries will be built into the SIS file so that the installer can rebuild the chain and locate a root from the mobile phone.

Figure 8.2 shows the single chain of certificates constructed from those present in the SIS package and one from the mobile phone’s store.

Figure 8.2 Where Different Types of Certificates in a Chain are Found

Additional Certificate Validation – OCSP

We’ve covered validating certificates (from a tamper protection viewpoint) and building a chain. There is, however, an additional verification step available to the installer and this is a ‘revocation check’.

If you’ve ever had to wait in a shop while the merchant checks out your credit card, then you’ve been subject to this type of check. There is nothing apparently wrong with your card – your signature matches, the card’s date is valid – but a check with the card issuer might be being performed randomly, or, more likely, because you’re buying an expensive item.

A revocation check on a certificate is much the same thing. The certificate appears to be valid, but a check is made to see if, in fact, it has been revoked in the meantime. Perhaps the private key has been compromised somehow, and its issuer wishes to prevent signings based on the certificate from being treated as valid. Symbian OS uses a protocol called OCSP (Online Certificate Status Protocol) to achieve this.

Depending on how the mobile phone is configured, the installer might, therefore, connect to the network during an installation to validate certificates. Of course, it is possible for the network to be unavailable, in which case further device configuration comes into play. This controls whether the platform allows package installations to go ahead when an OCSP network service cannot be reached or is unavailable. It’s likely that most mobile phones will be configured to allow installations to finish despite transient OCSP problems. This is because the internal software install package registry will remember the validation state of the package, and an application manager – or other application – can always request revalidation at a later date.

Revalidation of an Application

(Note: this is a new feature being introduced in Symbian OS v9.2).

As well as providing information about the contents and state of a package, the SisRegistry interfaces can be used to re-initiate this OCSP check. Beware, some SisRegistry interfaces require ReadDeviceData capability and some are restricted to the software installer alone. Checking revocation may require NetworkServices, so please check the header files for details if you use these interfaces.

If you wish to check the trust status of an application, then some example code follows:

Swi::RSisRegistrySession regSession;
Swi::RSisRevocationEntry revEntry;

// connect the session
User::LeaveIfError(regSession.Connect());
CleanupClosePushL(regSession);

// open the registry entry for package by pUID
User::LeaveIfError(revEntry.Open(regSession, packageUid));
CleanupClosePushL(revEntry);

// check the current trust status
Swi::TSisTrustStatus trustStatusBefore;
trustStatusBefore = revEntry.TrustStatus();

// perform post install revocation (synchronous)
revEntry.CheckRevocationStatusL(tempUriValue);

// check the new trust status
Swi::TSisTrustStatus trustStatusAfter;
trustStatusBefore = revEntry.TrustStatus()

CleanupStack::PopAndDestroy(2, &regSession)

Trusted Roots

Certificates can contain their own metadata in the form of certificate extensions, but Symbian OS certificate stores also contain additional proprietary certificate metadata that is associated with the certificate and stored independently. This associated metadata is writable in some certificate stores but, in the case of certificates used for installation (and OCSP), there are no APIs that allow the certificates or metadata to be changed programmatically. In fact, the store employed by the software installer is part ROM-based and part file-system-based, but the file-system part can only be updated via a proprietary software installer mechanism which requires additional signing constraints to be met. This store is called the Software Install Certificate Store, or ‘swicertstore’ for short.

Even though this particular certificate store is readable through the unified certificate store interfaces, it is the only store queried by the installer during an installation or any activity relating to revocation. Certificates not in this private store are therefore ignored during the software installation process.

Installation Certificate Metadata

In general, the associated certificate metadata (see Figure 8.3) relates to which activities the certificate can be used for. Examples of usage are TLS server authentication, Java MIDlet installation or OCSP and native software installation (see below).

In addition, certificates intended for the validation of software installation are also associated with a set of capabilities, which the certificate will endorse during the software installation process.

Figure 8.3 Symbian OS Metadata which may be Associated with Certificates

The Trusted Application

Based on what we’ve covered up to now concerning certificates, chains and metadata we can define a trusted application as follows: if any of the chains present on the SIS package can be shown to correctly chain back to a certificate in the private store which has an applicability setting of ‘native software install’ then the application is deemed ‘trusted’.

It follows, therefore, that any unsigned application, self-signed application, or signed application not chaining back to one of these certificates, is ‘untrusted’.

Later in the chapter we’ll talk generally about what it means to be a trusted application or an untrusted application. We’ll see that trusted applications may be somewhat more privileged than untrusted ones when it comes to deciding what to do about upgrade clashes and other software installation features.

The Significance of Multiple Chains

Given that an application can be signed multiple times, multiple chains can now be present within a SIS file, you may be wondering whether an application can have more than one chain resolving to a software install trust anchor. If so, can the capabilities being granted to an application come from more than one trust anchor certificate?

The answer to both questions is yes, so it would be quite possible to split desired capabilities between two root certificates, thus forcing all applications requiring those capabilities to be signed twice – perhaps by two authorities. Although possible in theory, this is unlikely to be the case in practice – it could perhaps be applicable to situations involving Digital Rights Management where separate signings may be required for applications that deal with valuable digital assets that need to be deployed.

The most likely case for multiple signings is where an application, which is currently valid and signed for only one operator domain, could be signed again later to enable it for use in another domain – where the root certificates are entirely different. At least one of the chains present will, hopefully, resolve to one root certificate that will grant most – if not all – of the capabilities required by general applications.

Software Installer Capability Processing

The installer’s primary role in life (apart from copying files) is, therefore, to build chains based on SIS file signatures in order to identify the relevant root or trust anchor certificates. Once these have been identified, the metadata associated with each is used to validate a particular install. If you’d like to understand the processing logic this section will provide more details.

Software Install Basic Capability Logic

As we saw earlier, certificates can chain to form a relationship between the End Entity (EE), which was used to sign the SIS file, and a trust anchor certificate which is, we hope, on the mobile phone. We’re also now aware that more than one of these chains can be present in a SIS file since it can now be signed multiple times. With this in mind, the installer logic looks something like this:

1. Identify which binaries (EXEs and DLLs) from the SIS file are actually going to be installed. (User selections and SIS conditionals may result in only a subset requiring installation.)
2. Make a list of all the system and user capabilities required by these binaries.
3. Build the chains present in the SIS file and identify the trusted certificates in the software install certificate store that successfully terminate these chains.
4. Make a list of all the system and user capabilities associated with those trusted anchor (or root) certificates.

So, at this point we have a list of all the capabilities required by the package, and a list of all the capabilities endorsed by the certificates. The installer can now check to see if the certificates can effectively endorse the capabilities requested by the application.

5. Discard any capabilities specified as ignored by the manufacturer.
6. Ensure that the certificates specify all the remaining system capabilities required by the package. If they do not, then abort the installation.
7. Ensure that the certificates specify all the remaining user capabilities required by the package. If they do not, then the user is presented with a list of unresolved user capabilities and asked to allow or disallow them in their entirety. If the user fails to allow them, the installation is again aborted.

Nested SIS Files

As in earlier releases, SIS files can be nested within SIS files (now to a bounded depth – currently eight). Although they are nested, they are processed linearly in depth-first order. This means that each time we encounter an embedded SIS file, we open and process it before continuing on with the files in the current package. Any dependency an outer SIS package has on an inner package is automatically resolved by the installer, so there’s no need to order packages.

From a signing and capability perspective, each SIS file is processed based on its own merits. This means that there is no inheriting of signatures or capabilities from the containing (outer) package to the contained (embedded) package, or vice versa.

Developer Certificates

Earlier, we mentioned that the ability to sign packages could be delegated to you, the developer. The need for this is clear: signing (and testing) authorities just don’t have the resource to sign every version of a package that you might ordinarily produce to ensure that your latest application works on real mobile phones.

Allowing developers to sign their own applications does sound a little generous – or risky, depending on your viewpoint – but we must point out that these certificates are highly constrained in their use.

Constraints, Constraints

There’s already one significant constraint present in a certificate, and that is the validity date range. Developer certificates are likely to have a significantly reduced lifetime. Please be aware that the point at which an expired certificate becomes clearly noticeable is at install time, so watch out for developer certificate-signed SIS files which suddenly don’t install any more.

Other constraints exist within certificate extensions – parts of the standard certificate structure (defined in X.509 and RFC3280) designed to carry additional information about the certificates.

The sorts of things your developer certificate issuer can constrain you to are:

• Installations on one or more listed handsets. You won’t be able to install your SIS file on any other handsets as long as it’s signed with the developer certificate.
• Certain capabilities, that is, you won’t be able to sign for capabilities outside of an agreed set.

There are also additional constraints relating to package and binary UIDs. You may, therefore, be constrained to a set of SIDs, VIDs, or, perhaps, unprotected parts of the identifier ranges (for example, VID = 0).

As an additional safeguard the installer will also raise a UI dialog, warning the user that what they are installing has been signed in a developer context and may not necessarily be of production quality, or even trustworthy.

Identifiers, Upgrades, Removals and Special Files

Identifier Checking

UID Overload

32-bit UIDs are used for many purposes in Symbian OS, which may lead to some degree of confusion. As an introductory point, it’s worth clarifying the role of the three UIDs, which are particularly significant to the software installer:

• the SID or secure ID; allocation of SIDs is discussed in Chapter 3
• the VID or vendor ID; an additional value, which can be assigned to an EXE, also discussed in Chapter 3
• the pUID or package UID; this is a value assigned to a SIS file from the specification in the package file, and is essentially the identifier of a package, or set of files, that forms an installable unit.

To complicate things a little further, these identifier ranges are divided into protected and unprotected ranges, and your use of values from a particular range in a package (or binary within a package) may require your package to be signed.

SID Uniqueness

The most important thing for you to be aware of is that SIDs on EXEs must be unique – at least as far as a single mobile phone is concerned. This means that the installer will reject an installation if it detects an EXE with a SID that is already present on the mobile phone (and this includes OS executables as well).

SIDs on DLLs are not meaningful, and therefore the installer does not enforce uniqueness.

Identifier Ranges

We mentioned at the start of this section that identifiers have ranges. For pUIDs and SIDs, the identifier space is, in fact, divided into two:

• an unprotected range (identified by bit 31 = 1)
• a protected range (identified by bit 31 = 0)

Any identifier greater than or equal to 0x80000000 is therefore part of the ‘unprotected’ range, and any identifier less than this value is part of the protected range.

Conditions of Use

If the installer comes across a protected range pUID or an EXE with a protected range SID, then it will require that the package is ‘trusted’ (see Section 8.2.9). This means that signing programs can support the concept of owned identifiers i.e. they will only sign your application if the identifiers present in the package are actually owned by you.

In summary, therefore, if you use a pUID that is less than 0x80000000, or attempt to install an EXE with a SID less than 0x80000000, your package must be trusted to successfully install. This helps mitigate against SID hijacking, which is the act of deploying EXEs with particular SIDs with the sole purpose of preventing legitimate applications installing later – a form of denial of service attack.

VIDs and Untrusted Packages

Similarly, the installer will reject any untrusted application which installs an EXE or DLL with a non-zero vendor ID. The UI should, if this situation occurs, indicate that some form of VID violation has taken place. In summary, if you use a non-zero VID in any EXE or DLL in your package, your package must be trusted to successfully install.

Special Directories

As you will now be aware, things have been moved around in the file system a little since Symbian OS v8. For example, binaries are in /sys/bin, and resource files in /resource etc. There are two directories relevant to the software installer, which we cover here.

The Private Directory

Private directories take the form /private/<SID> where the SID corresponds to the Secure ID of the EXE (see Chapter 3). What the installer will do is collect all the SIDs of EXEs in the package which are destined for installation and make all of those /private/<SID> directories eligible for installation to the current package. For example, if a package were to install two EXEs with SIDs 0x263A7E40 and 0x123D6758 respectively, then any non-executable (that is, data) file in the package can be installed to either /private/263A7E40 or /private/123D6758, but not /private/12345678.

Basically, the installer will evaluate the private directories you’ve specified in the PKG file and make sure you’re only using the private directories appropriate to your package.

The Import Directory

The import directory for a given EXE is /private/<SID>/import. Any package can install files into the import directory of an EXE it doesn’t own – this is in order to deliver files to another package. A third-party delivering map data for a mapping application is a good example of this feature.

Using the example from the previous subsection again: if a package installs EXEs with the SIDs specified above, then it clearly cannot deploy a data file to /private/12345678, but it can deploy a file to /private/12345678/import.

There are three additional points to make clear, here. First, many people assume that /private/<SID>/import can be written to by any application using the file server. This is not the case. Import directories can only be used in the context of deploying a file into /private/<SID>/import via software install. Secondly, please note that file-overwriting rules apply – look out for these later in this text because import directories are subject to the same rules as everyone else. Finally, you can only deliver into someone’s import directory if it already exists, so if you wish your application to receive files from other installed packages you must create an import directory to permit it.

Upgrades

The process of upgrading packages has been simplified in Symbian OS v9. Essentially there are three options available to you. These are described below. (For those of you who are familiar with the PKG header types, this means that several old types – SO, SC and SY – are no longer supported.)

Standard Upgrade

The standard upgrade is essentially the delivery of the same package again. During the upgrade, the original package is actually removed and replaced with the new package. In detail:

• The standard upgrade PKG type is SA.
• The SIS file package UID (see Section 8.3.1), package name and non-localized vendor name must be identical to the original package, but a new version number is required.
• Files not re-delivered in the new SIS package are removed from the installed package.
• Should an EXE be removed and not replaced by the upgrade, the private storage directory will also be removed. If a replacement EXE is delivered, then the private storage directory remains untouched during the upgrade.

Partial Upgrade

The partial upgrade is a way of achieving a standard upgrade, but replaces only those files that need to be modified and adds any new files. For example, a developer does not need to re-deliver all the large map files with an upgrade if only the EXE requires replacing. Some additional points are:

• The partial upgrade PKG type is PU.
• The SIS file package UID, package name and non-localized vendor name must be identical to the original package, but a later version number is usually required. The same version will be permitted, but only as a means of allowing the package creator to deploy configuration changes (in a similar fashion to the old SC package type).
• Files can be replaced or added.
• The contents of the partial upgrade become part of the package itself, so it is not possible to select or remove anything other than the entire package. (The installer would certainly not be in a position to revert the package to its previous version.)

Patching or Augmenting a Package

A patch (or augmentation) is simply a set of new files that adds into the original package. Unlike the partial upgrade, the patch must not conflict with the original package by attempting to replace any existing files. The benefit of a patch is that it can subsequently be identified and uninstalled. The patch is, therefore, a convenient vehicle for delivering, for example, additional game levels to an application where it is envisaged that the user may wish to remove them after playing them.

• The patch PKG type is SP.
• The upgrade package must have the same SIS file package UID and non-localized vendor name.
• The package name should be different from the base package name.
• Files must not conflict with the original package.

Note that it is possible to install a patch to a drive other than the one that the original package was installed to. Assuming, therefore, that the package is capable of identifying that new files are present, this ability ought to extend to other drives, e.g. looking for files in D:\private\<SID> as well as C:\private\<SID>. Smart application writers could, of course, use the SisRegistry interfaces to identify if a patch is present for their pUID and determine where the user chose to install the package:

// connect to the SIS Registry and
// look for updates to the
// package ‘WoollyJumper’
RSisRegistrySession session;
User::LeaveIfError(session.Connect());
CleanupClosePushL(session);

// open the package entry
RSisRegistryEntry package;
User::LeaveIfError(package.Open(session, Tuid::Uid(KUidWoollyJumper)));
CleanupClosePushL(package);

// retrieve the list of augmentations to the package
RpointerArray<CSisRegistryPackage> augmentations;
package.AugmentationsL(augmentations);

// open the package entry for the augmentation
RSisRegistryEntry aug;
User::LeaveIfError(aug.Open(session, augmentations[0]->Uid()));
CleanupClosePushL(aug);

// retrieve the drive the augmentation was installed on
// note: only applies if a drive wasn’t specified in the SIS file.
Tchar driveLetter = aug.SelectedDriveL();

// clean up
CleanupStack::PopAndDestroy(3,&session);

Other Issues Relevant to Upgrade

Standard or partial upgrades can bring new EXEs into the package. This implies that the set of eligible private directories for subsequent upgrades can grow over time.

Package Removal

When a package is removed, the installer will always attempt to remove all the files that were originally installed. For a partially upgraded package, this includes all the original files plus any additional files added in the meantime.

If an EXE is removed, the installer will also finish the uninstall process by attempting to remove the contents of /private/<SID> and the directory itself. The installer will also clean up /private/<SID> directories on other drives (if found).

Import Directories

As a necessary part of cleaning /private/<SID>, the /private/<SID>/import directory will also be removed, so, if your package delivered files to someone else’s import directory, when your package is uninstalled the installer will ignore any missing files.

As a slight twist, please note that removal of a package which deployed files to a third-party /private/<SID>/import will result in these files being removed. If, therefore, you’re worried about files in your import directory vanishing inexplicably, then you should take ownership of them by moving them up one directory into your /private/<SID> area so that they are not removed when the ‘donating’ application is uninstalled. This all sounds a bit convoluted, but having explained it, you are free to use this behavior to your advantage depending on your specific situation.

Running Applications

The software installer may attempt to terminate applications that are running at the time of uninstall (or standard upgrade) and that relate to the package being uninstalled. This also includes programs which are run on install and uninstall and do not complete before a predetermined timeout period.

Rollback

The general policy for the system installer in a failure situation is to ‘rollback’ immediately. This means that installations revert to the point prior to the installation (the partial package is removed), and un-installations revert to the point prior to the un-installation (i.e. partial removals are restored).

Future versions of the software installer may intelligently roll-forward under some uninstallation circumstances, or perform necessary consistency operations at phone boot-time.

File Overriding Rules

Two problems are now being actively dealt with in the new platform security environment; they are:

• file overwriting (or ‘clobbering’, if you’d like a technical term for it)
• file eclipsing.

File Overwriting

As an example, suppose package A deploys a file, say C:\sys\bin\utils.dll, and package B then attempts to deploy an identically named C:\sys\bin\utils.dll.

Clearly we cannot allow packages to arbitrarily replace files in other packages, accidentally or otherwise, because we may be putting the integrity of the device or the user’s privacy at risk.

As with any general rule, there are exceptions. In this instance there are two. The first relates to the features described in Section 8.3.3: If package B is an upgrade to package A, then the replacement will be allowed. Being an upgrade, package B will have the same pUID as package A. {If you're concerned that using the same pUID sounds easy for a nefarious package creator, then refer back to the section on Identifier Checking above.)

The second feature is a safeguard against untrusted packages that deliberately deploy files known to clash with legitimate applications (a type of Denial-of-Service attack in Security circles): if package B is a trusted package and package A is untrusted, then the user can be asked to make a decision about whether to remove the untrusted file.

(Although we state that the user could be queried in this situation, you must consider what was stated in Section 8.1.3 about mobile phone configuration. Although the installer notifies the UI that such a situation has occurred, the mobile phone manufacturer might choose to resolve the issue through the installer configuration or within the UI. This means you may discover that the decision to overwrite or abort has already been made.)

If the above criteria are not met, the installation will not be able to proceed, and the UI should report a clash and indicate the blocking package.

Note that even if the file delivered by B is identical in name and content to the one previously delivered by A, the installer will still report a clash because it does not support files shared by multiple packages. A better approach is to bundle shared files in a separate (or embedded) SIS file and arrange for this to be installed if it is not already present.

File Eclipsing

An ‘eclipsed-file’ situation can occur when you have the same path and filename existing on two or more different drives. For example, if there is a file C:\resource\mydata.rsc, and a package attempts to install D:\resource\mydata.rsc, we could have an eclipsing situation if an application which made use of the existing resource file on C: started using the new file on D: instead.

This might not seem a big problem, but the situation is much more serious if the file in question is a DLL. As in other operating systems, Symbian OS operates a path-based search scheme for DLLs. This means that the loader will load one DLL of a given name and version instead of another based on where it is in the file system. The loader policy is to search for a DLL on drive Y, go backwards through the alphabet to A and then try Z – halting the search if an eligible DLL is found.

As is the situation with overwriting, we can no longer allow arbitrary packages to deploy DLLs that eclipse those in other packages or the OS.

Once again, there are two special cases. Firstly, as is the case for overwriting, if a trusted package attempts to install a file that is eclipsing one from an untrusted package the user can be asked if the file from the untrusted package should be removed.

Secondly, there is an exception to the general no eclipsing rule when OS files are deliberately eclipsed – perhaps by the manufacturer to resolve a software issue. In this case much more stringent rules come into play, based on signing – so, in general, it’s probably safe to state that if you try to eclipse an OS file your package will fail to install.

Data file eclipsing is a less serious issue than binary eclipsing, but Symbian has chosen to apply the same rules because there are areas in the OS – and possibly in applications – that employ search path rules to find files and could be duped into finding a file deliberately planted by another package.

How to Avoid It

On first reading, the above rules may appear rather Draconian until you consider that, in earlier versions of the OS, files would simply have overwritten or eclipsed each other silently – perhaps leading to some interesting application failures.

As a general rule, try to avoid both overwriting and eclipsing – allow yourself, instead, to become highly imaginative with your filenames!

SIS File Changes for Platform Security

Software Install Scripts (SIS files) are used to deliver software packages to mobile phones for installation and they can be installed from a PC, downloaded via a browser, or sent to a phone by MMS. A SIS file could be described as a smart archive – what actually gets installed from the SIS file can depend on certain rules and also on choices such as which language the user selects. The result of installing a SIS file is usually (assuming all is well) one of the following:

• A new package is installed and available on the mobile phone.
• An existing package has been upgraded or modified.
• An existing package has had some new removable components installed (e.g. game levels).

There were some significant new requirements relating to SIS files for Symbian OS v9, so Symbian also took the opportunity to redesign the basic structure of the SIS file to provide additional benefits – these are covered in the following subsection.

Although the internal format of the file has changed, Symbian has kept the extension SIS to maintain some consistency in the development process. New system recognizers associated with this format expect to see both the extension SIS and the internal format of the new files.

The most significant point to be aware of about the new SIS file is as follows:

This may appear to be a big compatibility break, but bear in mind that the binaries in an old SIS file wouldn’t be compatible with Symbian OS v9 anyway. You have probably already foreseen the next point, but we’ll mention it anyway:

SIS File Format Changes

The new SIS file format changes are summarized briefly below:

• Multiple Signatures

The new SignSIS tool allows packages to be signed multiple times. Why? Well, some parties may want to endorse or sign packages only if they have already been signed by another party. Also, some packages may require signing twice to allow the package to obtain the platform security capabilities it requires to run.

This leads to some interesting issues relating to how multiple certificate chains are handled and validated. This was covered in more detail earlier.

• Larger Package Sizes

The theoretical maximum package size has been increased significantly, well beyond the current mobile phone’s typical storage capacity – but Symbian likes to think of the future.

• Streamed Install

Large package files may become necessary, but caching them locally on the mobile phone prior to installation is wasteful. The new format (and installer) allows them to be fed to the phone incrementally over a shortlink or network connection. The API for this is covered in Appendix C.3.

• Future Proofing

The underlying structure allows us to be much more flexible with the contents and ordering of a SIS file. This also means we can avoid SIS file compatibility problems in future, even if we enhance the file contents.

Additional Compatibility Note

While we are on the subject of SIS file compatibility, it is worth recalling that the binary format was modified for Symbian OS v8.1b and v9. Since the software installer checks binaries for capability information it should come as no surprise that, if the installer encounters an old-style binary in a new SIS file, the installation will be aborted.

In general it’s a good idea to ensure that the binaries present in your package are applicable to the target environment. Look out for the following situations:

• You are packaging emulator binaries for use on a mobile phone or vice versa.
• You’re packaging binaries built for the wrong version of Symbian OS for your intended target.

In short, please ensure your binaries are correct for the target environment; this includes having the appropriate binary version for the target version of Symbian OS or the correct choice of emulator and target binaries.

Auto-Signing

It is possible that some operators or manufacturers may require that all SIS files be signed. This does not mean an end to unsigned applications in the traditional sense, so there’s no need rush off and worry about getting your application signed by a signing authority – perhaps at some cost to you. Assuming the requirement is simply that they are signed, this can include ‘self-signing’. We’ve already seen that makekeys.exe can generate self-signed certificates and keys, so all the tools are present for you to sign your SIS file with the private key associated with your self-signed certificate.

To make things more convenient, the CreateSIS script tool (createsis -h for help) will generate the required self-signed certificate and key – if you choose not to specify any alternative signing material – and will then create and sign a SIS file for you. This ephemeral private key can then be discarded if you do not plan to do any further signing with it.

Those familiar with Makekeys will notice that CreateSIS simply wraps Makekeys, MakeSIS and SignSIS into one command-line operation, and auto-generates some of the field data required along the way.

Why should signing need to be a mandatory requirement? Well, it’s simply there to provide additional mechanisms for identifying packages – the public key acts rather like a random car registration plate. Rogue packages, or malware, once identified can be found and removed more quickly, while at the same time making it difficult to ‘clone’ someone else’s public key in an attempt to have their legitimate package removed.

Auto-Execution within SIS Files

If you’re familiar with PKG file options, you might know that there are some ‘run-at-install’ and ‘run-at-uninstall’ options which have been with us for some time (see RI/RR/RB package file options in the Symbian OS Library).

; Exe that is run on installation. SWI
; will wait until Exe has completed.
;flags FILERUN, RUNINSTALL, RUNWAITEND

;Languages
&EN
;Header
#{"testrun_exe"}, (0x1000007A), 1, 2, 3,TYPE=SA

%{"LocalVendor"}
:"UniqueVendorName"
"\epoc32\release\9.1\armv5\nocapability.exe"-
"!:\sys\bin\nocapability.exe", FR, RI, RW
; GJtEFLqAAHAQRVQJOXTCPAAJECAEEAZJUyIU

After some considerable deliberation, Symbian decided to maintain support for these in Symbian OS v9, although there are some constraints to be aware of. In future releases, this auto-run ability may be restricted to trusted applications.

Limitations

In previous OS releases, you might have used auto-execution to unpack data in the SIS file, after the installation. An example of this might be a database of chess opening moves.

Now, we need to apply data-caging rules to auto-execution and some limitations become apparent:

• The auto-run EXE has its own SID – by definition.
• The auto-run EXE can see data in its own /private/<SID> directory.
• The auto-run EXE cannot see data in any other EXE’s /private/<SID> directory.

Sadly, therefore, data-caging rules limit what the auto-run EXE would have been able to do with the file system prior to Symbian OS v9. For example, an auto-run EXE cannot manipulate data files (for example, to unpack chess opening moves) in the private directory of an EXE being installed. The auto-run EXE can still, however:

• manipulate any data in public (non-data-caged) areas
• communicate with servers
• act as a server itself.

Note, also, that the auto-run EXE cannot write into the import directory of the EXE being installed – in fact, as we previously noted, only the installer can write into that directory.

Finally, auto-run executables may not be allowed to run indefinitely. For example, the installer may terminate them after a period of time to allow uninstallation to complete.

Installing to and from Removable Media

As in previous releases, it’s perfectly possible to install a SIS file to a writable, removable media card. Now, with platform security, we have introduced an additional mechanism to prevent binaries installed on removable media from being tampered with when the media is removed from the mobile phone.

The Software Installer and the OS Loader

A deal has been struck between the OS loader and the software install infrastructure. In addition to the rules that the loader observes while finding and loading binaries, there is now an additional step where the loader checks for the presence of a hash (see Appendix B) for any binary on removable media. It should be no surprise that the table of hashes is populated by the software installer.

What this means from a security perspective is that you can always insert media cards containing binaries – but they won’t be loadable by the OS loader until the installer generates the hash entry. The installer won’t do this until it has validated the installation – this is similar to a SIS-based installation.

‘Pre-Installed’ Media

It’s useful to be able to supply media cards, containing software that can run almost immediately after the card has been inserted and without the need to install from a SIS file.

However, delivering ‘pre-installed’ software on removable media proves to be an interesting challenge in a platform security environment, and the rest of this section discusses this particular issue. After all, you might imagine that there would be no specific install step required – however, this is not the case.

In fact, just about the only part of the software installation which does not take place for media card based applications is the extraction of the files from the SIS archive, and then the copying of them into their destination directories.

In-Place Installation

A pre-installed media card installation is called an ‘in-place’ installation, simply because the files are already in place when the card arrives in your hand.

The SIS file, as you’ll recall, contains lots of additional metadata such as hashes, signatures and certificates, and this information must be provided with the in-place package so that the installer can validate the package and make the application eligible to be run.

Some New Package Types

Earlier, we described the package install types (SA, SP, and PU) which are specified in the package file. At the time, we neglected to mention two additional types for pre-installed applications, which we can reveal now:

• type PA – standard pre-installed application
• type PP – pre-installed patch.

Consider the following example:

; Pre-installed package example
; Languages
&EN
; Header
#{“PreInstalled_Install”}, (0x11111209), 1, 2, 3,TYPE=PA

%{“LocalVendorName”}
:”UniqueVendorName”
“files\bigvideo.mpg”-“e:\public\bigvideo.mpg”

You will notice that the resulting SIS file is rather small. This is because the files specified are not actually included in the SIS package at all. What you have been provided with by MakeSIS is a ‘SIS Stub File’.

SIS Stub Files

SIS stub files should be placed on the media card in directory \private\10202DCE. This specific location is important because it is the private directory of the software installer’s daemon process, and it is the job of this process to identify media card insertions and bring them to the attention of the installer UI. There is no naming convention for SIS stub files at the moment other than that the file must have a SIS extension and be recognizable as a SIS file.

When the media card is inserted (or soon after), an in-place install takes place. If the certificates and the signings in the stub are valid for the data files and binaries present, and no eclipsing occurs, the installer will enable subsequent loading of the binaries by populating the loader cache accordingly.

Future Enhancements

At the time of writing it was necessary to specify, in the package file, the expected target drive for the in-place files. By the time you read this, it should be possible simply to use the wildcard ‘!’ for the drive, and the installer will validate the installation based on the drive location of the stub SIS file.

Auto-Propagated Packages

As an additional feature, if you should perform a normal installation of a SIS package to a media card, the installer will (if configured to do so) automatically generate a stub SIS file for you on the card. This means you can move your media card to another compatible phone, and an in-place installation will take place.

There are a number of limitations on the way that you should create your package if you want propagations to work. Most importantly:

• Make sure all the required files install to your media card.
• Ensure the application doesn’t modify any of the files listed as part of the package.

Deviating from these rules could mean that you have a propagated application that is either missing files or cannot be installed, because the files have been modified and no longer match the hash values stored in the SIS stub file.

Summary

In this chapter we’ve looked in some detail at how the Symbian OS v9 software installer behaves, and covered a number of the new rules which will be enforced by the installer prior to allowing packages onto the mobile phone successfully.

As pointed out in earlier, the additional security tends to manifest itself as additional restrictions, so it might be useful to recap and list a number of the most common reasons why your new Symbian OS v9 SIS file does not, or may not, install:

• Are you trying to install a pre-v9 SIS file?
• Are the binaries in your package suitable for the target environment? This includes installing emulator binaries on a mobile phone.
• Are you using the correct versions of the tools? MakeSIS, for example, should report a version of at least ‘4,0,0,1’. Tools from earlier kits will not work correctly.
• Does your operator or manufacturer demand that all applications are signed – even if they are only self-signed? If so, you’ll need to use the tools provided to generate a key and a certificate so that you can sign your own package.
• Is there any way the SIS file could have become corrupt? If so, the checksums and digital signatures might no longer match the rest of data in the package.
• Do your package’s EXEs and DLLs require any system capabilities (as defined by your manufacturer)? If so, you’ll need to have them appropriately signed by a signing authority.
• Does the certificate with which you (or your signing authority) signed your SIS file actually chain to a trust anchor in the swicertstore? (If you are developing for a handset, did you even create a swicertstore in the first place?)
• Is your package already installed? This seems obvious, but can be an occasional oversight.
• Is your package attempting to overwrite a file that was delivered by an earlier package? If so, you may wish to restructure your package or rename your files. Delivering private application data files to a /private/<SID> directory is probably the best idea. If your intention was to upgrade a package, ensure you’ve used the same pUID (and matched name and vendor fields) otherwise the installer may treat it as a new package.
• Is your package installing files which may eclipse (or be eclipsed by) a file with the same path on another drive (this includes OS files)? Again, you may wish to restructure your package or rename your files.
• Are you trying to install an EXE with a SID that is already in use? This can easily happen if your SID is in the unprotected range. You could contact your signing authority and obtain your own SID range, which can be appropriately signed for.
• Have you employed a reserved range pUID or SID? If so, your package must be signed appropriately for it to be trusted. Similarly, non-zero VIDs must also be signed-for.
• Are you using a developer certificate outside of the context that you agreed with your developer certificate issuer? Perhaps the certificate has expired, or you are trying to install the package on the wrong handset.
• Does your SIS file specify dependencies that cannot be met at the moment? For example, does another package need to be present first?