docs/README.md

   1 AGL framework overview
   2 ======================
   3
   4 Foreword
   5 --------
   6
   7 This document describes what we intend to do. It may happen that our
   8 current implementation and the content of this document differ.
   9
  10 In case of differences, it is assumed that this document is right
  11 and the implementation is wrong.
  12
  13
  14 Introduction
  15 ------------
  16
  17 During the first works in having the security model of Tizen
  18 integrated in AGL (Automotive Grade Linux) distribution, it became
  19 quickly obvious that the count of components specific to Tizen
  20 to integrate was huge.
  21
  22 Here is a minimal list of what was needed:
  23
  24  - platform/appfw/app-installers
  25  - platform/core/security/cert-svc
  26  - platform/core/appfw/ail
  27  - platform/core/appfw/aul-1
  28  - platform/core/appfw/libslp-db-util
  29  - platform/core/appfw/pkgmgr-info
  30  - platform/core/appfw/slp-pkgmgr
  31
  32 But this list isn't complete because many dependencies are hidden.
  33 Those hidden dependencies are including some common libraries but also many
  34 tizen specific sub-components (iniparser, bundle, dlog, libtzplatform-config,
  35 db-util, vconf-buxton, ...).
  36
  37 This is an issue because AGL is not expected to be Tizen. Taking it would
  38 either need to patch it for removing unwanted components or to take all
  39 of them.
  40
  41 However, a careful study of the core components of the security framework
  42 of Tizen showed that their dependencies to Tizen are light (and since some
  43 of our work, there is no more dependency to tizen).
  44 Those components are **cynara**, **security-manager**, **D-Bus aware of cynara**.
  45
  46 Luckily, these core security components of Tizen are provided
  47 by [meta-intel-iot-security][meta-intel], a set of yocto layers.
  48 These layers were created by Intel to isolate Tizen specific security
  49 components from the initial port of Tizen to Yocto.
  50 The 3 layers are providing components for:
  51
  52  * Implementing Smack LSM
  53  * Implementing Integrity Measurement Architecture
  54  * Implementing Tizen Security Framework
  55
  56 The figure below shows the history of these layers.
  57
  58 ![Security_model_history][Security_model_history]
  59
  60 We took the decision to use these security layers that provide the
  61 basis of the Tizen security, the security framework.
  62
  63 For the components of the application framework, built top of
  64 the security framework, instead of pulling the huge set of packages
  65 from Tizen, we decided to refit it by developing a tiny set of
  66 components that would implement the same behaviour but without all
  67 the dependencies and with minor architectural improvements for AGL.
  68
  69 These components are **afm-system-daemon** and **afm-user-daemon**.
  70 They provides infrastructure for installing, uninstalling,
  71 launching, terminating, pausing and resuming applications in
  72 a multi user secure environment.
  73
  74 A third component exists in the framework, the binder **afb-daemon**.
  75 The binder provides the easiest way to provide secured API for
  76 any tier. Currently, the use of the binder is not absolutely mandatory.
  77
  78 This documentation explains the framework created by IoT.bzh
  79 by rewriting the Tizen Application Framework. Be aware of the
  80 previous foreword.
  81
  82 <!-- pagebreak -->
  83 Overview
  84 --------
  85
  86 The figure below shows the major components of the framework
  87 and their interactions going through the following scenario:
  88 APPLICATION installs an other application and then launch it.
  89
  90 ![AppFW-APP_install_sequences][AppFW-APP_install_sequences]{style width:70%}
  91
  92 Let follow the sequence of calls:
  93
  94 1. APPLICATION calls its **binder** to install the OTHER application.
  95
  96 2. The binding **afm-main-binding** of the **binder** calls, through
  97    **D-Bus** system, the system daemon to install the OTHER application.
  98
  99 3. The system **D-Bus** checks wether APPLICATION has the permission
 100    or not to install applications by calling **CYNARA**.
 101
 102 4. The system **D-Bus** transmits the request to **afm-system-daemon**.
 103
 104    **afm-system-daemon** checks the application to install, its
 105    signatures and rights and install it.
 106
 107 5. **afm-system-daemon** calls **SECURITY-MANAGER** for fulfilling
 108    security context of the installed application.
 109
 110 6. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions
 111    for the application.
 112
 113 7. APPLICATION call its binder to start the nearly installed OTHER application.
 114
 115 8. The binding **afm-main-binding** of the **binder** calls, through
 116    **D-Bus** session, the user daemon to launch the OTHER application.
 117
 118 9. The session **D-Bus** checks wether APPLICATION has the permission
 119    or not to start an application by calling **CYNARA**.
 120
 121 10. The session **D-Bus** transmits the request to **afm-user-daemon**.
 122
 123 11. **afm-user-daemon** checks wether APPLICATION has the permission
 124     or not to start the OTHER application **CYNARA**.
 125
 126 12. **afm-user-daemon** uses **SECURITY-MANAGER** features to set
 127     the security context for the OTHER application.
 128
 129 13. **afm-user-daemon** launches the OTHER application.
 130
 131 This scenario does not cover all the features of the frameworks.
 132 Shortly because details will be revealed in the next chapters,
 133 the components are:
 134
 135 * ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules,
 136   of setting groups, and, of creating initial content of *CYNARA* rules
 137   for applications.
 138
 139 * ***CYNARA***: in charge of handling API access permissions by users and by
 140   applications.
 141
 142 * ***D-Bus***: in charge of checking security of messaging. The usual D-Bus
 143   security rules are enhanced by *CYNARA* checking rules.
 144
 145 * ***afm-system-daemon***: in charge of installing and uninstalling applications.
 146
 147 * ***afm-user-daemon***: in charge of listing applications, querying application details,
 148   starting, terminating, pausing, resuming applications and their instances
 149   for a given user context.
 150
 151 * ***afb-binder***: in charge of serving resources and features through an
 152   HTTP interface.
 153
 154 * ***afm-main-binding***: This binding allows applications to use the API
 155   of the AGL framework.
 156
 157
 158 Links between the "Security framework" and the "Application framework"
 159 ----------------------------------------------------------------------
 160
 161 The security framework refers to the security model used to ensure
 162 security and to the tools that are provided for implementing that model.
 163
 164 The security model refers to how DAC (Discretionary Access Control),
 165 MAC (Mandatory Access Control) and Capabilities are used by the system
 166 to ensure security and privacy. It also includes features of reporting
 167 using audit features and by managing logs and alerts.
 168
 169 The application framework manages the applications:
 170 installing, uninstalling, starting, pausing, listing ...
 171
 172 The application framework uses the security model/framework
 173 to ensure the security and the privacy of the applications that
 174 it manages.
 175
 176 The application framework must be compliant with the underlying
 177 security model/framework. But it should hide it to the applications.
 178
 179
 180 The security framework
 181 ----------------------
 182
 183 The implemented security model is the security model of Tizen 3.
 184 This model is described [here][tizen-secu-3].
 185
 186 The security framework then comes from Tizen 3 but through
 187 the [meta-intel].
 188 It includes: **Security-Manager**, **Cynara**
 189 and **D-Bus** compliant to Cynara.
 190
 191 Two patches are applied to the security-manager. The goal of these patches
 192 is to remove specific dependencies with Tizen packages that are not needed
 193 by AGL.
 194 None of these patches adds or removes any behaviour.
 195
 196 **In theory, the security framework/model is an implementation details
 197 that should not impact the layers above the application framework**.
 198
 199 The security framework of Tizen provides "nice lad" a valuable component to
 200 scan log files and analyse auditing. This component is still in development.
 201
 202
 203 The application framework
 204 -------------------------
 205
 206 The application framework on top of the security framework
 207 provides the components to install and uninstall applications
 208 and to run it in a secured environment.
 209
 210 The goal is to manage applications and to hide the details of
 211 the security framework to the applications.
 212
 213 For the reasons explained in introduction, we did not used the
 214 application framework of Tizen as is but used an adaptation of it.
 215
 216 The basis is kept identical: the applications are distributed
 217 in a digitally signed container that must match the specifications
 218 of widgets (web applications). This is described by the technical
 219 recommendations [widgets] and [widgets-digsig] of the W3 consortium.
 220
 221 This model allows the distribution of HTML, QML and binary applications.
 222
 223 The management of signatures of the widget packages.
 224 This basis is not meant as being rigid and it can be extended in the
 225 future to include for example incremental delivery.
 226
 227
 228
 229
 230 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 231 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 232 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 233 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 234 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 235 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 236 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 237 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 238 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 239 [cmake]:            https://cmake.org                                               "CMake"
 240 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 241 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 242 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 243 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 244
 245 [AppFW-APP_install_sequences]: pictures/AppFW-APP_install_sequences.svg
 246 [Security_model_history]: pictures/Security_model_history.svg