If you're new to Symbian, or used to the Symbian OS v8 or earlier, then Platform Security might come as a bit of a shock to you. Well, I have good news and bad. The bad news is there are an awful lot of new rules to get your head around, the good news is most of them don't apply to you. This short guide will get you up to speed on what you need to know to get your applications deployed, and if you still have trouble then you can run your SIS file through the debugger.
In Symbian OS v8 and earlier, your executables had the run of the device. Nowhere was off limits, and you could read or write whatever you liked. With the introduction of PlatSec however, there are a few places that you can't tread. Here's how the filesystem is divided up:
/sys/:
The sys directory is where all the executables and other vital system data is stored.
It requires the TCB capability to write to, and the AllFiles capability to read from.
For all practical purposes, this means you can't access it. The exception to this rule is that
you are allowed to install executables and DLLs in to /sys/bin/. Do not attempt
to install something that is not an executable or DLL in to /sys/bin/, or attempt to install to
any other directory under /sys/, as this is not allowed.
/resource/:
The resource directory is where read-only application resources are kept.
It requires TCB to write to, but no capability to read from. For pratical purposes, this means you may install your
application's resource files here, but you may not modify them after install time.
/private/:
The private directory is more complex. It is divided up in to areas that are private to
individual executables. Your executables "owns" the private directory named after its Secure ID in hexadecimal. For example, the executable with the Secure ID of 1 owns the private directory
/private/00000001/. An executable may read or write to its own private directory freely, but
would require the AllFiles capability to read or write to any other.
At install time, applications may place files in to another application's import directory (e.g. for our executable with Secure ID of 1, that would be /private/00000001/import/.)
If you wish to place files in the private directory proper, the executable must be included in the SIS file being installed (there are also some special rules about upgrades, see later.)
All other directories are refered to as the public areas of the device. Public areas require no capabilities to read and write to.
Capabilities are divided in to three practical sets:
1. The User Grantable Capabilites, LocalSevices, UserEnvironment, NetworkServices, Location, ReadUserData, WriteUserData. These can be accessed by any application, even
if it is self signed. This set should do pretty much everything you need to do, and you should think carefully about what you really need to do if think you really need
a capability not in this set.
2. The "Signed Only" capabilities, ProtServ, ReadDeviceData, WriteDeviceData, SurroundingsDD, TrustedUI, SwEvent, PowerMgmt. These capabilities will probably be granted to
you by Symbian Signed, if you have a decent reason to have them, and you pass the test criteria.
3. The restricted capability set, NetworkControl, MultiMediaDD, AllFiles, CommDD, DiskAdmin, TCB, DRM. Good luck getting any of these, buster.
You might just about get NetworkControl, MultiMediaDD and at a strech DiskAdmin. If you regulary go to meetings with people from your favourite phone
manufacturer, you have a hope of getting some of the others. Forget about TCB, you can't have it.
You should try and confine your applications to only using capabilities from the first set. This should be fairly easy, since it covers most of the published APIs in the whole OS.
By and large, the breakdown is as follows:
All executables and DLLs must be installed in to /sys/bin/. There is no exception to this rule. Any executable not in /sys/bin can not be executed. Nothing that is not an executable or DLL will not be allowed in /sys/bin/.
Resource files for an (such as those that deal with dialog layout, and localisation and such like) will go under /resource/. You will not need to modify these after install time, so it doesn't matter that you don't have permission to write to this directory.
Application data files should be installed in to the private directory of the application that needs to use them. For example, if your executable with SID 1 had an INI file in which it stored its configuration, this might be installed to /private/00000001/myapps.ini. This kind of file will be written to after install time, so it needs to go in to a location that your executable can read and write.
The three cases above should have covered almost all the files in your package, however there are a couple of exceptional cases. Sometimes you may install files that are needed by applications you didn't write, for example the registration resource file needed by the shell to display your application's icon in the menu. Typically, these will go in to an appropriate import directory (in this example, /private/10003a3f/import/apps/myapp_reg.rsc). Rarely, you may also wish to install a file in to a public area of the device. This is generally discouraged, and should only ever be the case in exceptional circumstances.
So far, you probably know enough to create and install a Standard Application (SA) type SIS file. However, there are two other types of SIS file you may also want to deploy. These are the Patch (SP) type and the Partial Upgrade (PU) type.
The difference between these types boils down to a patch type may be uninstalled seperately from the main package, but may not overwrite any files in it. The partial upgrade may not be removed seperately, but can replace files from the package it upgrades.
The interesting property of these upgrade types is that they inherit the SIDs of executables included in the base package for purposes of accessing private directories. So, we may deploy a patch to our original example package. The base package contained an executable with SID of 1, but the patch contains no executables, just data files. However, the patch is still allowed to install files in to /private/00000001/ if it so desires.
There is, however, a caveat. You may only install a patch or a partial upgrade if it is at least as "trusted" as the base package it is upgrading. In reality, this means as well signed. So, if the base package was self signed, the upgrade may be self signed or Symbian Signed. If the base package was Symbian Signed, the upgrade must also be Symbian Signed.
Platform Security brings with it a new concept called "Eclipsing", that is installing a file with the same name as another that is already on device, but to a different drive. For example, if we had a file called z:\foo.txt, installing a file c:\foo.txt would "eclipse" this file.
Both overwriting and eclipsing are interesting because you are not allowed to do either at install time! You may not overwrite a file belonging to another package, nor eclipse it. This means you should stick to writing files in your own private directories, and choose the names of things you install in to /sys/bin or /resource with care.
There are exceptions to this rule though. You are allowed to overwrite or eclipse so-called "orphaned" files. These are files which have not been installed via a SIS file, but have been put on the device by other means (e.g. copying an MP3 to the device, etc.) If your package writes to public areas, and you accidentally wish to overwrite an orphan, the user will be prompted at install time to allow or deny this. There are also exceptions to the eclipsing rule to allow ROM upgrades to be delivered in SIS files, however these almost certainly do not concern you.
One mistake everyone makes at one time or another is attempting to install executables built for winscw (emulator) target on a real phone. For various complicated implementation reasons, this is not allowed. If you attempt this, the installer will not allow it. This is one of the things the debugger picks up on.
While it is obvious which capabilities to give an executable (the minimum set to access every API you need to use), DLLs are less obvious. This isn't helped by all the example applications using ALL-TCB. DLL capabilities have to be signed for just as much as executable capabilities.
As a rule, DLLs should be given the set of capabilities that is the union of the capability sets of all the executables that use them. If only one executable ever uses the DLL, then this is easy.
If you read about Secure IDs earlier, you'll know they have to be unique on device. You'll also know that if you don't specify the SID, then it defaults to zero. Unfortunately, this means that if you forget that you need a SID for every executable, you'll end up with SIS files containing executables with SID zero, and a baffling mystery as to why they don't install. There will always be an executable with SID zero already on device (in the ROM), so you will never be allowed to install one. Of course, the debugger warns you of this.