MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Harmattan security FAQ

Q: What is the syntax of @credential Doxygen tag?

The syntax is @credential <credential-value> [{description}].

The @credential tag is used to provide information on the credential, which is required in order to use a particular API. The credential-value attribute gives the name of the required credential. The optional description of the credential is strongly advised to be provided. The @credential tag is neither fully mandatory nor fully optional. If any method or class needs credentials then that information must be provided otherwise there is no need. This tag follows following rules:

  • @credential tag can exist both at class level and method level
  • There can be multiple @credential tags both at method-level and class-level
  • If there is @credential tag at class-level, then that credential is required by all the methods in the class
  • If there is @credential tag at method-level, then that credential is required by just that method

Q: I have added the required security tokens but when I start the application for testing, the access rights are not granted. What do I do?

Start the application with the full path name, for example /opt/myapp/bin/myapp instead of ./myapp in that path. The security framework only grants the tokens when you start an application with the full path name.

Q: What does the error message "Operation not permitted" mean?

In most cases, the executable fails to start because there was no correct reference hash loaded into the kernel. Possible reasons for this are:

  • The file was not installed into the target Harmattan device by using dpkg, apt, or package manager.
  • The file was modified after it was installed.
  • The file was created on the device (for example, by the package's post-install script).

There are also other reasons why a binary cannot be executed, even after all hashes have been installed. For example, the code may fail because of the "origin check" mechanism. The mechanism checks that the task's credentials are allowed for the origin of your executable or library.

When loading libraries, the error message itself can be hidden or reported in different forms depending on the application. This is more difficult to diagnose but looking at the syslog or dmesg output may give some hints. There should be a sequence of lines similar to:

...
[ 1965.710021] credp: dpkg.real: credential 0::32 not present in source SRC::9990004
[ 1965.717773] credp: dpkg.real: credential 0::33 not present in source SRC::9990004
[ 1965.725555] credp: dpkg.real: credential 3::9990001 not present in source SRC::9990004
[ 1965.733795] Aegis: credp_kcheck failed 9990004 preinst


First is the list of problematic credentials (credp lines) followed by credp_kcheck line. In this example, the code trying to execute something is dpkg.real and the code failing the origin check test is preinst (from source 9990004).

Q: What is verified by Integrity Protection subsystem?

The Integrity Protection subsystem verifies the integrity of all native executables (applications, shared libraries) and shell scripts that are started as commands (see How can I run my shell scripts in the device for an example of scripts that are not verified). It also verifies the integrity of kernel modules and some data files such as upstart files, for example /etc/init/*.conf.

Q: Where are reference hashes stored?

Reference hashes are created during Debian packaging and used to verify the integrity of files. In the Debian package the hashes are stored in the digsigsums file inside control.tar.gz. When the package is installed, this information is stored into the reference hash database /var/lib/aegis/refhashlist.

Q: How can I run my shell scripts on the device?

The best and the most secure solution is to package them into to a Debian package. This automatically adds the reference hashes for your test scripts and allows them to be started in a secure environment. You can also have an Aegis manifest file and request the credentials for your scripts as for any other executable.

It is still possible to run scripts without verification (if this is really needed) and with default credentials of the shell using either:

# sh scriptname
# sh < scriptname
# . scriptname

Note: This approach should be used for testing or debugging purposes only. Using it for other purposes exposes your application to a severe security risk, because the Integrity Protection system does not verify the integrity of scripts started this way.

Q: Does a library package need an Aegis manifest file?

Usually, a library package does not need an Aegis manifest file because libraries are not assigned any credentials in the Harmattan security model. However, there are some cases when a library does need to have an Aegis manifest file:

  • When declaring new credentials in a library package. Sometimes it can be useful to provide new credentials in a library package. This can be due to inter-package dependencies or the internal structure of the software project.
  • When using plug-in based architectures. A library, which is used as a service providing plugin for a main program, can request additional credentials to be added to the main program. This can be useful if the main program does not know in advance the plugins it loads and cannot predict the required credential set. For example, if we have a main program, mainprogram, that is located under /usr/bin/ and comes from the package mainpackage: In order to make the mainprogram able to receive the credentials from the plug-ins, the mainpackage Aegis manifest file should contain at least an empty request section, for example:
<aegis>
  <request>
    <for path="/usr/bin/mainprogram" />
  </request>
</aegis>

The package that provides a library can have the following Aegis manifest file that requests the credentials for the mainprogram:

...
  <request>
    <credential ... />
    ...
    <for path="mainpackage::/usr/bin/mainprogram" />
  </request>
...

Q: How can I request POSIX capabilities for maintainer scripts ?

By default, maintainer scripts do not have any POSIX capabilities. If your installation source allows it, you can request more credentials for your install scripts using the line <request context="INSTALL"> in the Aegis manifest file.

For example, to restart your application from a maintainer script, use the kill command. In this case, you can request CAP::kill capability for your script:

<aegis>
  <request context="INSTALL">
     <credential name="CAP::kill" />
  </request>
</aegis>

Q: How can I see which credentials a process has; or how can I query a credential possession in a script?

Use a command line tool accli to query the credentials of another process by PID.

To get current credentials of the shell, type:

accli -I

To use PID to query credentials for process:

accli -p <PID> -I
accli -p `pidof app` -I

accli also has a testing feature that can be used to verify whether current process uses a certain credential:

# Syntax:
# accli -p <PID> -t <credential>
# Will return error code 0 if credential was found; non-zero if it was not.
accli -p 123 -t CAP::net_raw && echo "Capability 'CAP::net_raw' was found!"
accli -p 123 -t mypackage::mytoken && echo "Resource token 'mypackage::mytoken' was found!"
accli -p 123 -t GRP::group && echo "Supplementary group 'group' was found!"

Q: When trying to install a package, the device complains that it cannot replace a package from "unknown origin". What does this mean?

The screen may display, for example, the following:

# dpkg -i package_name.deb
Aegis rejecting package_name.deb: package 'package_name' already installed from
'source_name' -- not replacing it from unknown origin

This means that the system already has a package named package_name that comes from source_name software source (origin). Now, an attempt has been made to install a package with the same name into the target device from a lower ranking origin (in this case unknown origin). The only way to substitute such a package is to either provide it from the same software source or from a source that has a higher rank.

Q: Is this problem/bug due to Aegis and security permissions?

If strace -v -f -p PID or strace -v -f binary_name trace of the program shows EPERM, permission denied and failures such as these, then yes.

A ptrace attach causes a permission denied error if the tracing task has less credentials than the task being traced. In normal Linux, if the traced task has more capabilities than the tracer or if it has different UID, then the tracing is denied. This check can be overridden by cap_ptrace.

Aegis uses additional credentials in the form of resource tokens and a similar check applies to them: does the task being traced have credentials that the tracing task does not have? If so, ptrace is not allowed. This check can be overridden by adding the token tcb to the Aegis manifest file.

Q: How do I see which credentials a Debian binary package file requests?

To extract _aegis from .deb, use the command ar:

ar x package.deb _aegis
cat _aegis

Q: How can I give my package-specific token to another package?

A package-specific token (pkgname::pkgname) is automatically generated by the installer component when the package requests credentials for an executable. The package token is added implicitly to the request list. As such, this package-specific token cannot be requested by other packages or granted to other packages.

To make a package token behave like a normal token, you need to explicitly provide it. The following example assumes that the name of the package is "foo":

   ...
   <provide>
     ...
     <credential name="foo" />
     ...
   </provide>

After this, it can be used in requests like any other package-defined local token.