MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Aegis examples

This section provides Aegis manifest file examples that certain applications need for requesting credentials and capabilities. Disclaimer: Certain tokens and credentials are available only for packages coming from a trusted origin (that is, com.nokia.maemo). For more information, see Aegis manifest syntax.

Network

This is an example manifest file of an application that needs a network connection. This example requests the following credentials:

  • CAP::net_bind_service: Allows binding to TCP/UDP sockets below 1024 and to ATM VCIs below 32.
  • CAP::net_broadcast: Allows broadcasting and listening to multicast.
  • CAP::net_admin: Allows several functions, for example, interface configuration, administration of IP firewall, masquerading and accounting, setting a debug option on sockets and modification of routing tables.
  • CAP::net_raw: Allows the use of RAW and PACKET sockets.
   <aegis>
     <request>
       <credential name="CAP::net_bind_service" />
       <credential name="CAP::net_broadcast" />
       <credential name="CAP::net_admin" />
       <credential name="CAP::net_raw" />
       <for path="/usr/bin/foobar" />
     </request>
   </aegis>

Camera

This is an example manifest file of a built-in camera application. It requests the following credentials:

  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • tracker::tracker-miner-fs-access: Allows the D-Bus calls to get progress updates and use pausing and resuming.
  • GID::metadata-users: Allows the Tracker directly read metadata without using D-Bus. This credential is relevant to the main group identifier (GID).
  • GRP::metadata-users: Allows the Tracker directly read metadata without using D-Bus. This credential is relevant to the supplementary group (GRP).
  • GRP::video: Provides direct access to the video devices.
  • GRP::pulse-access: Allows access to the PulseAudio daemon. Note: The user user is already in this group, but the default policy is set meaning that each group is dropped unless you request them all. You do not need to request them explicitly, if you use add policy which is not the default behaviour. If the process is run under a user not belonging to the pulse-access group, it always needs to be requested (that is, no matter what policy is in effect). This credential is not needed from PR1.1 because Harmattan is a single-user system. The group exists in upstream so that system administrators on other operating systems can block some users from accessing audio.
  • Location: Allows access to the location information, such as GPRS data.
   <aegis>
     <request>
       <credential name="TrackerReadAccess" />
       <credential name="TrackerWriteAccess" />
       <credential name="tracker::tracker-miner-fs-access" />
       <credential name="GRP::metadata-users" />
       <credential name="GID::metadata-users" />
       <credential name="GRP::video" />
       <credential name="GRP::pulse-access" />
       <credential name="Location" />
       <for path="/usr/bin/camera-ui" />
     </request>
   </aegis>

Contacts

This example manifest file can be used with applications which need access to the contact information. It requests the following credentials:

  • Cellular: Sends an SMS or MMS and makes a CS Call.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • GRP::metadata-users: Allows the Tracker directly read metadata without using D-Bus. This credential is relevant to the main group identifier (GRP).
  • FacebookSocial: Allows to use Facebook data if there is a need for interacting with the Facebook accounts across the email client. Note: Do not use this since exporting Facebook data is not allowed. It resides here only for showing an example of the internal tokens you can reveal in the /var/lib/aegis/restok/restok.conf file.
   <aegis>
       <request>
           <credential name="Cellular" />
           <credential name="TrackerReadAccess" />
           <credential name="TrackerWriteAccess" />
           <credential name="GRP::metadata-users" />
           <credential name="FacebookSocial" />
           <for path="/usr/bin/contacts" />
       </request>
   </aegis>

Email

This is an example manifest file for an email application. It requests the following credentials:

  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • GRP::metadata-users: Allows the Tracker directly read metadata without using D-Bus. This credential is relevant to the main group identifier (GRD).
  • FacebookSocial: Allows to use Facebook data if there is a need for interacting with the Facebook accounts across the email client. Note: Do not use this since exporting Facebook data is not allowed. It resides here only for showing an example of the internal tokens you can reveal in the /var/lib/aegis/restok/restok.conf file.
   <aegis>
     <request>
       <credential name="TrackerReadAccess" />
       <credential name="TrackerWriteAccess" />
       <credential name="GRP::metadata-users" />
       <credential name="FacebookSocial" />
       <for path="/usr/bin/fenix" />
     </request>
   </aegis>

