MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Security guide

This section provides an introduction to the MeeGo 1.2 Harmattan security and the basics of application and platform security.

For more advanced topics and more information on protecting your application, see Using Harmattan security features.

Introduction to Harmattan Security

The Harmattan security is based on the principle of least privilege. This means that applications running on the platform should have only those privileges that they need for normal execution. Many of the existing security problems combine security problems from applications and from the operating system. Here the principle of least privilege helps to minimise the options a malicious software developer has for trying to use the end user’s device for malicious purposes, or when trying to steal end user’s private data.

The purpose of the Harmattan security framework is to:

  • Protect device users from having their personal and private data and passwords stolen and used for malicious purposes.
  • Prevent malware from misusing the device and incurring costs on the user.
  • Prevent a user from accidentally breaking the device.
  • Make sure that the platform meets the requirements set by third-party software that requires a safe execution environment.

To achieve these goals, Harmattan security framework does the following:

  • Provides fine-grained configurable access control, which can restrict the set of allowed operations according to the source and identity of applications.
  • Performs extensive integrity checking to ensure the authenticity of all executable files from the boot loader and kernel to all executable content, including applications, and important configuration files and policies.
  • Protects sensitive data with encryption and signing, by using a key derived from a hardware-protected device-specific secret.
  • Protects the software deployment chain with cryptography-based source authentication and software source ranking to prevent attacks through malicious repositories.
  • Provides a device security policy, which defines what resources software from different sources can access.

This section introduces the following Harmattan security concepts:


On standard Unix systems, privileges are defined as user IDs and group IDs. Standard Linux extends this with Linux kernel capabilities that define the operations that can be performed by the application. The Harmattan platform extends this further with the concept of resource tokens. These privileges are all available in Harmattan, however, they are more fine-grained than what is normally found in Linux systems.

Unix privileges

Unix privileges builds on top of users and groups of users. Each user has a numerical user identifier (UID). In addition, the user has other associated data such as a user name, a home directory, a primary group and a password. Each group in the system has group identifier (GID) and a list of users who belong to the group.

When a user logs in to the Unix system, the information is set for the user’s shell to identify the user. All applications executed by the user have the information on the current UID, GID and other groups associated to the user (also known as supplementary groups). This information is then used by the operating system and by the system software to decide what the applications executed by the user are allowed to do.

On the file system, every file and directory has ownership information defined by the owner and the group. In addition to the ownership information, it is also defined what the owner, the group and others can do with the file, or directory. This is usually referred as Unix permissions or Unix Access Control Lists (ACLs).

Linux kernel capabilities

Linux kernel extends Unix privileges by defining a set of capabilities which define what operations within the Linux kernel the user can perform. For example, the operation of being able to define which UID is active for the application is protected by the CAP_SETUID capability in Linux kernel.

Normally it is hardcoded in Linux kernel that when the UID is set to super user (UID of 0 which usually is the user account named as root), the user is given all capabilities. When the UID is set to something other than the super user, the capabilities are reset to an empty set.

This concept of having all capabilities or nothing has generated several problems which require that some applications are executed with super user rights with all capabilities, when in reality they only require one or two. The way to execute an application with super user rights with a normal user account requires that the binary of the application has been set with SETUID bit in its Unix ACLs. When executing an application with all capabilities, it is up to the application to control how they are used and to drop extra capabilities when they are not needed anymore. The technique usually used by system programs is to change the user to a UID-specific for a system program, or to another user.

Harmattan resource tokens

When applications are executed in the system with the same UID or when there is a need for different applications to access the same resource, it is hard to implement the situation with standard means. Different services in the platform have different requirements for which applications are allowed to access their operations. If every application was able to access every service in the platform it would easily expose the user’s private data or the third party developer's private data stored in the service for malicious applications. The use of a fixed set of privileges is also problematic as every service has different needs and when users install new applications into the system, using a fixed set of privileges comes even harder to implement.

To address these problems, a concept called resource token was introduced into Harmattan. Resource token is an extension to groups in the standard Unix system. A resource token is a dynamically defined rights object added by applications installed in the Harmattan operating system. New resource tokens can be introduced into the system to coexist with the existing ones.

An example of a resource token is Location. This resource token defines that applications with the Location resource token are allowed to access location services. These location services include access to GPS coordinates and location information. Location services are considered as services that only specific applications are allowed to access in order to block compromised applications from trying to expose user's coordinates without a permission to do so.

When an application is executed in Harmattan it is bound with UID, GID, a set of supplementary groups and set of Linux kernel capabilities like in a normal Linux system. In addition to these, the application gets extra resource tokens which are configured for the application.

