framework.md

   1
   2
   3 AGL framework, proposal of IoT.bzh
   4 ==================================
   5
   6     version: 1
   7     Date:    29 february 2016
   8     Author:  José Bollo
   9
  10 Foreword
  11 --------
  12
  13 This document describes what we intend to do. It may happen that our
  14 current implementation and the content of this document differ.
  15
  16 In case of differences, it is assumed that this document is right
  17 and the implementation is wrong.
  18
  19
  20 Introduction
  21 ------------
  22
  23 During the first works in having the security model of Tizen
  24 integrated in AGL (Automotive Grade Linux) distribution, it became
  25 quickly obvious that the count of components specific to Tizen
  26 to integrate was huge.
  27
  28 Here is a minimal list of what was needed:
  29
  30  - platform/appfw/app-installers
  31  - platform/core/security/cert-svc
  32  - platform/core/appfw/ail
  33  - platform/core/appfw/aul-1
  34  - platform/core/appfw/libslp-db-util
  35  - platform/core/appfw/pkgmgr-info
  36  - platform/core/appfw/slp-pkgmgr
  37
  38 But this list is complete because many dependencies are hidden.
  39 Those hidden dependencies are including some common libraries but also many
  40 tizen specific sub-components (iniparser, bundle, dlog, libtzplatform-config,
  41 db-util, vconf-buxton, ...).
  42
  43 This is an issue because AGL is not expected to be Tizen. Taking it would
  44 either need to patch it for removing unwanted components or to take all
  45 of them.
  46
  47 However, a careful study of the core components of the security framework
  48 of Tizen showed that their dependencies to Tizen are light (and since some
  49 of our work, there is no more dependency to tizen).
  50 Those components are **cynara**, **security-manager**, **D-Bus aware of cynara**.
  51
  52 Luckyly, these core security components of Tizen are provided
  53 by [meta-intel-iot-security][meta-intel], a set of yocto layers.
  54 These layers were created by Intel to isolate Tizen specific security
  55 components from the initial port of Tizen to Yocto.
  56 The 3 layers are providing components for:
  57
  58  * Implementing Smack LSM
  59  * Implementing Integrity Measurement Architecture
  60  * Implementing Tizen Security Framework
  61
  62 The figure below shows the history of these layers.
  63
  64
  65                       2014         2015
  66     Tizen OBS ----------+--------------------------->
  67                          \
  68                           \
  69          Tizen Yocto       +---------+-------------->
  70                                       \
  71                                        \
  72            meta-intel-iot-security      +----------->
  73
  74 We took the decision to use these security layers that provides the
  75 basis of the Tizen security, the security framework.
  76
  77 For the components of the application framework, built top of
  78 the security framework, instead of pulling the huge set of packages
  79 from Tizen, we decided to refit it by developping a tiny set of
  80 components that would implement the same behaviour but without all
  81 the dependencies and with minor architectural improvements for AGL.
  82
  83 These components are **afm-system-daemon** and **afm-user-daemon**.
  84 They provides infrastructure for installing, uninstalling,
  85 launching, terminating, stopping and resuming applications in
  86 a multi user secure environment.
  87
  88 A third component exists in the framework, the binder **afb-daemon**.
  89 The binder provides the easiest way to provide secured API for
  90 any tier. Currently, the use of the binder is not absolutely mandatory.
  91
  92 This documentation explains the framework created by IoT.bzh
  93 by rewriting the Tizen Application Framework. Be aware of the
  94 previous foreword.
  95
  96
  97 Overview
  98 --------
  99
 100 The figure below shows the major components of the framework
 101 and their interactions going through the following scenario:
 102 APPLICATION installs an other application and then launch it.
 103
 104     +-----------------------------------------------------------------------+
 105     |                                 User                                  |
 106     |  ................................                                     |
 107     |  :   Smack isolation context    :                                     |
 108     |  :                              :      ...........................    |
 109     |  :  +-----------------------+   :      : Smack isolation context :    |
 110     |  :  |                       |   :      :                         :    |
 111     |  :  |      APPLICATION      |   :      :     OTHER application   :    |
 112     |  :  |                       |   :      :.........................:    |
 113     |  :  +-----------+-----------+   :                ^                    |
 114     |  :              |               :                |                    |
 115     |  :              |(1),(7)        :                |(13)                |
 116     |  :              |               :                |                    |
 117     |  :  +-----------v-----------+   :      +---------+---------------+    |
 118     |  :  |   binder afb-daemon   |   :      |                         |    |
 119     |  :  +-----------------------+   :      |      afm-user-daemon    |    |
 120     |  :  |    afm-main-plugin    |   :      |                         |    |
 121     |  :  +-----+--------------+--+   :      +------^-------+------+---+    |
 122     |  :........|..............|......:             |       |      :        |
 123     |           |(2)           |(8)                 |(10)   |      :        |
 124     |           |              |                    |       |      :        |
 125     |           |         +----v--------------------+---+   |      :        |
 126     |           |         |        D-Bus   session      |   |(11)  :(12)    |
 127     |           |         +-------------------------+---+   |      :        |
 128     |           |                                   |       |      :        |
 129     |           |                                   |(9)    |      :        |
 130     |           |                                   |       |      :        |
 131     :===========|===================================|=======|======:========:
 132     |           |                                   |       |      :        |
 133     |           |                               +---v-------v--+   :        |
 134     |    +------v-------------+     (3)         |              |   :        |
 135     |    |  D-Bus   system    +----------------->    CYNARA    |   :        |
 136     |    +------+-------------+                 |              |   :        |
 137     |           |                               +------^-------+   :        |
 138     |           |(4)                                   |           :        |
 139     |           |                                      |(6)        v        |
 140     |    +------v--------------+             +---------+---------------+    |
 141     |    |                     |    (5)      |                         |    |
 142     |    |  afm-system-daemon  +------------->     SECURITY-MANAGER    |    |
 143     |    |                     |             |                         |    |
 144     |    +---------------------+             +-------------------------+    |
 145     |                                                                       |
 146     |                              System                                   |
 147     +-----------------------------------------------------------------------+
 148
 149 Let follow the sequence of calls:
 150
 151 1. APPLICATION calls its **binder** to install the OTHER application.
 152
 153 2. The plugin **afm-main-plugin** of the **binder** calls, through
 154    **D-Bus** system, the system daemon to install the OTHER application.
 155
 156 3. The system **D-Bus** checks wether APPLICATION has the permission
 157    or not to install applications by calling **CYNARA**.
 158
 159 4. The system **D-Bus** transmits the request to **afm-system-daemon**.
 160
 161    **afm-system-daemon** checks the application to install, its
 162    signatures and rights and install it.
 163
 164 5. **afm-system-daemon** calls **SECURITY-MANAGER** for fullfilling
 165    security context of the installed application.
 166
 167 6. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions
 168    for the application.
 169
 170 7. APPLICATION call its binder to start the nearly installed OTHER application.
 171
 172 8. The plugin **afm-main-plugin** of the **binder** calls, through
 173    **D-Bus** session, the user daemon to launch the OTHER application.
 174
 175 9. The session **D-Bus** checks wether APPLICATION has the permission
 176    or not to start an application by calling **CYNARA**.
 177
 178 10. The session **D-Bus** transmits the request to **afm-user-daemon**.
 179
 180 11. **afm-user-daemon** checks wether APPLICATION has the permission
 181     or not to start the OTHER application **CYNARA**.
 182
 183 12. **afm-user-daemon** uses **SECURITY-MANAGER** features to set
 184     the seciruty context for the OTHER application.
 185
 186 13. **afm-user-daemon** launches the OTHER application.
 187
 188 This scenario does not cover all the features of the frameworks.
 189 Shortly because details will be revealed in the next chapters,
 190 the components are:
 191
 192 * ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules,
 193   of setting groups, and, of creating initial content of *CYNARA* rules
 194   for applications.
 195
 196 * ***CYNARA***: in charge of handling API access permissions by users and by
 197   applications.
 198
 199 * ***D-Bus***: in charge of checking security of messaging. The usual D-Bus
 200   security rules are enhanced by *CYNARA* checking rules.
 201
 202 * ***afm-system-daemon***: in charge of installing and uninstalling applications.
 203
 204 * ***afm-user-daemon***: in charge of listing applications, querying application details,
 205   starting, terminating, stopping, resuming applications and their instances
 206   for a given user context.
 207
 208 * ***afb-binder***: in charge of serving resources and features through an
 209   HTTP interface.
 210
 211 * ***afm-main-plugin***: This plugin allows applications to use the API
 212   of the AGL framework.
 213
 214
 215 Links between the "Security framework" and the "Application framework"
 216 ----------------------------------------------------------------------
 217
 218 The security framework refers to the security model used to ensure
 219 security and to the tools that are provided for implementing that model.
 220
 221 The security model refers to how DAC (Discretionnary Access Control),
 222 MAC (Mandatory Access Control) and Capabilities are used by the system
 223 to ensure security and privacy. It also includes features of reporting
 224 using audit features and by managing logs and alerts.
 225
 226 The application framework manages the applications:
 227 installing, uninstalling, starting, stopping, listing ...
 228
 229 The application framework uses the security model/framework
 230 to ensure the security and the privacy of the applications that
 231 it manages.
 232
 233 The application framework must be compliant with the underlyiong
 234 security model/framework. But it should hide it to the applications.
 235
 236
 237 The security framework
 238 ----------------------
 239
 240 The implemented security model is the security model of Tizen 3.
 241 This model is described [here][tizen-secu-3].
 242
 243 The security framework then comes from Tizen 3 but through
 244 the [meta-intel].
 245 It includes: **Security-Manager**, **Cynara**
 246 and **D-Bus** compliant to Cynara.
 247
 248 Two patches are applied to the security-manager. These patches are removing
 249 dependencies to packages specific of Tizen but that are not needed by AGL.
 250 None of these patches adds or removes any behaviour.
 251
 252 **Theoritically, the security framework/model is an implementation details
 253 that should not impact the layers above the application framework**.
 254
 255 The security framework of Tizen provides "nice lad" a valuable component to
 256 scan log files and analyse auditing. This component is still in developement.
 257
 258
 259 The application framework
 260 -------------------------
 261
 262 The application framework on top of the security framework
 263 provides the compoenents to install and uninstall applications
 264 and to run it in a secured environment.
 265
 266 The goal is to manage applications and to hide the details of
 267 the security framework to the applications.
 268
 269 For the reasons explained in introduction, we did not used the
 270 application framework of Tizen as is but used an adaptation of it.
 271
 272 The basis is kept identical: the applications are distributed
 273 in a digitally signed container that must match the specifications
 274 of widgets (web applications). This is described by the technical
 275 recomendations [widgets] and [widgets-digsig] of the W3 consortium.
 276
 277 This model allows the distribution of HTML, QML and binary applications.
 278
 279 The management of signatures of the widget packages
 280 This basis is not meant as being rigid and it can be extended in the
 281 futur to include for example incremental delivery.
 282
 283 The widgets
 284 -----------
 285
 286 ### signature of the
 287
 288 The application framework
 289
 290 This is the original part of our work here
 291
 292 ### directory where are stored applications
 293
 294 Applications can be installed in few places: on the system itself or on an extension device.
 295 For my phone, for example, it is the sd card.
 296
 297 This translates to:
 298
 299  - /usr/applications: for system wide applications
 300  - /opt/applications: for removable applications
 301
 302 In the remaining of the document, these places are writen "APPDIR".
 303
 304
 305 Organisation of directory of applications
 306 =========================================
 307
 308 The main path for applivcations are: APPDIR/PKGID/VER.
 309
 310 Where:
 311
 312  - APPDIR is as defined above
 313  - PKGID is a directory whose name is the package identifier
 314  - VER is the version of the package MAJOR.MINOR
 315
 316 This organisation has the advantage to allow several versions to leave together.
 317 This is needed for some good reasons (rolling back) and also for less good reasons (user habits).
 318
 319 Identity of installed files
 320 ---------------------------
 321
 322 All the files are installed as the user "userapp" and group "userapp".
 323 All files have rw(x) for user and r-(x) for group and others.
 324
 325 This allows any user to read the files.
 326
 327
 328 Labelling the directories of applications
 329 -----------------------------------------
 330
 331
 332 Organisation of data
 333 ====================
 334
 335 The data of a user are in its directory and are labelled using the labels of the application
 336
 337 Setting Smack rules for the application
 338 =======================================
 339
 340 For Tizen, the following rules are set by the security manager for each application.
 341
 342     System ~APP~             rwx
 343     System ~PKG~             rwxat
 344     System ~PKG~::RO         rwxat
 345     ~APP~  System            wx
 346     ~APP~  System::Shared    rxl
 347     ~APP~  System::Run       rwxat
 348     ~APP~  System::Log       rwxa
 349     ~APP~  _                 l
 350     User   ~APP~             rwx
 351     User   ~PKG~             rwxat
 352     User   ~PKG~::RO         rwxat
 353     ~APP~  User              wx
 354     ~APP~  User::Home        rxl
 355     ~APP~  User::App::Shared rwxat
 356     ~APP~  ~PKG~             rwxat
 357     ~APP~  ~PKG~::RO         rxl
 358
 359 Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application.
 360
 361 What user can run an application?
 362 =================================
 363
 364 Not all user are able to run all applications.
 365 How to manage that?
 366
 367
 368
 369 API of the framework
 370 ====================
 371
 372 Data handled
 373 ------------
 374
 375 === description of an application
 376
 377 the JSON object: APPDESC
 378
 379     {
 380       "appid":       string, the application id for the framework
 381       "id":          string, the application intrinsic id
 382       "version":     string, the version of the application
 383       "path":        string, the path of the directory of the application
 384       "width":       integer, requested width of the application
 385       "height":      integer, resqueted height of the application
 386       "name":        string, the name of the application
 387       "description": string, the description of the application
 388       "shortname":   string, the short name of the application
 389       "author":      string, the author of the application
 390     }
 391
 392
 393 The base of the path is FWKAPI = /api/fwk
 394
 395
 396 request FWKAPI/runnables
 397   -- get the list of applications
 398   => [ APPDESC... ]
 399
 400 request FWKAPI/detail?id=APPID
 401   subject to languages tuning
 402   => { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author" }
 403
 404 /*
 405 request FWKAPI/icon?id=APPID
 406   subject to languages tuning
 407   => the icon image
 408 */
 409
 410 request FWKAPI/run?id=APPID
 411   => { "status": "done/error", "data": { "runid": "RUNID" } }
 412
 413 request FWKAPI/running
 414   => [ { "id": "RUNID", "appid": "APPID", "state": ... }... ]
 415
 416 request FWKAPI/state?id=RUNID
 417   => { "id": "RUNID", "appid": "APPID", "state": ... }
 418
 419 request FWKAPI/stop?id=RUNID
 420   => { "error": "message" ou "done": "RUNID" }
 421
 422 request FWKAPI/suspend?id=RUNID
 423   => { "error": "message" ou "done": "RUNID" }
 424
 425 request FWKAPI/resume?id=RUNID
 426   => { "error": "message" ou "done": "RUNID" }
 427
 428 /*
 429 request FWKAPI/features
 430   => returns the features of the current application
 431
 432 request FWKAPI/preferences
 433   => returns the features of the current application
 434 */
 435
 436 API of the store
 437 ================
 438
 439 The base of the path is STORAPI = /api/store
 440
 441 request STORAPI/search[?q=...]
 442   subject to languages tuning
 443   => [ { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author", "icon": "url" }... ]
 444
 445 /*
 446 request STORAPI/icon?id=APPID
 447   subject to languages tuning
 448   => the icon image
 449 */
 450
 451 request STORAPI/detail?id=APPID
 452   => { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author", "icon": "url", "permissions": [ "perm"... ] }
 453
 454
 455 request STORAPI/install?id=APPID&permissions
 456   => { "transaction": "XXX", "desc"= { see above }  } or error
 457
 458
 459
 460 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 461 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 462 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 463 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 464 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 465 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 466 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 467 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 468 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 469 [cmake]:            https://cmake.org                                               "CMake"
 470 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 471 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 472 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 473 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 474
 475