doc/afm-system-daemon.md

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