Resource tokens are divided into the following types:

  • Global token – A token that is defined as being common for several applications – these cannot be added by third party developers (without any prefix)
  • Package-specific token – A token that is defined by software package being installed – these can be freely added by third party developers (<package name>::<package-specific resource token name>)
  • Application identifier – Defines application identifier for the application being executed (AID::<source name>.<package name>.<custom aid>)
  • Source name – Defines from which software source the application being executed comes from (SRC::<source name>)
  • User ID – Defines which is the active UID for application (UID::<UID name>)
  • Group ID – Defines which is the active GID for application (GID::<GID name>)
  • Supplementary group – Defines the supplementary group for application (GRP::<GID name>)
  • Linux kernel capability – Defines the Linux kernel capability for the application (CAP::<capability name>)

Integrity protection

To protect the system from unauthorised modifications by malicious applications, there is a need to protect system from modifications and to verify that the system is in a valid state.

Trust to system validity comes from a trusted boot and after system has booted up, there is a need to verify that the applications in the system are still valid for execution and to protect system from harmful modifications.

Trusted boot

Trusted boot is a concept which defines that everything that is being executed during the boot is verified and that the executables are authentic. This starts by verifying that the boot loader comes from Nokia. The boot loader then verifies that the Linux kernel is valid and starts its execution. When the Linux kernel is up and running it must verify that everything executed in the device is considered to be valid.

Application protection

Application binaries in Harmattan are protected from modifications. This is done by having reference hashes for all binaries, scripts and libraries in the system. When a new application is installed, the installer first validates that the package is valid and then reads the reference hash information from the package. New reference hashes are then stored in the reference hash database in the system.

If the system does not have reference hash for an application, or the actual hash for the application binary does not match the reference value, the execution of the application is denied.

When developer mode is activated, the application protection is more relaxed to allow you to copy new binaries for testing purposes. However, you are not allowed to modify the existing binaries in the system.

File system protection

As many files in the system are owned by the root user account, it means that the root user can normally modify its own files. If there is a security breach in the system and a malicious application or a malicious user gets elevated as the super user, normally they would be able to modify system files. To prevent this there are several areas in the file system that are protected against unauthorised modifications – even if the owner of the file or directory requests modifications. The only entity in the system that is able to modify protected files and directories is the installer.

Data protection

The Harmattan platform provides several features to protect the private data of the users and third party developers.

The standard Unix file system permissions are the basic data protection feature. The permissions are an easy way to control data access. However, if multiple applications are executed with the same UID, file system permissions do not help much as all applications using the same UID have the same access rights.

When there is a need to have private application data in the file system, there are new options to protect data from modifications or from being copied to another device. The options are AegisFS and AegisCrypto. For information on AegisCrypto API, see Platform API reference.

AegisFS provides protected file system directories that can only be accessed by parties that have the needed privileges. Applications can have completely private directories, or directories shared with other applications, when they are protected by a resource token. AegisFS uses a hardware-specific secret and an associated resource token for protection.

AegisCrypto is a C++ software library that can be used by third party developers to crypt, decrypt, sign and verify data based on resource tokens. If data is being encrypted, decrypted or signed, the application must possess a resource token in order for the operation to be allowed. Data verification service is available for every application.

The key used for protection in AegisFS and AegisCrypto is derived from a hardware-specific secret and from the resource token used. The hardware-specific secret cannot be exported from the device and it cannot be changed. The secret is unique for every device. This means that any data encrypted this way cannot be copied to another device.

Software sources

In Harmattan, the software source defines the origin of the application and what privileges the application can have.

Generally, software sources can be divided into following:

  • Harmattan platform software – software that comes with the platform.
  • Nokia Store software – software that is distributed through Nokia Store.
  • Unknown origin – software with an identity that cannot be determined – usually developer’s own software before it is published in Nokia Store.

Ultimate trust is given to the Harmattan platform software. This means that all privileges are available for software delivered in device firmware.

Even if the software distributed through Nokia Store has a more limited set of privileges, different kinds of applications can still be developed.

Unknown origin has a minimal set of privileges. When developer mode is activated, this set is extended to allow software for Nokia Store to be developed.

By default, software coming from Nokia Store can be installed in the device.

Harmattan security policy

The Harmattan platform comes with the initial version of the Harmattan security policy. The policy defines what the applications can do and from where the applications can be installed. The policy also contains information about software sources and what privileges can be granted for the applications coming from them.

Harmattan security policy can be updated with the system update – meaning that the policy can be tightened or loosened depending on what is necessary. For example, if some resource token or a Linux kernel capability is abused, its use can be prevented.

Harmattan security policy is also updated when a new application is installed into the system. A new application gets acknowledged by the policy and is assigned approved rights. These rights are based on what is requested by the application in its package and what is allowed from the software source where the package is being provided.

Application security policy

Application security policy is defined by the author of the application. The policy is defined in the Aegis manifest file. When developing software with the Qt SDK, the security policy is automatically generated. However, in some cases it needs to be modified manually in order to have everything working properly.


        <credential name="Location" />
        <for path="/usr/bin/MyApp1 />

