diff options
| author |   José Bollo <jose.bollo@iot.bzh> | 2016-03-18 17:29:08 +0100 |
|---|---|---|
| committer | José Bollo <jose.bollo@iot.bzh> | 2016-03-18 17:29:08 +0100 |
| commit | f2bde701a9873c69897e599a7da08a0d113a86ab (patch) | |
| tree | 3357827d6a8a3f4bf7bb6eb52b1549aea4ed849c | |
| parent | 2c6fcae14552ab6e7addc82516617a135f86b5ca (diff) | |
doc: more documentation
Change-Id: I34d3442e928e310608800d3325f0547872ec21ff
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
| -rw-r--r-- | doc/afm-system-daemon.html | 240 | ||||
| -rw-r--r-- | doc/afm-system-daemon.md | 260 | ||||
| -rw-r--r-- | doc/afm-user-daemon.html | 53 | ||||
| -rw-r--r-- | doc/afm-user-daemon.md | 57 | ||||
| -rw-r--r-- | doc/application-framework.html | 296 | ||||
| -rw-r--r-- | doc/application-framework.md | 303 | ||||
| -rw-r--r-- | doc/overview.html | 14 | ||||
| -rw-r--r-- | doc/overview.md | 12 | ||||
| -rw-r--r-- | doc/security-framework.html | 2 | ||||
| -rw-r--r-- | doc/security-framework.md | 2 | ||||
| -rw-r--r-- | doc/widgets.html | 2 | ||||
| -rw-r--r-- | doc/widgets.md | 2 | ||||
| -rw-r--r-- | src/TODO | 4 |
13 files changed, 563 insertions, 684 deletions
diff --git a/doc/afm-system-daemon.html b/doc/afm-system-daemon.html index 96c6227..dac4315 100644 --- a/doc/afm-system-daemon.html +++ b/doc/afm-system-daemon.html @@ -8,72 +8,224 @@ <h1>The afm-system-daemon</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> -<a name="Organisation.of.directory.of.applications"></a> -<h1>Organisation of directory of applications</h1> +<a name="Foreword"></a> +<h2>Foreword</h2> -<p>The main path for applivcations are: APPDIR/PKGID/VER.</p> +<p>This document describes what we intend to do. It may happen that our +current implementation and the content of this document differ.</p> -<p>Where:</p> +<p>In case of differences, it is assumed that this document is right +and the implementation is wrong.</p> + +<a name="Introduction"></a> +<h2>Introduction</h2> + +<p>The daemon <strong>afm-system-daemon</strong> is in charge of installing +applications on the system. Its main tasks are:</p> <ul> -<li>APPDIR is as defined above</li> -<li>PKGID is a directory whose name is the package identifier</li> -<li>VER is the version of the package MAJOR.MINOR</li> +<li><p>installs the applications and setup the security framework +to include it</p></li> +<li><p>uninstall the applications</p></li> </ul> -<p>This organisation has the advantage to allow several versions to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits).</p> +<p>The <strong>afm-system-daemon</strong> takes its orders from the system +instance of D-Bus.</p> + +<p>The figure below summarizes the situation of the +<strong>afm-system-daemon</strong> in the system.</p> + +<pre><code>+------------------------------------------------------------+ +| User | +| | +| +-------------------------------------------------+ | +| | | | +| | afm-user-daemon | | +| | | | +| +----------+----------------------+----------+----+ | +| | | : | +| | | : | +:================|======================|==========:=========: +| | | : | +| +----------+----------+ +-----+-----+ : | +| | D-Bus system +-----+ CYNARA | : | +| +----------+----------+ +-----+-----+ : | +| | | : | +| +----------+---------+ +-------+----------+----+ | +| | afm-system-daemon +----+ SECURITY-MANAGER | | +| +--------------------+ +-----------------------+ | +| | +| System | ++------------------------------------------------------------+ +</code></pre> + +<a name="Starting..strong.afm-system-daemon..strong."></a> +<h2>Starting <strong>afm-system-daemon</strong></h2> + +<p><strong>afm-system-daemon</strong> is launched as a <strong>systemd</strong> service +attached to system. Normally, the service file is +located at /lib/systemd/system/afm-system-daemon.service.</p> + +<p>The options for launching <strong>afm-system-daemon</strong> are:</p> + +<pre><code>-r +--root directory -<a name="Identity.of.installed.files"></a> -<h2>Identity of installed files</h2> + Set the root application directory. -<p>All the files are installed as the user “userapp” and group “userapp”. -All files have rw(x) for user and r-(x) for group and others.</p> + Note that the default root directory is defined + to be /usr/share/afm/applications (may change). -<p>This allows any user to read the files.</p> +-d +--daemon -<a name="Labelling.the.directories.of.applications"></a> -<h2>Labelling the directories of applications</h2> + Daemonizes the process. It is not needed by sytemd. -<a name="Organisation.of.data"></a> -<h1>Organisation of data</h1> +-q +--quiet -<p>The data of a user are in its directory and are labelled using the labels of the application</p> + Reduces the verbosity (can be repeated). -<a name="Setting.Smack.rules.for.the.application"></a> -<h1>Setting Smack rules for the application</h1> +-v +--verbose -<p>For Tizen, the following rules are set by the security manager for each application.</p> + Increases the verbosity (can be repeated). -<pre><code>System ~APP~ rwx -System ~PKG~ rwxat -System ~PKG~::RO rwxat -~APP~ System wx -~APP~ System::Shared rxl -~APP~ System::Run rwxat -~APP~ System::Log rwxa -~APP~ _ l -User ~APP~ rwx -User ~PKG~ rwxat -User ~PKG~::RO rwxat -~APP~ User wx -~APP~ User::Home rxl -~APP~ User::App::Shared rwxat -~APP~ ~PKG~ rwxat -~APP~ ~PKG~::RO rxl +-h +--help + + Prints a short help. </code></pre> -<p>Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application.</p> +<a name="The.D-Bus.interface"></a> +<h2>The D-Bus interface</h2> + +<a name="Overview.of.the.dbus.interface"></a> +<h3>Overview of the dbus interface</h3> + +<p><strong><em>afm-system-daemon</em></strong> takes its orders from the session instance +of D-Bus. The use of D-Bus is great because it allows to implement +discovery and signaling.</p> + +<p>The <strong>afm-system-daemon</strong> is listening with the destination name +<strong><em>org.AGL.afm.system</em></strong> at the object of path <strong><em>/org/AGL/afm/system</em></strong> +on the interface <strong><em>org.AGL.afm.system</em></strong> for the below detailed +members <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p> + +<p>D-Bus is mainly used for signaling and discovery. Its optimized +typed protocol is not used except for transmitting only one string +in both directions.</p> + +<p>The client and the service are using JSON serialisation to +exchange data.</p> + +<p>The D-Bus interface is defined by:</p> + +<ul> +<li><p>DESTINATION: <strong>org.AGL.afm.system</strong></p></li> +<li><p>PATH: <strong>/org/AGL/afm/system</strong></p></li> +<li><p>INTERFACE: <strong>org.AGL.afm.system</strong></p></li> +</ul> + + +<p>The signature of any member of the interface is <strong><em>string -> string</em></strong> +for <strong><em>JSON -> JSON</em></strong>.</p> + +<p>This is the normal case. In case of error, the current implmentation +returns a dbus error that is a string.</p> + +<p>Here is an example that use <em>dbus-send</em> to query data on +installed applications.</p> + +<pre><code>dbus-send --session --print-reply \ + --dest=org.AGL.afm.system \ + /org/AGL/afm/system \ + org.AGL.afm.system.install 'string:"/tmp/appli.wgt"' +</code></pre> + +<a name="The.protocol.over.D-Bus"></a> +<h3>The protocol over D-Bus</h3> + +<hr /> + +<a name="Method.org.AGL.afm.system.install"></a> +<h4>Method org.AGL.afm.system.install</h4> + +<p><strong>Description</strong>: Install an application from its widget file.</p> -<a name="What.user.can.run.an.application."></a> -<h1>What user can run an application?</h1> +<p>If an application of the same <em>id</em> and <em>version</em> exists, it is not +reinstalled except if <em>force=true</em>.</p> + +<p>Applications are installed in the subdirectories of the common directory +of applications. +If <em>root</em> is specified, the application is installed under the +sub-directories of the <em>root</em> defined.</p> + +<p>Note that this methods is a simple accessor to the method +<strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> + +<p>After the installation and before returning to the sender, +<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> + +<p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly, +a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p> + +<p>Either just a string being the absolute path of the widget file:</p> + +<pre><code>"/a/path/driving/to/the/widget" +</code></pre> + +<p>Or an object:</p> + +<pre><code>{ + "wgt": "/a/path/to/the/widget", + "force": false, + "root": "/a/path/to/the/root" +} +</code></pre> + +<p>“wgt” and “root” must be absolute paths.</p> + +<p><strong>output</strong>: An object with the field “added” being the string for +the id of the added application.</p> + +<pre><code>{"added":"appli@x.y"} +</code></pre> + +<hr /> + +<a name="Method.org.AGL.afm.system.uninstall"></a> +<h4>Method org.AGL.afm.system.uninstall</h4> + +<p><strong>Description</strong>: Uninstall an application from its id.</p> + +<p>Note that this methods is a simple accessor to the method +<strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> + +<p>After the uninstallation and before returning to the sender, +<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> + +<p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to +<em>root</em> of the application.</p> + +<p>Either a string:</p> + +<pre><code>"appli@x.y" +</code></pre> + +<p>Or an object:</p> + +<pre><code>{ + "id": "appli@x.y", + "root": "/a/path/to/the/root" +} +</code></pre> -<p>Not all user are able to run all applications. -How to manage that?</p> +<p><strong>output</strong>: the value ‘true’.</p> </body> </html> diff --git a/doc/afm-system-daemon.md b/doc/afm-system-daemon.md index 980f634..9a22add 100644 --- a/doc/afm-system-daemon.md +++ b/doc/afm-system-daemon.md @@ -3,71 +3,243 @@ The afm-system-daemon ===================== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo -Organisation of directory of applications -========================================= -The main path for applivcations are: APPDIR/PKGID/VER. +Foreword +-------- + +This document describes what we intend to do. It may happen that our +current implementation and the content of this document differ. + +In case of differences, it is assumed that this document is right +and the implementation is wrong. + + +Introduction +------------ + +The daemon **afm-system-daemon** is in charge of installing +applications on the system. Its main tasks are: + + - installs the applications and setup the security framework + to include it + + - uninstall the applications + +The **afm-system-daemon** takes its orders from the system +instance of D-Bus. + +The figure below summarizes the situation of the +**afm-system-daemon** in the system. + + +------------------------------------------------------------+ + | User | + | | + | +-------------------------------------------------+ | + | | | | + | | afm-user-daemon | | + | | | | + | +----------+----------------------+----------+----+ | + | | | : | + | | | : | + :================|======================|==========:=========: + | | | : | + | +----------+----------+ +-----+-----+ : | + | | D-Bus system +-----+ CYNARA | : | + | +----------+----------+ +-----+-----+ : | + | | | : | + | +----------+---------+ +-------+----------+----+ | + | | afm-system-daemon +----+ SECURITY-MANAGER | | + | +--------------------+ +-----------------------+ | + | | + | System | + +------------------------------------------------------------+ + + +Starting **afm-system-daemon** +------------------------------ + +**afm-system-daemon** is launched as a **systemd** service +attached to system. Normally, the service file is +located at /lib/systemd/system/afm-system-daemon.service. + +The options for launching **afm-system-daemon** are: + + -r + --root directory + + Set the root application directory. + + Note that the default root directory is defined + to be /usr/share/afm/applications (may change). + + -d + --daemon + + Daemonizes the process. It is not needed by sytemd. + + -q + --quiet + + Reduces the verbosity (can be repeated). + + -v + --verbose + + Increases the verbosity (can be repeated). + + -h + --help + + Prints a short help. + +The D-Bus interface +------------------- + +### Overview of the dbus interface + +***afm-system-daemon*** takes its orders from the session instance +of D-Bus. The use of D-Bus is great because it allows to implement +discovery and signaling. + +The **afm-system-daemon** is listening with the destination name +***org.AGL.afm.system*** at the object of path ***/org/AGL/afm/system*** +on the interface ***org.AGL.afm.system*** for the below detailed +members ***install*** and ***uninstall***. + +D-Bus is mainly used for signaling and discovery. Its optimized +typed protocol is not used except for transmitting only one string +in both directions. + +The client and the service are using JSON serialisation to +exchange data. + +The D-Bus interface is defined by: + + * DESTINATION: **org.AGL.afm.system** + + * PATH: **/org/AGL/afm/system** + + * INTERFACE: **org.AGL.afm.system** + +The signature of any member of the interface is ***string -> string*** +for ***JSON -> JSON***. + +This is the normal case. In case of error, the current implmentation +returns a dbus error that is a string. + +Here is an example that use *dbus-send* to query data on +installed applications. + + dbus-send --session --print-reply \ + --dest=org.AGL.afm.system \ + /org/AGL/afm/system \ + org.AGL.afm.system.install 'string:"/tmp/appli.wgt"' + +### The protocol over D-Bus + +--- + +#### Method org.AGL.afm.system.install + +**Description**: Install an application from its widget file. + +If an application of the same *id* and *version* exists, it is not +reinstalled except if *force=true*. + +Applications are installed in the subdirectories of the common directory +of applications. +If *root* is specified, the application is installed under the +sub-directories of the *root* defined. + +Note that this methods is a simple accessor to the method +***org.AGL.afm.system.install*** of ***afm-system-daemon***. + +After the installation and before returning to the sender, +***afm-system-daemon*** sends the signal ***org.AGL.afm.system.changed***. + +**Input**: The *path* of the widget file to install and, optionaly, +a flag to *force* reinstallation, and, optionaly, a *root* directory. + +Either just a string being the absolute path of the widget file: + + "/a/path/driving/to/the/widget" + +Or an object: + + { + "wgt": "/a/path/to/the/widget", + "force": false, + "root": "/a/path/to/the/root" + } + +"wgt" and "root" must be absolute paths. + +**output**: An object with the field "added" being the string for +the id of the added application. + + {"added":"appli@x.y"} + +--- + +#### Method org.AGL.afm.system.uninstall + +**Description**: Uninstall an application from its id. + + +Note that this methods is a simple accessor to the method +***org.AGL.afm.system.uninstall*** of ***afm-system-daemon***. + +After the uninstallation and before returning to the sender, +***afm-system-daemon*** sends the signal ***org.AGL.afm.system.changed***. + +**Input**: the *id* of the application and, otpionaly, the path to +*root* of the application. + +Either a string: + + "appli@x.y" + +Or an object: + + { + "id": "appli@x.y", + "root": "/a/path/to/the/root" + } + +**output**: the value 'true'. + + + + + + + + + + + + -Where: - - APPDIR is as defined above - - PKGID is a directory whose name is the package identifier - - VER is the version of the package MAJOR.MINOR -This organisation has the advantage to allow several versions to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits). -Identity of installed files ---------------------------- -All the files are installed as the user "userapp" and group "userapp". -All files have rw(x) for user and r-(x) for group and others. -This allows any user to read the files. -Labelling the directories of applications ------------------------------------------ -Organisation of data -==================== -The data of a user are in its directory and are labelled using the labels of the application -Setting Smack rules for the application -======================================= -For Tizen, the following rules are set by the security manager for each application. - System ~APP~ rwx - System ~PKG~ rwxat - System ~PKG~::RO rwxat - ~APP~ System wx - ~APP~ System::Shared rxl - ~APP~ System::Run rwxat - ~APP~ System::Log rwxa - ~APP~ _ l - User ~APP~ rwx - User ~PKG~ rwxat - User ~PKG~::RO rwxat - ~APP~ User wx - ~APP~ User::Home rxl - ~APP~ User::App::Shared rwxat - ~APP~ ~PKG~ rwxat - ~APP~ ~PKG~::RO rxl -Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application. -What user can run an application? -================================= -Not all user are able to run all applications. -How to manage that? diff --git a/doc/afm-user-daemon.html b/doc/afm-user-daemon.html index cc9cb12..29001bb 100644 --- a/doc/afm-user-daemon.html +++ b/doc/afm-user-daemon.html @@ -8,7 +8,7 @@ <h1>The afm-user-daemon</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> @@ -152,6 +152,8 @@ located at /usr/lib/systemd/user/afm-user-daemon.service.</p> Includes the given application directory to the database base of applications. + Can be repeated. + -r --root directory @@ -162,6 +164,8 @@ located at /usr/lib/systemd/user/afm-user-daemon.service.</p> applications is always added. It is defined to be /usr/share/afm/applications (may change). + Can be repeated. + -m --mode (local|remote) @@ -601,7 +605,7 @@ a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directo <p><strong>output</strong>: An object with the field “added” being the string for the id of the added application.</p> -<pre><code>{"added":"appli@x.y" } +<pre><code>{"added":"appli@x.y"} </code></pre> <hr /> @@ -728,50 +732,5 @@ or “stopped”).</p> <p><strong>output</strong>: An array of states, one per running instance, as returned by the methodd <strong><em>org.AGL.afm.user.state</em></strong>.</p> - -<a name="The.afb.plugin"></a> -<h2>The afb plugin</h2> - -<p>The base of the path is FWKAPI = /api/fwk</p> - -<p>request FWKAPI/runnables - – get the list of applications - => [ APPDESC… ]</p> - -<p>request FWKAPI/detail?id=APPID - subject to languages tuning - => { “id”: “APPID”, “name”: “name”, “description”: “description”, “license”: “license”, “author”: “author” }</p> - -<p>/<em> -request FWKAPI/icon?id=APPID - subject to languages tuning - => the icon image -</em>/</p> - -<p>request FWKAPI/run?id=APPID - => { “status”: “done/error”, “data”: { “runid”: “RUNID” } }</p> - -<p>request FWKAPI/running - => [ { “id”: “RUNID”, “appid”: “APPID”, “state”: … }… ]</p> - -<p>request FWKAPI/state?id=RUNID - => { “id”: “RUNID”, “appid”: “APPID”, “state”: … }</p> - -<p>request FWKAPI/stop?id=RUNID - => { “error”: “message” ou “done”: “RUNID” }</p> - -<p>request FWKAPI/suspend?id=RUNID - => { “error”: “message” ou “done”: “RUNID” }</p> - -<p>request FWKAPI/resume?id=RUNID - => { “error”: “message” ou “done”: “RUNID” }</p> - -<p>/* -request FWKAPI/features - => returns the features of the current application</p> - -<p>request FWKAPI/preferences - => returns the features of the current application -*/</p> </body> </html> diff --git a/doc/afm-user-daemon.md b/doc/afm-user-daemon.md index 107b399..b7b6636 100644 --- a/doc/afm-user-daemon.md +++ b/doc/afm-user-daemon.md @@ -3,7 +3,7 @@ The afm-user-daemon =================== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo @@ -146,6 +146,8 @@ The options for launching **afm-user-daemon** are: Includes the given application directory to the database base of applications. + Can be repeated. + -r --root directory @@ -156,6 +158,8 @@ The options for launching **afm-user-daemon** are: applications is always added. It is defined to be /usr/share/afm/applications (may change). + Can be repeated. + -m --mode (local|remote) @@ -591,7 +595,7 @@ Or an object: **output**: An object with the field "added" being the string for the id of the added application. - {"added":"appli@x.y" } + {"added":"appli@x.y"} --- @@ -707,52 +711,3 @@ Example of returned state: **output**: An array of states, one per running instance, as returned by the methodd ***org.AGL.afm.user.state***. - -The afb plugin --------------- - -The base of the path is FWKAPI = /api/fwk - - -request FWKAPI/runnables - -- get the list of applications - => [ APPDESC... ] - -request FWKAPI/detail?id=APPID - subject to languages tuning - => { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author" } - -/* -request FWKAPI/icon?id=APPID - subject to languages tuning - => the icon image -*/ - -request FWKAPI/run?id=APPID - => { "status": "done/error", "data": { "runid": "RUNID" } } - -request FWKAPI/running - => [ { "id": "RUNID", "appid": "APPID", "state": ... }... ] - -request FWKAPI/state?id=RUNID - => { "id": "RUNID", "appid": "APPID", "state": ... } - -request FWKAPI/stop?id=RUNID - => { "error": "message" ou "done": "RUNID" } - -request FWKAPI/suspend?id=RUNID - => { "error": "message" ou "done": "RUNID" } - -request FWKAPI/resume?id=RUNID - => { "error": "message" ou "done": "RUNID" } - -/* -request FWKAPI/features - => returns the features of the current application - -request FWKAPI/preferences - => returns the features of the current application -*/ - - - diff --git a/doc/application-framework.html b/doc/application-framework.html index f77ee48..3b62cb7 100644 --- a/doc/application-framework.html +++ b/doc/application-framework.html @@ -8,7 +8,7 @@ <h1>Application framework</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> @@ -21,239 +21,9 @@ current implementation and the content of this document differ.</p> <p>In case of differences, it is assumed that this document is right and the implementation is wrong.</p> -<a name="Introduction"></a> -<h2>Introduction</h2> - -<p>During the first works in having the security model of Tizen -integrated in AGL (Automotive Grade Linux) distribution, it became -quickly obvious that the count of components specific to Tizen -to integrate was huge.</p> - -<p>Here is a minimal list of what was needed:</p> - -<ul> -<li>platform/appfw/app-installers</li> -<li>platform/core/security/cert-svc</li> -<li>platform/core/appfw/ail</li> -<li>platform/core/appfw/aul-1</li> -<li>platform/core/appfw/libslp-db-util</li> -<li>platform/core/appfw/pkgmgr-info</li> -<li>platform/core/appfw/slp-pkgmgr</li> -</ul> - - -<p>But this list is complete because many dependencies are hidden. -Those hidden dependencies are including some common libraries but also many -tizen specific sub-components (iniparser, bundle, dlog, libtzplatform-config, -db-util, vconf-buxton, …).</p> - -<p>This is an issue because AGL is not expected to be Tizen. Taking it would -either need to patch it for removing unwanted components or to take all -of them.</p> - -<p>However, a careful study of the core components of the security framework -of Tizen showed that their dependencies to Tizen are light (and since some -of our work, there is no more dependency to tizen). -Those components are <strong>cynara</strong>, <strong>security-manager</strong>, <strong>D-Bus aware of cynara</strong>.</p> - -<p>Luckyly, these core security components of Tizen are provided -by <a href="https://github.com/01org/meta-intel-iot-security" title="A collection of layers providing security technologies">meta-intel-iot-security</a>, a set of yocto layers. -These layers were created by Intel to isolate Tizen specific security -components from the initial port of Tizen to Yocto. -The 3 layers are providing components for:</p> - -<ul> -<li>Implementing Smack LSM</li> -<li>Implementing Integrity Measurement Architecture</li> -<li>Implementing Tizen Security Framework</li> -</ul> - - -<p>The figure below shows the history of these layers.</p> - -<pre><code> 2014 2015 -Tizen OBS ----------+---------------------------> - \ - \ - Tizen Yocto +---------+--------------> - \ - \ - meta-intel-iot-security +-----------> -</code></pre> - -<p>We took the decision to use these security layers that provides the -basis of the Tizen security, the security framework.</p> - -<p>For the components of the application framework, built top of -the security framework, instead of pulling the huge set of packages -from Tizen, we decided to refit it by developping a tiny set of -components that would implement the same behaviour but without all -the dependencies and with minor architectural improvements for AGL.</p> - -<p>These components are <strong>afm-system-daemon</strong> and <strong>afm-user-daemon</strong>. -They provides infrastructure for installing, uninstalling, -launching, terminating, stopping and resuming applications in -a multi user secure environment.</p> - -<p>A third component exists in the framework, the binder <strong>afb-daemon</strong>. -The binder provides the easiest way to provide secured API for -any tier. Currently, the use of the binder is not absolutely mandatory.</p> - -<p>This documentation explains the framework created by IoT.bzh -by rewriting the Tizen Application Framework. Be aware of the -previous foreword.</p> - <a name="Overview"></a> <h2>Overview</h2> -<p>The figure below shows the major components of the framework -and their interactions going through the following scenario: -APPLICATION installs an other application and then launch it.</p> - -<pre><code>+-----------------------------------------------------------------------+ -| User | -| ................................ | -| : Smack isolation context : | -| : : ........................... | -| : +-----------------------+ : : Smack isolation context : | -| : | | : : : | -| : | APPLICATION | : : OTHER application : | -| : | | : :.........................: | -| : +-----------+-----------+ : ^ | -| : | : | | -| : |(1),(7) : |(13) | -| : | : | | -| : +-----------v-----------+ : +---------+---------------+ | -| : | binder afb-daemon | : | | | -| : +-----------------------+ : | afm-user-daemon | | -| : | afm-main-plugin | : | | | -| : +-----+--------------+--+ : +------^-------+------+---+ | -| :........|..............|......: | | : | -| |(2) |(8) |(10) | : | -| | | | | : | -| | +----v--------------------+---+ | : | -| | | D-Bus session | |(11) :(12) | -| | +-------------------------+---+ | : | -| | | | : | -| | |(9) | : | -| | | | : | -:===========|===================================|=======|======:========: -| | | | : | -| | +---v-------v--+ : | -| +------v-------------+ (3) | | : | -| | D-Bus system +-----------------> CYNARA | : | -| +------+-------------+ | | : | -| | +------^-------+ : | -| |(4) | : | -| | |(6) v | -| +------v--------------+ +---------+---------------+ | -| | | (5) | | | -| | afm-system-daemon +-------------> SECURITY-MANAGER | | -| | | | | | -| +---------------------+ +-------------------------+ | -| | -| System | -+-----------------------------------------------------------------------+ -</code></pre> - -<p>Let follow the sequence of calls:</p> - -<ol> -<li><p>APPLICATION calls its <strong>binder</strong> to install the OTHER application.</p></li> -<li><p>The plugin <strong>afm-main-plugin</strong> of the <strong>binder</strong> calls, through -<strong>D-Bus</strong> system, the system daemon to install the OTHER application.</p></li> -<li><p>The system <strong>D-Bus</strong> checks wether APPLICATION has the permission -or not to install applications by calling <strong>CYNARA</strong>.</p></li> -<li><p>The system <strong>D-Bus</strong> transmits the request to <strong>afm-system-daemon</strong>.</p> - -<p><strong>afm-system-daemon</strong> checks the application to install, its -signatures and rights and install it.</p></li> -<li><p><strong>afm-system-daemon</strong> calls <strong>SECURITY-MANAGER</strong> for fullfilling -security context of the installed application.</p></li> -<li><p><strong>SECURITY-MANAGER</strong> calls <strong>CYNARA</strong> to install initial permissions -for the application.</p></li> -<li><p>APPLICATION call its binder to start the nearly installed OTHER application.</p></li> -<li><p>The plugin <strong>afm-main-plugin</strong> of the <strong>binder</strong> calls, through -<strong>D-Bus</strong> session, the user daemon to launch the OTHER application.</p></li> -<li><p>The session <strong>D-Bus</strong> checks wether APPLICATION has the permission -or not to start an application by calling <strong>CYNARA</strong>.</p></li> -<li><p>The session <strong>D-Bus</strong> transmits the request to <strong>afm-user-daemon</strong>.</p></li> -<li><p><strong>afm-user-daemon</strong> checks wether APPLICATION has the permission -or not to start the OTHER application <strong>CYNARA</strong>.</p></li> -<li><p><strong>afm-user-daemon</strong> uses <strong>SECURITY-MANAGER</strong> features to set -the seciruty context for the OTHER application.</p></li> -<li><p><strong>afm-user-daemon</strong> launches the OTHER application.</p></li> -</ol> - - -<p>This scenario does not cover all the features of the frameworks. -Shortly because details will be revealed in the next chapters, -the components are:</p> - -<ul> -<li><p><strong><em>SECURITY-MANAGER</em></strong>: in charge of setting Smack contexts and rules, -of setting groups, and, of creating initial content of <em>CYNARA</em> rules -for applications.</p></li> -<li><p><strong><em>CYNARA</em></strong>: in charge of handling API access permissions by users and by -applications.</p></li> -<li><p><strong><em>D-Bus</em></strong>: in charge of checking security of messaging. The usual D-Bus -security rules are enhanced by <em>CYNARA</em> checking rules.</p></li> -<li><p><strong><em>afm-system-daemon</em></strong>: in charge of installing and uninstalling applications.</p></li> -<li><p><strong><em>afm-user-daemon</em></strong>: in charge of listing applications, querying application details, -starting, terminating, stopping, resuming applications and their instances -for a given user context.</p></li> -<li><p><strong><em>afb-binder</em></strong>: in charge of serving resources and features through an -HTTP interface.</p></li> -<li><p><strong><em>afm-main-plugin</em></strong>: This plugin allows applications to use the API -of the AGL framework.</p></li> -</ul> - - -<a name="Links.between.the..Security.framework..and.the..Application.framework."></a> -<h2>Links between the “Security framework” and the “Application framework”</h2> - -<p>The security framework refers to the security model used to ensure -security and to the tools that are provided for implementing that model.</p> - -<p>The security model refers to how DAC (Discretionnary Access Control), -MAC (Mandatory Access Control) and Capabilities are used by the system -to ensure security and privacy. It also includes features of reporting -using audit features and by managing logs and alerts.</p> - -<p>The application framework manages the applications: -installing, uninstalling, starting, stopping, listing …</p> - -<p>The application framework uses the security model/framework -to ensure the security and the privacy of the applications that -it manages.</p> - -<p>The application framework must be compliant with the underlyiong -security model/framework. But it should hide it to the applications.</p> - -<a name="The.security.framework"></a> -<h2>The security framework</h2> - -<p>The implemented security model is the security model of Tizen 3. -This model is described <a href="https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview" title="Tizen 3 security overview">here</a>.</p> - -<p>The security framework then comes from Tizen 3 but through -the <a href="https://github.com/01org/meta-intel-iot-security" title="A collection of layers providing security technologies">meta-intel</a>. -It includes: <strong>Security-Manager</strong>, <strong>Cynara</strong> -and <strong>D-Bus</strong> compliant to Cynara.</p> - -<p>Two patches are applied to the security-manager. These patches are removing -dependencies to packages specific of Tizen but that are not needed by AGL. -None of these patches adds or removes any behaviour.</p> - -<p><strong>Theoritically, the security framework/model is an implementation details -that should not impact the layers above the application framework</strong>.</p> - -<p>The security framework of Tizen provides “nice lad” a valuable component to -scan log files and analyse auditing. This component is still in developement.</p> - -<a name="The.application.framework"></a> -<h2>The application framework</h2> - <p>The application framework on top of the security framework provides the components to install and uninstall applications and to run it in a secured environment.</p> @@ -286,5 +56,69 @@ futur to include for example incremental delivery.</p> <a name="ostro"></a> <h3>ostro</h3> + +<a name="Organisation.of.directory.of.applications"></a> +<h1>Organisation of directory of applications</h1> + +<p>The main path for applivcations are: APPDIR/PKGID/VER.</p> + +<p>Where:</p> + +<ul> +<li>APPDIR is as defined above</li> +<li>PKGID is a directory whose name is the package identifier</li> +<li>VER is the version of the package MAJOR.MINOR</li> +</ul> + + +<p>This organisation has the advantage to allow several versions to leave together. +This is needed for some good reasons (rolling back) and also for less good reasons (user habits).</p> + +<a name="Identity.of.installed.files"></a> +<h2>Identity of installed files</h2> + +<p>All the files are installed as the user “userapp” and group “userapp”. +All files have rw(x) for user and r-(x) for group and others.</p> + +<p>This allows any user to read the files.</p> + +<a name="Labelling.the.directories.of.applications"></a> +<h2>Labelling the directories of applications</h2> + +<a name="Organisation.of.data"></a> +<h1>Organisation of data</h1> + +<p>The data of a user are in its directory and are labelled using the labels of the application</p> + +<a name="Setting.Smack.rules.for.the.application"></a> +<h1>Setting Smack rules for the application</h1> + +<p>For Tizen, the following rules are set by the security manager for each application.</p> + +<pre><code>System ~APP~ rwx +System ~PKG~ rwxat +System ~PKG~::RO rwxat +~APP~ System wx +~APP~ System::Shared rxl +~APP~ System::Run rwxat +~APP~ System::Log rwxa +~APP~ _ l +User ~APP~ rwx +User ~PKG~ rwxat +User ~PKG~::RO rwxat +~APP~ User wx +~APP~ User::Home rxl +~APP~ User::App::Shared rwxat +~APP~ ~PKG~ rwxat +~APP~ ~PKG~::RO rxl +</code></pre> + +<p>Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application.</p> + +<a name="What.user.can.run.an.application."></a> +<h1>What user can run an application?</h1> + +<p>Not all user are able to run all applications. +How to manage that?</p> </body> </html> diff --git a/doc/application-framework.md b/doc/application-framework.md index 35ad960..ac6d40d 100644 --- a/doc/application-framework.md +++ b/doc/application-framework.md @@ -3,7 +3,7 @@ Application framework ===================== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo Foreword @@ -16,278 +16,103 @@ In case of differences, it is assumed that this document is right and the implementation is wrong. -Introduction ------------- - -During the first works in having the security model of Tizen -integrated in AGL (Automotive Grade Linux) distribution, it became -quickly obvious that the count of components specific to Tizen -to integrate was huge. - -Here is a minimal list of what was needed: - - - platform/appfw/app-installers - - platform/core/security/cert-svc - - platform/core/appfw/ail - - platform/core/appfw/aul-1 - - platform/core/appfw/libslp-db-util - - platform/core/appfw/pkgmgr-info - - platform/core/appfw/slp-pkgmgr - -But this list is complete because many dependencies are hidden. -Those hidden dependencies are including some common libraries but also many -tizen specific sub-components (iniparser, bundle, dlog, libtzplatform-config, -db-util, vconf-buxton, ...). - -This is an issue because AGL is not expected to be Tizen. Taking it would -either need to patch it for removing unwanted components or to take all -of them. - -However, a careful study of the core components of the security framework -of Tizen showed that their dependencies to Tizen are light (and since some -of our work, there is no more dependency to tizen). -Those components are **cynara**, **security-manager**, **D-Bus aware of cynara**. - -Luckyly, these core security components of Tizen are provided -by [meta-intel-iot-security][meta-intel], a set of yocto layers. -These layers were created by Intel to isolate Tizen specific security -components from the initial port of Tizen to Yocto. -The 3 layers are providing components for: - - * Implementing Smack LSM - * Implementing Integrity Measurement Architecture - * Implementing Tizen Security Framework - -The figure below shows the history of these layers. - - - 2014 2015 - Tizen OBS ----------+---------------------------> - \ - \ - Tizen Yocto +---------+--------------> - \ - \ - meta-intel-iot-security +-----------> - -We took the decision to use these security layers that provides the -basis of the Tizen security, the security framework. - -For the components of the application framework, built top of -the security framework, instead of pulling the huge set of packages -from Tizen, we decided to refit it by developping a tiny set of -components that would implement the same behaviour but without all -the dependencies and with minor architectural improvements for AGL. - -These components are **afm-system-daemon** and **afm-user-daemon**. -They provides infrastructure for installing, uninstalling, -launching, terminating, stopping and resuming applications in -a multi user secure environment. - -A third component exists in the framework, the binder **afb-daemon**. -The binder provides the easiest way to provide secured API for -any tier. Currently, the use of the binder is not absolutely mandatory. - -This documentation explains the framework created by IoT.bzh -by rewriting the Tizen Application Framework. Be aware of the -previous foreword. - - Overview -------- -The figure below shows the major components of the framework -and their interactions going through the following scenario: -APPLICATION installs an other application and then launch it. - - +-----------------------------------------------------------------------+ - | User | - | ................................ | - | : Smack isolation context : | - | : : ........................... | - | : +-----------------------+ : : Smack isolation context : | - | : | | : : : | - | : | APPLICATION | : : OTHER application : | - | : | | : :.........................: | - | : +-----------+-----------+ : ^ | - | : | : | | - | : |(1),(7) : |(13) | - | : | : | | - | : +-----------v-----------+ : +---------+---------------+ | - | : | binder afb-daemon | : | | | - | : +-----------------------+ : | afm-user-daemon | | - | : | afm-main-plugin | : | | | - | : +-----+--------------+--+ : +------^-------+------+---+ | - | :........|..............|......: | | : | - | |(2) |(8) |(10) | : | - | | | | | : | - | | +----v--------------------+---+ | : | - | | | D-Bus session | |(11) :(12) | - | | +-------------------------+---+ | : | - | | | | : | - | | |(9) | : | - | | | | : | - :===========|===================================|=======|======:========: - | | | | : | - | | +---v-------v--+ : | - | +------v-------------+ (3) | | : | - | | D-Bus system +-----------------> CYNARA | : | - | +------+-------------+ | | : | - | | +------^-------+ : | - | |(4) | : | - | | |(6) v | - | +------v--------------+ +---------+---------------+ | - | | | (5) | | | - | | afm-system-daemon +-------------> SECURITY-MANAGER | | - | | | | | | - | +---------------------+ +-------------------------+ | - | | - | System | - +-----------------------------------------------------------------------+ - -Let follow the sequence of calls: - -1. APPLICATION calls its **binder** to install the OTHER application. - -2. The plugin **afm-main-plugin** of the **binder** calls, through - **D-Bus** system, the system daemon to install the OTHER application. - -3. The system **D-Bus** checks wether APPLICATION has the permission - or not to install applications by calling **CYNARA**. - -4. The system **D-Bus** transmits the request to **afm-system-daemon**. - - **afm-system-daemon** checks the application to install, its - signatures and rights and install it. - -5. **afm-system-daemon** calls **SECURITY-MANAGER** for fullfilling - security context of the installed application. - -6. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions - for the application. - -7. APPLICATION call its binder to start the nearly installed OTHER application. - -8. The plugin **afm-main-plugin** of the **binder** calls, through - **D-Bus** session, the user daemon to launch the OTHER application. - -9. The session **D-Bus** checks wether APPLICATION has the permission - or not to start an application by calling **CYNARA**. - -10. The session **D-Bus** transmits the request to **afm-user-daemon**. - -11. **afm-user-daemon** checks wether APPLICATION has the permission - or not to start the OTHER application **CYNARA**. - -12. **afm-user-daemon** uses **SECURITY-MANAGER** features to set - the seciruty context for the OTHER application. - -13. **afm-user-daemon** launches the OTHER application. - -This scenario does not cover all the features of the frameworks. -Shortly because details will be revealed in the next chapters, -the components are: - -* ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules, - of setting groups, and, of creating initial content of *CYNARA* rules - for applications. - -* ***CYNARA***: in charge of handling API access permissions by users and by - applications. - -* ***D-Bus***: in charge of checking security of messaging. The usual D-Bus - security rules are enhanced by *CYNARA* checking rules. +The application framework on top of the security framework +provides the components to install and uninstall applications +and to run it in a secured environment. -* ***afm-system-daemon***: in charge of installing and uninstalling applications. +The goal is to manage applications and to hide the details of +the security framework to the applications. -* ***afm-user-daemon***: in charge of listing applications, querying application details, - starting, terminating, stopping, resuming applications and their instances - for a given user context. +For the reasons explained in introduction, we did not used the +application framework of Tizen as is but used an adaptation of it. -* ***afb-binder***: in charge of serving resources and features through an - HTTP interface. +The basis is kept identical: the applications are distributed +in a digitally signed container that must match the specifications +of widgets (web applications). This is described by the technical +recomendations [widgets] and [widgets-digsig] of the W3 consortium. -* ***afm-main-plugin***: This plugin allows applications to use the API - of the AGL framework. +This model allows the distribution of HTML, QML and binary applications. +The management of signatures of the widget packages +This basis is not meant as being rigid and it can be extended in the +futur to include for example incremental delivery. -Links between the "Security framework" and the "Application framework" ----------------------------------------------------------------------- -The security framework refers to the security model used to ensure -security and to the tools that are provided for implementing that model. +Comparison to other frameworks +------------------------------ -The security model refers to how DAC (Discretionnary Access Control), -MAC (Mandatory Access Control) and Capabilities are used by the system -to ensure security and privacy. It also includes features of reporting -using audit features and by managing logs and alerts. +### Tizen framework -The application framework manages the applications: -installing, uninstalling, starting, stopping, listing ... +### xdg-app -The application framework uses the security model/framework -to ensure the security and the privacy of the applications that -it manages. +### ostro -The application framework must be compliant with the underlyiong -security model/framework. But it should hide it to the applications. +Organisation of directory of applications +========================================= +The main path for applivcations are: APPDIR/PKGID/VER. -The security framework ----------------------- +Where: -The implemented security model is the security model of Tizen 3. -This model is described [here][tizen-secu-3]. + - APPDIR is as defined above + - PKGID is a directory whose name is the package identifier + - VER is the version of the package MAJOR.MINOR -The security framework then comes from Tizen 3 but through -the [meta-intel]. -It includes: **Security-Manager**, **Cynara** -and **D-Bus** compliant to Cynara. +This organisation has the advantage to allow several versions to leave together. +This is needed for some good reasons (rolling back) and also for less good reasons (user habits). -Two patches are applied to the security-manager. These patches are removing -dependencies to packages specific of Tizen but that are not needed by AGL. -None of these patches adds or removes any behaviour. +Identity of installed files +--------------------------- -**Theoritically, the security framework/model is an implementation details -that should not impact the layers above the application framework**. +All the files are installed as the user "userapp" and group "userapp". +All files have rw(x) for user and r-(x) for group and others. -The security framework of Tizen provides "nice lad" a valuable component to -scan log files and analyse auditing. This component is still in developement. +This allows any user to read the files. -The application framework -------------------------- +Labelling the directories of applications +----------------------------------------- -The application framework on top of the security framework -provides the components to install and uninstall applications -and to run it in a secured environment. -The goal is to manage applications and to hide the details of -the security framework to the applications. +Organisation of data +==================== -For the reasons explained in introduction, we did not used the -application framework of Tizen as is but used an adaptation of it. +The data of a user are in its directory and are labelled using the labels of the application -The basis is kept identical: the applications are distributed -in a digitally signed container that must match the specifications -of widgets (web applications). This is described by the technical -recomendations [widgets] and [widgets-digsig] of the W3 consortium. +Setting Smack rules for the application +======================================= -This model allows the distribution of HTML, QML and binary applications. +For Tizen, the following rules are set by the security manager for each application. -The management of signatures of the widget packages -This basis is not meant as being rigid and it can be extended in the -futur to include for example incremental delivery. + System ~APP~ rwx + System ~PKG~ rwxat + System ~PKG~::RO rwxat + ~APP~ System wx + ~APP~ System::Shared rxl + ~APP~ System::Run rwxat + ~APP~ System::Log rwxa + ~APP~ _ l + User ~APP~ rwx + User ~PKG~ rwxat + User ~PKG~::RO rwxat + ~APP~ User wx + ~APP~ User::Home rxl + ~APP~ User::App::Shared rwxat + ~APP~ ~PKG~ rwxat + ~APP~ ~PKG~::RO rxl +Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application. -Comparison to other frameworks ------------------------------- +What user can run an application? +================================= -### Tizen framework +Not all user are able to run all applications. +How to manage that? -### xdg-app -### ostro diff --git a/doc/overview.html b/doc/overview.html index f24d8b9..0c67b63 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -8,7 +8,7 @@ <h1>AGL framework, overview of the proposal of IoT.bzh</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> @@ -274,17 +274,5 @@ recomendations <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps"> <p>The management of signatures of the widget packages This basis is not meant as being rigid and it can be extended in the futur to include for example incremental delivery.</p> - -<a name="Comparison.to.other.frameworks"></a> -<h2>Comparison to other frameworks</h2> - -<a name="Tizen.framework"></a> -<h3>Tizen framework</h3> - -<a name="xdg-app"></a> -<h3>xdg-app</h3> - -<a name="ostro"></a> -<h3>ostro</h3> </body> </html> diff --git a/doc/overview.md b/doc/overview.md index a6922b1..22d8d81 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -3,7 +3,7 @@ AGL framework, overview of the proposal of IoT.bzh ================================================== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo Foreword @@ -280,16 +280,6 @@ This basis is not meant as being rigid and it can be extended in the futur to include for example incremental delivery. -Comparison to other frameworks ------------------------------- - -### Tizen framework - -### xdg-app - -### ostro - - [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" diff --git a/doc/security-framework.html b/doc/security-framework.html index e28909e..98598f0 100644 --- a/doc/security-framework.html +++ b/doc/security-framework.html @@ -8,7 +8,7 @@ <h1>The security framework</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> diff --git a/doc/security-framework.md b/doc/security-framework.md index 842e8c1..7407c17 100644 --- a/doc/security-framework.md +++ b/doc/security-framework.md @@ -3,7 +3,7 @@ The security framework ====================== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo diff --git a/doc/widgets.html b/doc/widgets.html index 2906bd0..77bf236 100644 --- a/doc/widgets.html +++ b/doc/widgets.html @@ -8,7 +8,7 @@ <h1>The widgets</h1> <pre><code>version: 1 -Date: 14 March 2016 +Date: 15 March 2016 Author: José Bollo </code></pre> diff --git a/doc/widgets.md b/doc/widgets.md index 11a0da7..6016a0d 100644 --- a/doc/widgets.md +++ b/doc/widgets.md @@ -3,7 +3,7 @@ The widgets =========== version: 1 - Date: 14 March 2016 + Date: 15 March 2016 Author: José Bollo The widgets @@ -19,3 +19,7 @@ List of things to do for the code - allow to control the environment setting of the launched instances - send the SIGKILL after a short time if SIGTERM has no effect + +- handle permission list at install + +- allows to check the requested permissions before to install it |