Calling

This is an example manifest file for a call application, for example, call history application. It requests the following credentials:

  • Cellular: Allows to create an SMS or MMS and to make a CS Call.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • GRP::metadata-users: Allows the Tracker directly read metadata without using D-Bus. This credential is relevant to the main group identifier (GRD).
  • FacebookSocial: Allows to use Facebook data if there is a need for interacting with the Facebook accounts across the email client. Note: Do not use this since exporting Facebook data is not allowed. It resides here only for showing an example of the internal tokens you can reveal in the /var/lib/aegis/restok/restok.conf file.
   <aegis>
     <request>
       <credential name="Cellular" />
       <credential name="TrackerReadAccess" />
       <credential name="TrackerWriteAccess" />
       <credential name="GRP::metadata-users" />
       <credential name="FacebookSocial" />
       <for path="/usr/bin/call-history" />
       <for path="applauncherd-launcher::/usr/bin/applauncherd.bin" id="" />
     </request>
   </aegis>

Maps

This is an example manifest file for a map application. It requests the following credentials:

  • Location: Access to location information
  • account-plugin-ovi::noaaccess: Allows to use the Nokia account. Note: Do not use it externally. It resides here only for showing an example of the internal tokens you can reveal in the /var/lib/aegis/restok/restok.conf file.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.

Note: By default post-install and pre-install scripts do not have any capabilities. If you need certain credentials, then you can use INSTALL context in the request to specify the desired capabilities. It concerns each maintainer script (that is, not granular for post-install). For example, if you need to run maintainer scripts under the user user, use the following example:

<aegis>
  <request>
     <credential name="Location" />
     <credential name="account-plugin-ovi::noaaccess" />
     <credential name="TrackerReadAccess" />
     <credential name="TrackerWriteAccess" />
     <for path="/usr/bin/maps" id="client"/>
  </request>
  <request context="INSTALL">
     <credential name="UID::user" />
  </request>
</aegis>

Audio

This is an example manifest file for an application that uses audio devices. It requests the following credentials:

  • GRP::pulse-access: Allows access to the PulseAudio daemon. Note: The user user is already in this group, but the default policy is set meaning that each group is dropped unless you request them all. You do not need to request them explicitly, if you use add policy which is not the default behaviour. If the process is run under a user not belonging to the pulse-access group, it always needs to be requested (that is, no matter what policy is in effect). This credential is not needed in PR1.1 because Harmattan is a single-user system. The group exists in upstream so that system administrators on other operating systems can block some users from accessing audio.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • GRP::metadata-users: Allows the Tracker to directly read metadata without using D-Bus. This credential is relevant to the main group identifier (GRD).
  • tracker::tracker-miner-fs-access: Allows the D-Bus calls to get progress updates and use pausing and resuming.
<aegis>
  <request>
    <credential name="GRP::pulse-access" />
    <credential name="TrackerReadAccess" />
    <credential name="TrackerWriteAccess" />
    <credential name="GRP::metadata-users" />
    <credential name="tracker::tracker-miner-fs-access" />
    <for path="/usr/bin/maps" />
  </request>
</aegis>

Video

This is an example manifest file for an application that uses video features. It requests the following credentials:

  • GRP::video: Provides direct access to video devices (for example, /dev/video0). You do not need it if you use a high-level API.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • TrackerWriteAccess: Allows to use Update method in Tracker queries.
  • GRP::pulse-access: Allows access to the PulseAudio daemon. Note: The user user is already in this group, but the default policy is set meaning that each group is dropped unless you request them all. You do not need to request them explicitly, if you use add policy which is not the default behaviour. If the process is run under a user not belonging to the pulse-access group, it always needs to be requested (that is, no matter what policy is in effect). This credential is not needed in PR1.1 because Harmattan is a single-user system. The group exists in upstream so that system administrators on other operating systems can block some users from accessing audio.