The Aegis manifest file is named manifest.aegis inside Qt Creator projects. The file located is in Qt Creator project files directory qtc_packaging/debian_harmattan/. At the start of a build, Qt Creator copies this file to debian/<package-name>.aegis. This is the location where the Debian packaging tools access the file, in the MADDE and Scratchbox environments as well.

Even if the author of the application requests a credential for the application that is available in the system, the credential is not necessarily granted. The reason for this is that for every software source there is a limit of which credentials can be granted and which cannot.

Accessing protected resources

To access a protected resource, you do not need to change your application's code. However, you do need to list the required security credentials in the Aegis manifest file. The file is optional, and it is delivered inside a Debian package. Without this file, your application cannot access the protected resource. For a list of the most common credentials, see Global tokens.

When you package your application, the Aegis manifest file generation tool inside the SDK generates the Aegis manifest file automatically for most protected resources. If your application provides protected resources for other applications, you must edit the Aegis manifest file manually.

When your application is installed, the Aegis manifest file in the application package is loaded onto the security system's internal database. When your application is launched, the credential information defined in the file is passed on to the system kernel. Harmattan services, including applications, can check credentials and make access control decisions either directly or by delegating the decisions to the D-Bus daemon.

The Aegis manifest file includes two main sections (either or both can be present):

  • requested credentials: <request>
  • provided credentials: <provide>

The manifest is stored under the name, _aegis, as the fourth file in addition to the standard Debian files (debian-binary, control.tar.gz and data.tar.gz). Files with names starting with _ (underscore) are ignored by all standard Debian tools. Both _aegis and manifest.aegis (in the Qt SDK) files are identical.

If you need to create the Aegis manifest file manually, see the instructions for the Qt SDK and for Platform SDK.

Global tokens

Global tokens are the most commonly used tokens and they are used to protect the MeeGo 1.2 Harmattan API interfaces. For example, if your application searches for image files on the Harmattan device, the application needs the TrackerReadAccess token. The token allows your application to use the query method in D-Bus. Another example is an application that updates metadata to tracker database. In this case, the application needs the TrackerWriteAccess token to use the update method in D-Bus.

Global tokens are:

  • Cellular: Allows cellular services including call and SMS for example
  • Location: Allows location services including GPS and coordinates information
  • TrackerReadAccess: Allows queries to tracker database
  • TrackerWriteAccess: Allows updates to tracker database


If your application needs location data from the GPS module, you need to have the Location token in your Aegis manifest file. When packaging your application, the Aegis manifest generator tool inside the SDK should be able to detect the required tokens and generate the needed <request> sections into the Aegis manifest file.

The Aegis manifest file generation tool recognises QML source code found from plain text .qml files, contained in Qt resource archive .rcc files, and Qt resource archives which are compiled into the application binary. The tool matches the required tokens based on module imports. The tokens that are detected from import module version statements in QML code are inherited by each application binary that uses symbols from QDeclarativeEngine or QDeclarativeView classes.

Note: The QML source code must not be named by any other suffix than .qml, and it must not be compressed or obfuscated in any manner or it cannot be processed by the Aegis manifest generator tool in the SDK.

If the Aegis manifest file with the Location token was not generated automatically for some reason, you need to create it manually. See the instructions for creating the Aegis manifest file manually for the Qt SDK and for Platform SDK.


The following Aegis manifest file includes the Location credential.

                <!-- My application from this binary package needs the Location credential -->
                <credential name="Location" />

                <for path="/usr/bin/MyApp1 />


Package-specific tokens

Package-specific tokens enable you to protect the APIs that your server provides. You can specify the package-specific tokens in the <provide> section in the Aegis manifest file.

For an example of using the <provide> section, see Providing protected resources.

Harmattan APIs that require security credentials

There are certain Harmattan APIs and Qt Quick modules that always require a token. For more information, see Harmattan APIs that require security credentials.

Developer tools for security analysis

Harmattan provides a set of tools that you can use for security analysis.

accli - You can use the Aegis crypto command line interface to see which credentials a process has, based on PID, for example. To view a help text, enter accli without any parameters. For a use case, see Harmattan security FAQ.

apscli - The Aegis protected storage command line interface is a similar command line API as accli for protected stores. You can, for example, list all protected stores in the system, list the contents of a signed store and show the contents of a file in a signed store. To view a help text, enter apscli without any parameters.

acmcli- The Aegis certificate management command line tool provides the basic operations of listing, creating and manipulating certificate stores. It is primarily used for creating application-specific certificate stores in installation scripts. To view a help text, enter acmcli without any parameters.

aegis-exec - You can use the Aegis exec command line tool to configure credentials for launched application. Use this tool if you need to drop current credentials or load Aegis session settings for a launched program. To view a help text, enter aegis-exec -h.

aegis-session - You can use the Aegis session command line tool to query session information. Session information is a collection of environment variables and resource limitations that are expected by user applications to be present in the system. Examples include D-Bus environment variables and memory limitations for applications. To view a help text, enter aegis-session without any parameters.

Further information

For more information on security, see the following links: