doc/afm-system-daemon.md

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