<aegis>
  <request>
    <credential name="GRP::video" />
    <credential name="TrackerReadAccess" />
    <credential name="TrackerWriteAccess" />
    <credential name="GRP::pulse-access" />
    <for path="/usr/bin/maps" />
  </request>
</aegis>

D-Bus

This is an example for providing and requesting credentials for D-Bus.

The server provides access and control credentials. The control credential is requested by the aegis-dbus-server application. This is usually needed for providing credentials in Nokia Store. Since there is no dependency management in Nokia store, you need to put the client and the server parts into the same package. Otherwise your application fails the Nokia Store QA process. As for third-party repositories, for example, community or personal it is not a problem as far as the given repository in question can handle dependencies. The tokens, coming from another package, are granted when the specific application is installed (for example, after the installation of the server or similar applications providing the desired token). Once something is marked unknown for an application, it does not automatically activate, even if defined later. Alternatively, <credential match="token" /> can be used instead of <credential name="token" />. If possible, avoid it because the match causes more overhead.

The debian/server.aegis file contents where the package is server:

   <aegis>
     <provide>
       <credential name="access" />
       <credential name="control" />
       <dbus name="com.maemo.Aegis.example" own="control" bus="session">
         <node name="/">
           <interface name="Aegis.Example">
             <method name="Hello">
               <annotation name="com.maemo.Aegis" value="access"/>
             </method>
             <signal name="Died">
               <annotation name="com.maemo.Aegis" value="access"/>
             </signal>
           </interface>
         </node>
       </dbus>
     </provide>
     <request>
       <credential name="control" />
       <for path="/usr/bin/aegis-dbus-server" />
     </request>
   </aegis>

This short example application does not do anything else than just request the access credential provided by the server application.

The debian/client.aegis file contents where the package is client:

   <aegis>
     <request>
       <credential name="aegis-dbus-server::access" />
       <for path="/usr/bin/aegis-dbus-client" />
     </request>
   </aegis>

Accounts

This example shows a manifest file for an application that needs credentials for a Skype account. It provides the following credentials:

  • skype-access: Credential provided to access Skype functionalities.
  • sso-encryption-token: Credential provided to access to the protected storage.

It also requests the following credentials:

  • AID::com.nokia.maemo.account-plugin-skype: The application identifier of the Skype account plugin.
  • TrackerReadAccess: Allows to use Query method in Tracker queries.
  • account-plugin-skype::skype-access: Credential requested to access Skype functionalities.
  • account-plugin-skype::sso-encryption-token: Credential requested to access to the protected storage.

Note: In policy add mode, the final credentials are the union of the requested and current credentials (the child processes also get the relevant tokens).

   <aegis>
      <provide>
         <credential name="skype-access" />
         <credential name="sso-encryption-token" />
      </provide>
      <request policy="add">
         <credential name="TrackerReadAccess" />
         <credential name="account-plugin-skype::skype-access" />
         <credential name="account-plugin-skype::sso-encryption-token" />
         <for path="/usr/lib/AccountSetup/bin/skypeplugin" />
         <for path="applauncherd-launcher::/usr/bin/applauncherd.bin" />
      </request>
      <request policy="add">
         <credential name="TrackerReadAccess" />
         <credential name="account-plugin-skype::skype-access" />
         <credential name="account-plugin-skype::sso-encryption-token" />
         <for path="telepathy-spirit::/usr/lib/telepathy/telepathy-spirit" />
      </request>
      <request policy="add">
         <credential name="account-plugin-skype::sso-encryption-token" />
         <for path="signond::/usr/bin/signond" />
      </request>
   </aegis>