doc/afm-system-daemon.md

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