docs/afm-system-daemon.md

   1
   2 The afm-system-daemon
   3 =====================
   4
   5 Foreword
   6 --------
   7
   8 This document describes application framework system daemon fundamentals.
   9 FCF (Fully Conform to Specification) implementation is still under development.
  10 It may happen that current implementation somehow diverges with specifications.
  11
  12
  13 Introduction
  14 ------------
  15
  16 The daemon **afm-system-daemon** is in charge of installing
  17 applications on AGL system. Its main tasks are:
  18
  19  - installs applications and setup security framework
  20    for newly installed application.
  21
  22  - uninstall applications
  23
  24 The **afm-system-daemon** takes its orders from system
  25 instance of D-Bus.
  26
  27 The figure below summarizes the situation of **afm-system-daemon** in the system.
  28
  29     +------------------------------------------------------------+
  30     |                          User                              |
  31     |                                                            |
  32     |     +-------------------------------------------------+    |
  33     |     |                                                 |    |
  34     |     |                  afm-user-daemon                |    |
  35     |     |                                                 |    |
  36     |     +----------+----------------------+----------+----+    |
  37     |                |                      |          :         |
  38     |                |                      |          :         |
  39     :================|======================|==========:=========:
  40     |                |                      |          :         |
  41     |     +----------+----------+     +-----+-----+    :         |
  42     |     |   D-Bus   system    +-----+  CYNARA   |    :         |
  43     |     +----------+----------+     +-----+-----+    :         |
  44     |                |                      |          :         |
  45     |     +----------+---------+    +-------+----------+----+    |
  46     |     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
  47     |     +--------------------+    +-----------------------+    |
  48     |                                                            |
  49     |                          System                            |
  50     +------------------------------------------------------------+
  51
  52
  53 Starting **afm-system-daemon**
  54 ------------------------------
  55
  56 **afm-system-daemon** is launched as a **systemd** service
  57 attached to system. Normally, the service file is
  58 located at /lib/systemd/system/afm-system-daemon.service.
  59
  60 The options for launching **afm-system-daemon** are:
  61
  62     -r
  63     --root directory
  64
  65          Set the root application directory.
  66
  67          Note that the default root directory is defined
  68          to be /usr/share/afm/applications (may change).
  69
  70     -d
  71     --daemon
  72
  73          Daemonizes the process. It is not needed by sytemd.
  74
  75     -q
  76     --quiet
  77
  78          Reduces the verbosity (can be repeated).
  79
  80     -v
  81     --verbose
  82
  83          Increases the verbosity (can be repeated).
  84
  85     -h
  86     --help
  87
  88          Prints a short help.
  89
  90 The D-Bus interface
  91 -------------------
  92
  93 ### Overview of the dbus interface
  94
  95 ***afm-system-daemon*** takes its orders from the session instance
  96 of D-Bus. The use of D-Bus is great because it allows to implement
  97 discovery and signaling.
  98
  99 The **afm-system-daemon** is listening with the destination name
 100 ***org.AGL.afm.system*** at the object of path ***/org/AGL/afm/system***
 101 on the interface ***org.AGL.afm.system*** for the below detailed
 102 members ***install*** and ***uninstall***.
 103
 104 D-Bus is mainly used for signaling and discovery. Its optimized
 105 typed protocol is not used except for transmitting only one string
 106 in both directions.
 107
 108 The client and the service are using JSON serialization to
 109 exchange data.
 110
 111 The D-Bus interface is defined by:
 112
 113  * DESTINATION: **org.AGL.afm.system**
 114
 115  * PATH: **/org/AGL/afm/system**
 116
 117  * INTERFACE: **org.AGL.afm.system**
 118
 119 The signature of any member of the interface is ***string -> string***
 120 for ***JSON -> JSON***.
 121
 122 This is the normal case. In case of error, the current implementation
 123 returns a dbus error that is a string.
 124
 125 Here is an example using *dbus-send* to query data on
 126 installed applications.
 127
 128     dbus-send --session --print-reply \
 129         --dest=org.AGL.afm.system \
 130         /org/AGL/afm/system \
 131         org.AGL.afm.system.install 'string:"/tmp/appli.wgt"'
 132
 133 ### The protocol over D-Bus
 134
 135 ---
 136
 137 #### Method org.AGL.afm.system.install
 138
 139 **Description**: Install an application from a widget file.
 140
 141 When an application with the same *id* and *version* already exists. Outside of
 142 using *force=true* the application is not reinstalled.
 143
 144 Applications are installed the subdirectories of applications common directory.
 145 If *root* is specified, the application is installed under the
 146 sub-directories of the *root* defined.
 147
 148 Note that this methods is a simple accessor method of
 149 ***org.AGL.afm.system.install*** from ***afm-system-daemon***.
 150
 151 After the installation and before returning to the sender,
 152 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 153
 154 **Input**: The *path* of the widget file to install and, optionally,
 155 a flag to *force* reinstallation, and, optionally, a *root* directory.
 156
 157 Either just a string being the absolute path of the widget file:
 158
 159     "/a/path/driving/to/the/widget"
 160
 161 Or an object:
 162
 163     {
 164       "wgt": "/a/path/to/the/widget",
 165       "force": false,
 166       "root": "/a/path/to/the/root"
 167     }
 168
 169 "wgt" and "root" must be absolute paths.
 170
 171 **output**: An object with the field "added" being the string for
 172 the id of the added application.
 173
 174     {"added":"appli@x.y"}
 175
 176 ---
 177
 178 #### Method org.AGL.afm.system.uninstall
 179
 180 **Description**: Uninstall an application from its id.
 181
 182
 183 Note that this methods is a simple method accessor of
 184 ***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***.
 185
 186 After the uninstallation and before returning to the sender,
 187 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 188
 189 **Input**: the *id* of the application and optionally the application *root* path.
 190
 191 Either a string:
 192
 193     "appli@x.y"
 194
 195 Or an object:
 196
 197     {
 198       "id": "appli@x.y",
 199       "root": "/a/path/to/the/root"
 200     }
 201
 202 **output**: the value 'true'.
 203
 204 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 205 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 206 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 207 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 208 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 209 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 210 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 211 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 212 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 213 [cmake]:            https://cmake.org                                               "CMake"
 214 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 215 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 216 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 217 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 218
 219
 220