Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.
Qt & Symbian Platform Security
On Symbian, application signing and platform security make it very difficult for malicious or badly-written software to subvert the normal operation of a device, while still ensuring that the phone is easy for the user to operate and that honest developers can create powerful and compelling applications.
Application signing is used to determine which applications are trusted, while platform security allows only trusted applications to call sensitive APIs and access areas of the file system. The two most important platform security concepts are capabilities and data caging.
This article provides a simple introduction to platform security for Qt application developers.
What are capabilities?
Capabilities are access tokens that an executable must have in order call sensitive APIs or access protected areas of the file system. For example, in order to access the Internet, an application must have the NetworkServices capability. If your application calls an API without having the the associated capability then it will crash (in Symbian terms it will panic with code KERN-EXEC 46).
The most important capabilities for Qt developers are discussed below (see Capabilities (Symbian Signed) for a complete listing).
How do I add capabilities to my executable?
Capabilities are requested/declared in the executable's .pro file using the TARGET.CAPABILITY keyword (in Symbian scope). The code fragment below shows how to specify the most common "user" capabilities:
TARGET.CAPABILITY = NetworkServices LocalServices Location ReadUserData WriteUserData UserEnvironment
What capabilities should I give my application?
Qt applications that don't connect to the Internet, or use the Qt Mobility Project APIs may not need any capabilities (none are required for most of the "desktop" modules, including the GUI Framework).
Capabilities are needed in the following cases:
- NetworkServices for any operation that results in a network connection. This includes multimedia operations that use an internet based sources.
- PowerMgmt to call QProcess::kill() or QProcess::terminate() on another process (the capability is not needed to terminate the current process).
- Qt Mobility Project APIs need additional capabilities, which are documented in the Qt Mobility Quick Start. At time of writing (May 2010) these are still being confirmed!
As a general rule you should give your application the minimal set of capabilities it needs to access the functionality it uses. Giving your application more capabilities than necessary "just in case", may prevent you from using the less expensive application signing options. For example, applications that specify more than the user capabilties (NetworkServices, LocalServices, Location, ReadUserData, WriteUserData, and UserEnvironment) cannot be self-signed.
What capabilities should I give DLLs?
A DLL must have all the capabilities of the loading process:
- If the DLL is solely for the use of a single application then give it the same capabilities as the application.
- If the DLL is shared (to be loaded into many processes) then give it all the capabilities of all the processes (System DLLs have all capabilities except TCB so that they can be loaded into any process). Note that if the application is to be Symbian Signed you may not be able to get the capabilities you request - in this case consider distributing your DLL to clients as statically-linked object code.
Note also that some DLLs also require capabilities because they call protected APIs. In this case both the DLL and the loading process must be granted the capability.
What if I get a platform security error
If there is a platform security error your application will crash with KERN-EXEC 46.
Check that the application has the capabilities that grant the broad functionality it uses (e.g. NetworkServices for Internet access), and that any DLLs loaded have the same capabilities (at least) as the application.
What is data caging?
Data cages are file system directories that are protected against reading or writing (or both). Attempts to access files in these directories returns an error code. Qt applications are given their own "private directory" (a private data cage) to which they have sole access (where their resources and data files can be securely stored). The location is based on the name of the application's secure identifier (SID) or UID3 (if no SID was declared).
For example, an application with SID 0xE80B00C9 has a private directory \private\E80B00C9\. Qt applications can get the location of this directory at runtime using QDesktopServices::storageLocation() with the location QDesktopServices::StandardLocation.
Note that one implication of data caging is that file browser applications cannot read certain protected directories, including /sys/bin (all executable code), /resource/ (Symbian resource files) or \private (application private directories). To read these areas requires the (very hard to get) device manufacturer capability AllFiles; To write needs the capability TCB.
This section contains non-essential information that may be useful when working with Qt & Platform Security.
What SID and VID should I give my application?
A secure identifier (SID) is used to identify your application for platform security checks, and to provide the location of the application private directory where you can securely store application files and content. The SID value defaults to the UID3 value for the application and there is no need to set it explicitly.
A Vendor ID (VID) can be used to restrict access to shared functionality to a specific vendor but, in practice, VIDs are hardly ever used.
UID Q&As (Symbian Signed) has more information on UIDs.
Capability listing by module and API
The information in section #What capabilities should I give my application? should be sufficient to determine the capabilities needed by your application. The listing below provides additional information, summarizing the capability requirements by Qt Module and API.
- Nokia have started the work of documenting these capabilities in source but at time of writing (May 2010) this information is not yet be visible in the online documentation set.
- The Qt Mobility Quick Start documents the module level capability requirements. At time of writing (May 2010) the API level requirements have not yet been documented. These have not been listed below.
Please extend the list with missing API/capability documentation, or with links to official documentation.
|QtCore||PowerMgmt||QProcess::kill()||To kill another process. Not required to kill current process.|
|QtCore||PowerMgmt||QProcess::terminate()||To terminate another process. Not required to terminate current process|
|QtMultimedia||UserEnvironment||QAudioInput||If this is not present then either overload of start() will fail. This failure is indicated by the QAudioInput object setting its error() value to QAudio::OpenError and then emitting a stateChanged() QAudio::StoppedState signal.|
|Phonon||NetworkServices||NetworkServices needed to access media via the network. If the client process lacks this capability, operations will result in errors; This failure is indicated by a state() of Phonon::ErrorState.|
Where do I ask for more information?
The Fundamentals of Symbian C++/Platform Security article and Symbian OS Platform Security book provide useful information about platform security, including a justification of why it is needed and an explanation of the implementation and design choices that have been made.
If you want to ask general questions about Qt and platform security, please raise the query on the Symbian Signed Support, Application Packaging and Distribution and Security forum.
If you have a specific point of clarification about any statement in this article, please post a wiki comment (logged in users will see the "Leave a comment" link at the bottom of the page).
This article provides a simple introduction to platform security for Qt application developers. It covers how capabilities are used in your project and how you decide which capabilities you need in both exes and DLLs.
Capabilities are requested at build time, but are only granted to applications through an application signing program. See Qt & Application Signing for information on how to sign your Qt application for distribution and during development.
© 2010 Symbian Foundation Limited. This document is licensed under the Creative Commons Attribution-Share Alike 2.0 license. See http://creativecommons.org/licenses/by-sa/2.0/legalcode for the full terms of the license.
Note that this content was originally hosted on the Symbian Foundation developer wiki.