diff options
| author |   José Bollo <jose.bollo@iot.bzh> | 2016-03-15 09:51:56 +0100 |
|---|---|---|
| committer | José Bollo <jose.bollo@iot.bzh> | 2016-03-15 09:51:56 +0100 |
| commit | ddd10705d70b598160a41d197f364d2f792359f5 (patch) | |
| tree | 0d8a0f7182072079dbc84da4ca86b14162a5fde5 | |
| parent | 4ce25d0ddbcfe1111f0adbf63b4d73f19e926d8b (diff) | |
doc: create documentation
Create more documentation about afm-main.
Change-Id: I8b73017b666ac42da248df4219ec7abc08c7e877
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
| -rw-r--r-- | doc/afm-system-daemon.html | 79 | ||||
| -rw-r--r-- | doc/afm-system-daemon.md | 91 | ||||
| -rw-r--r-- | doc/afm-user-daemon.html | 777 | ||||
| -rw-r--r-- | doc/afm-user-daemon.md | 758 | ||||
| -rw-r--r-- | doc/application-framework.html | 290 | ||||
| -rw-r--r-- | doc/application-framework.md (renamed from framework.md) | 183 | ||||
| -rw-r--r-- | doc/doc.css | 9 | ||||
| -rw-r--r-- | doc/overview.html | 290 | ||||
| -rw-r--r-- | doc/overview.md | 310 | ||||
| -rw-r--r-- | doc/security-framework.html | 46 | ||||
| -rw-r--r-- | doc/security-framework.md | 60 | ||||
| -rw-r--r-- | doc/triskel_iot_bzh.svg | 110 | ||||
| -rwxr-xr-x | doc/updt.sh | 25 | ||||
| -rw-r--r-- | doc/widgets.html | 77 | ||||
| -rw-r--r-- | doc/widgets.md | 86 |
15 files changed, 3017 insertions, 174 deletions
diff --git a/doc/afm-system-daemon.html b/doc/afm-system-daemon.html new file mode 100644 index 0000000..96c6227 --- /dev/null +++ b/doc/afm-system-daemon.html @@ -0,0 +1,79 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="The.afm-system-daemon"></a> +<h1>The afm-system-daemon</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<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/afm-system-daemon.md b/doc/afm-system-daemon.md new file mode 100644 index 0000000..980f634 --- /dev/null +++ b/doc/afm-system-daemon.md @@ -0,0 +1,91 @@ + +The afm-system-daemon +===================== + + version: 1 + Date: 14 March 2016 + Author: José Bollo + + +Organisation of directory of applications +========================================= + +The main path for applivcations are: APPDIR/PKGID/VER. + +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? + + + + +[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[openssl]: https://www.openssl.org "OpenSSL" +[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" +[json-c]: https://github.com/json-c/json-c "JSON-c" +[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" +[libzip]: http://www.nih.at/libzip "libzip" +[cmake]: https://cmake.org "CMake" +[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" +[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" +[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" + + + diff --git a/doc/afm-user-daemon.html b/doc/afm-user-daemon.html new file mode 100644 index 0000000..cc9cb12 --- /dev/null +++ b/doc/afm-user-daemon.html @@ -0,0 +1,777 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="The.afm-user-daemon"></a> +<h1>The afm-user-daemon</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<a name="Foreword"></a> +<h2>Foreword</h2> + +<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>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-user-daemon</strong> is in charge of handling +applications for one user. Its main tasks are:</p> + +<ul> +<li><p>enumerate the applications that the user can run +and keep the list avalable on demand</p></li> +<li><p>start applications for the user, set their running +environment, set their security context</p></li> +<li><p>list the current runner applications</p></li> +<li><p>stop (aka pause), continue (aka resume), terminate +the running instance of application</p></li> +<li><p>transfer requests for installation or uninstallation +of applications to the dedicated system daemon +<strong>afm-system-daemon</strong></p></li> +</ul> + + +<p>The <strong>afm-user-daemon</strong> takes its orders from the session +instance of D-Bus.</p> + +<p>The figure below summarizes the situation of the +<strong>afm-user-daemon</strong> in the system.</p> + +<pre><code>+------------------------------------------------------------+ +| User | +| +---------------------+ | +| +---------------------+ | Smack isolated | | +| | D-Bus session + | APPLICATIONS | | +| +----------+----------+ +---------+-----------+ | +| | | | +| | | | +| +----------+--------------------------+-----------+ | +| | | | +| | afm-user-daemon | | +| | | | +| +----------+----------------------+----------+----+ | +| | | : | +| | | : | +:================|======================|==========:=========: +| | | : | +| +----------+----------+ +-----+-----+ : | +| | D-Bus system +-----+ CYNARA | : | +| +----------+----------+ +-----+-----+ : | +| | | : | +| +----------+---------+ +-------+----------+----+ | +| | afm-system-daemon +----+ SECURITY-MANAGER | | +| +--------------------+ +-----------------------+ | +| | +| System | ++------------------------------------------------------------+ +</code></pre> + +<a name="Tasks.of..strong.afm-user-daemon..strong."></a> +<h2>Tasks of <strong>afm-user-daemon</strong></h2> + +<a name="Maintaining.list.of.applications"></a> +<h3>Maintaining list of applications</h3> + +<p>At start <strong>afm-user-daemon</strong> scans the directories containing +the applications and load in memory the list applications +availables to the current user.</p> + +<p>When <strong>afm-system-daemon</strong> installs or removes an application, +it sends the signal <em>org.AGL.afm.system.changed</em> on success. +If it receives that signal, <strong>afm-user-daemon</strong> rebuild its +list of applications.</p> + +<p><strong>afm-user-daemon</strong> provides the data that it collected about +application to its clients that either want to get that list +or to get information about one application.</p> + +<a name="Launching.applications"></a> +<h3>Launching applications</h3> + +<p><strong>afm-user-daemon</strong> launchs the applications. This means +that its builds a secure environment for the application +and then start it inside that secured environment.</p> + +<p>Applications of different kind can be launched.</p> + +<p>This is set using a configuration file that describes +how to launch an application of a given kind for a given +mode.</p> + +<p>There is two launching modes: local or remote.</p> + +<p>Launching an application locally means that +the application and its binder are launcher together.</p> + +<p>Launching application remotely means that only the +binder is launched for the application.</p> + +<p>Once launched, running instances of application receive +a runid that identify them.</p> + +<a name="Managing.instances.of.running.applications"></a> +<h3>Managing instances of running applications</h3> + +<p><strong>afm-user-daemon</strong> manages the list of applications +that it launched.</p> + +<p>With the good permissions, a client can get the list +of the running instances and details about a specific +running instance. It can also terminate, stop or +continue a given application.</p> + +<a name="Installing.and.uninstalling.applications"></a> +<h3>Installing and uninstalling applications</h3> + +<p>If the client has the good permission, +<strong>afm-user-daemon</strong> delegates that task +to <strong>afm-system-daemon</strong>.</p> + +<a name="Starting..strong.afm-user-daemon..strong."></a> +<h2>Starting <strong>afm-user-daemon</strong></h2> + +<p><strong>afm-user-daemon</strong> is launched as a <strong>systemd</strong> service +attached to user sessions. Normally, the service file is +located at /usr/lib/systemd/user/afm-user-daemon.service.</p> + +<p>The options for launching <strong>afm-user-daemon</strong> are:</p> + +<pre><code>-a +--application directory + + Includes the given application directory to + the database base of applications. + +-r +--root directory + + Includes the root application directory to + the database base of applications. + + Note that the default root directory for + applications is always added. It is defined + to be /usr/share/afm/applications (may change). + +-m +--mode (local|remote) + + Set the default launch mode. + The default value is 'local' + +-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. +</code></pre> + +<a name="Configuration.of.the.launcher"></a> +<h2>Configuration of the launcher</h2> + +<p>It contains rules for launching applications. +When <strong>afm-user-daemon</strong> need to launch an application, +it looks to the mode of launch, local or remote, and the +type of the application as given by the file <strong><em>config.xml</em></strong> +of the widget.</p> + +<p>This couple mode and type allows to select the rule.</p> + +<p>The configuration file is <strong>/etc/afm/afm-launch.conf</strong>.</p> + +<p>It contains sections and rules. It can also contain comments +and empty lines to improve the readability.</p> + +<p>The separators are space and tabulation, any other character +is meaning something.</p> + +<p>The format is line oriented. +The new line character separate the lines.</p> + +<p>Lines having only separators are blank lines and are skipped. +Line having the character # (sharp) as first not separator character +are comment lines and are ignored.</p> + +<p>Lines starting with a not separator character are differents +of lines starting with a separator character.</p> + +<p>The grammar of the configuration file is defined below:</p> + +<pre><code>CONF: *COMMENT *SECTION + +SECTION: MODE *RULE + +RULE: +TYPE VECTOR ?VECTOR + +MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL + +TYPE: DATA *SEP EOL + +VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL + +DATA: CHAR *NCHAR +NDATA: +NCHAR + +EOL: NL *COMMENT +COMMENT: *SEP CMT *(SEP | NCHAR) NL + +NL: '\x0a' +SEP: '\x20' | '\x09' +CMT: '#' +CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff' +NCHAR: CMT | CHAR +</code></pre> + +<p>Here is a sample of configuration file for defining how +to launch an application declared of types <em>application/x-executable</em>, +<em>text/x-shellscript</em> and <em>text/html</em> in mode local:</p> + +<pre><code>mode local + +application/x-executable +text/x-shellscript + %r/%c + +text/html + /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon + /usr/bin/web-runtime http://localhost:%P/%c?token=%S +</code></pre> + +<p>This shows that:</p> + +<ul> +<li>within a section, several rules can be defined</li> +<li>within a rule, several types can be defined</li> +<li>within a rule, one or two vectors can be defined</li> +<li>vectors are using %substitution</li> +<li>launched binaries must be defined with their full path</li> +</ul> + + +<a name="mode.local"></a> +<h3>mode local</h3> + +<p>Within this mode, the launchers have either one or two vectors +describing them. All of these vectors are treated as programs +and are executed with the system call ‘execve’.</p> + +<p>The first vector is the leader vector and it defines the process +group. The second vector (if any) is attached to the group +defined by this first vector.</p> + +<a name="mode.remote"></a> +<h3>mode remote</h3> + +<p>Within this mode, the launchers have either one or two vectors +describing them.</p> + +<p>The first vector is treated as a program and is executed with +the system call ‘execve’.</p> + +<p>The second vector (if any) defines a text that is returned +to the caller. This mechanism can be used to return the uri +to connect to for executing the application remotely.</p> + +<p>The daemon <strong><em>afm-user-daemon</em></strong> allocates a port for the +running the application remotely. +The current implmentation of the port allocation is just +incremental. +A more reliable (cacheable and same-originable) allocation +is to be defined.</p> + +<a name="L.substitutions"></a> +<h3>%substitutions</h3> + +<p>Vectors can include sequences of 2 characters that have a special +meaning. These sequences are named <em>%substitution</em> because their +first character is the percent sign (%) and because each occurrence +of the sequence is replaced, at launch time, by the value associated +to sequences.</p> + +<p>Here is the list of <em>%substitutions</em>:</p> + +<ul> +<li><p><strong><em>%%</em></strong>: %.</p> + +<p>This simply emits the percent sign %</p></li> +<li><p><strong><em>%a</em></strong>: appid</p> + +<p>This is the application Id of the launched application.</p> + +<p>Defined by the attribute <strong>id</strong> of the element <strong><widget></strong> +of <strong>config.xml</strong>.</p></li> +<li><p><strong><em>%c</em></strong>: content</p> + +<p>The file within the widget directory that is the entry point.</p> + +<p>For a HTML application, it is the relative path to the main +page (aka index.html).</p> + +<p>Defined by the attribute <strong>src</strong> of the element <strong><content></strong> +of <strong>config.xml</strong>.</p></li> +<li><p><strong><em>%D</em></strong>: datadir</p> + +<p>Path of the directory where the application runs (cwd) +and stores its data.</p> + +<p>It is equal to %h/%a.</p></li> +<li><p><strong><em>%H</em></strong>: height</p> + +<p>Requested height for the widget.</p> + +<p>Defined by the attribute <strong>height</strong> of the element <strong><widget></strong> +of <strong>config.xml</strong>.</p></li> +<li><p><strong><em>%h</em></strong>: homedir</p> + +<p>Path of the home directory for all applications.</p> + +<p>It is generally equal to $HOME/app-data</p></li> +<li><p><strong><em>%I</em></strong>: icondir</p> + +<p>Path of the directory were the icons of the applications can be found.</p></li> +<li><p><strong><em>%m</em></strong>: mime-type</p> + +<p>Mime type of the launched application.</p> + +<p>Defined by the attribute <strong>type</strong> of the element <strong><content></strong> +of <strong>config.xml</strong>.</p></li> +<li><p><strong><em>%n</em></strong>: name</p> + +<p>Name of the application as defined by the content of the +element <strong><name></strong> of <strong>config.xml</strong>.</p></li> +<li><p><strong><em>%p</em></strong>: plugins</p> + +<p>Unhandled until now.</p> + +<p>Will be the colon separated list of plugins and plugins directory.</p></li> +<li><p><strong><em>%P</em></strong>: port</p> + +<p>A port to use. It is currently a kind of random port. The precise +model is to be defined later.</p></li> +<li><p><strong><em>%R</em></strong>: readyfd</p> + +<p>Number of the file descriptor to use for signalling +readyness of the launched process.</p></li> +<li><p><strong><em>%r</em></strong>: rootdir</p> + +<p>Path of the directory containing the widget and its data.</p></li> +<li><p><strong><em>%S</em></strong>: secret</p> + +<p>An hexadecimal number that can be used to pair the client +with its server binder.</p></li> +<li><p><strong><em>%W</em></strong>: width</p> + +<p>Requested width for the widget.</p> + +<p>Defined by the attribute <strong>width</strong> of the element <strong><widget></strong> +of <strong>config.xml</strong>.</p></li> +</ul> + + +<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-user-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 dbus of the session is by default adressed by the environment +variable <strong><em>DBUS_SESSION_BUS_ADDRESS</em></strong>. Using <strong>systemd</strong> +the variable <em>DBUS_SESSION_BUS_ADDRESS</em> is automatically set for +user sessions.</p> + +<p>The <strong>afm-user-daemon</strong> is listening with the destination name +<strong><em>org.AGL.afm.user</em></strong> at the object of path <strong><em>/org/AGL/afm/user</em></strong> +on the interface <strong><em>org.AGL.afm.user</em></strong> for the below detailed +members <strong><em>runnables</em></strong>, <strong><em>detail</em></strong>, <strong><em>start</em></strong>, <strong><em>terminate</em></strong>, +<strong><em>stop</em></strong>, <strong><em>continue</em></strong>, <strong><em>runners</em></strong>, <strong><em>state</em></strong>, +<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.user</strong></p></li> +<li><p>PATH: <strong>/org/AGL/afm/user</strong></p></li> +<li><p>INTERFACE: <strong>org.AGL.afm.user</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.user \ + /org/AGL/afm/user \ + org.AGL.afm.user.runnables string:true +</code></pre> + +<a name="Using..strong..em.afm-util..em...strong."></a> +<h3>Using <strong><em>afm-util</em></strong></h3> + +<p>The command line tool <strong><em>afm-util</em></strong> uses dbus-send to send +orders to <strong>afm-user-daemon</strong>. This small scripts allows to +send command to <strong><em>afm-user-daemon</em></strong> either interactively +at shell prompt or scriptically.</p> + +<p>The syntax is simple: it accept a command and if the command +requires it, the argument to the command.</p> + +<p>Here is the summary of <strong><em>afm-util</em></strong>:</p> + +<ul> +<li><p><strong>afm-util runnables </strong>:</p> + +<p>list the runnable widgets installed</p></li> +<li><p><strong>afm-util install wgt </strong>:</p> + +<p>install the wgt file</p></li> +<li><p><strong>afm-util uninstall id </strong>:</p> + +<p>remove the installed widget of id</p></li> +<li><p><strong>afm-util detail id </strong>:</p> + +<p>print detail about the installed widget of id</p></li> +<li><p><strong>afm-util runners </strong>:</p> + +<p>list the running instance</p></li> +<li><p><strong>afm-util start id </strong>:</p> + +<p>start an instance of the widget of id</p></li> +<li><p><strong>afm-util terminate rid </strong>:</p> + +<p>terminate the running instance rid</p></li> +<li><p><strong>afm-util stop rid </strong>:</p> + +<p>stop the running instance rid</p></li> +<li><p><strong>afm-util continue rid </strong>:</p> + +<p>continue the previously rid</p></li> +<li><p><strong>afm-util state rid </strong>:</p> + +<p>get status of the running instance rid</p></li> +</ul> + + +<p>Here is how to list applications using <strong><em>afm-util</em></strong>:</p> + +<pre><code>afm-util runnables +</code></pre> + +<hr /> + +<a name="The.protocol.over.D-Bus"></a> +<h3>The protocol over D-Bus</h3> + +<p>Recall:</p> + +<ul> +<li><p><strong>DESTINATION</strong>: org.AGL.afm.user</p></li> +<li><p><strong>PATH</strong>: /org/AGL/afm/user</p></li> +<li><p><strong>INTERFACE</strong>: org.AGL.afm.user</p></li> +</ul> + + +<hr /> + +<a name="Method.org.AGL.afm.user.detail"></a> +<h4>Method org.AGL.afm.user.detail</h4> + +<p><strong>Description</strong>: Get details about an application from its id.</p> + +<p><strong>Input</strong>: the id of the application as below.</p> + +<p>Either just a string:</p> + +<pre><code>"appli@x.y" +</code></pre> + +<p>Or an object having the field “id” of type string:</p> + +<pre><code>{"id":"appli@x.y"} +</code></pre> + +<p><strong>Output</strong>: A JSON object describing the application containing +the fields described below.</p> + +<pre><code>{ + "id": string, the application id (id@version) + "version": string, the version of the application + "width": integer, requested width of the application + "height": integer, resqueted height of the application + "name": string, the name of the application + "description": string, the description of the application + "shortname": string, the short name of the application + "author": string, the author of the application +} +</code></pre> + +<hr /> + +<a name="Method.org.AGL.afm.user.runnables"></a> +<h4>Method org.AGL.afm.user.runnables</h4> + +<p><strong>Description</strong>: Get the list of applications that can be run.</p> + +<p><strong>Input</strong>: any valid json entry, can be anything except null.</p> + +<p><strong>output</strong>: An array of description of the runnable applications. +Each item of the array contains an object containing the detail of +an application as described above for the method +<em>org.AGL.afm.user.detail</em>.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.install"></a> +<h4>Method org.AGL.afm.user.install</h4> + +<p><strong>Description</strong>: Install an application from its widget file.</p> + +<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-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.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.user.uninstall"></a> +<h4>Method org.AGL.afm.user.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-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.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><strong>output</strong>: the value ‘true’.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.start"></a> +<h4>Method org.AGL.afm.user.start</h4> + +<p><strong>Description</strong>:</p> + +<p><strong>Input</strong>: the <em>id</em> of the application and, optionaly, the +start <em>mode</em> as below.</p> + +<p>Either just a string:</p> + +<pre><code>"appli@x.y" +</code></pre> + +<p>Or an object having the field “id” of type string and +optionaly a field mode:</p> + +<pre><code>{"id":"appli@x.y","mode":"local"} +</code></pre> + +<p>The field “mode” as a string value being either “local” or “remote”.</p> + +<p><strong>output</strong>: The <em>runid</em> of the application launched. +The runid is an integer.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.terminate"></a> +<h4>Method org.AGL.afm.user.terminate</h4> + +<p><strong>Description</strong>: Terminates the application of <em>runid</em>.</p> + +<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to terminate.</p> + +<p><strong>output</strong>: the value ‘true’.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.stop"></a> +<h4>Method org.AGL.afm.user.stop</h4> + +<p><strong>Description</strong>: Stops the application of <em>runid</em> until terminate or continue.</p> + +<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to stop.</p> + +<p><strong>output</strong>: the value ‘true’.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.continue"></a> +<h4>Method org.AGL.afm.user.continue</h4> + +<p><strong>Description</strong>: Continues the application of <em>runid</em> previously stopped.</p> + +<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to continue.</p> + +<p><strong>output</strong>: the value ‘true’.</p> + +<hr /> + +<a name="Method.org.AGL.afm.user.state"></a> +<h4>Method org.AGL.afm.user.state</h4> + +<p><strong>Description</strong>: Get informations about a running instance of <em>runid</em>.</p> + +<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance inspected.</p> + +<p><strong>output</strong>: An object describing the state of the instance. It contains: +the runid (an integer), the id of the running application (a string), +the state of the application (a string being either “starting”, “running” +or “stopped”).</p> + +<p>Example of returned state:</p> + +<pre><code>{ + "runid": 2, + "state": "running", + "id": "appli@x.y" +} +</code></pre> + +<hr /> + +<a name="Method.org.AGL.afm.user.runners"></a> +<h4>Method org.AGL.afm.user.runners</h4> + +<p><strong>Description</strong>: Get the list of the currently running instances.</p> + +<p><strong>Input</strong>: anything.</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 new file mode 100644 index 0000000..107b399 --- /dev/null +++ b/doc/afm-user-daemon.md @@ -0,0 +1,758 @@ + +The afm-user-daemon +=================== + + version: 1 + Date: 14 March 2016 + Author: José Bollo + + +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-user-daemon** is in charge of handling +applications for one user. Its main tasks are: + + - enumerate the applications that the user can run + and keep the list avalable on demand + + - start applications for the user, set their running + environment, set their security context + + - list the current runner applications + + - stop (aka pause), continue (aka resume), terminate + the running instance of application + + - transfer requests for installation or uninstallation + of applications to the dedicated system daemon + **afm-system-daemon** + +The **afm-user-daemon** takes its orders from the session +instance of D-Bus. + +The figure below summarizes the situation of the +**afm-user-daemon** in the system. + + +------------------------------------------------------------+ + | User | + | +---------------------+ | + | +---------------------+ | Smack isolated | | + | | D-Bus session + | APPLICATIONS | | + | +----------+----------+ +---------+-----------+ | + | | | | + | | | | + | +----------+--------------------------+-----------+ | + | | | | + | | afm-user-daemon | | + | | | | + | +----------+----------------------+----------+----+ | + | | | : | + | | | : | + :================|======================|==========:=========: + | | | : | + | +----------+----------+ +-----+-----+ : | + | | D-Bus system +-----+ CYNARA | : | + | +----------+----------+ +-----+-----+ : | + | | | : | + | +----------+---------+ +-------+----------+----+ | + | | afm-system-daemon +----+ SECURITY-MANAGER | | + | +--------------------+ +-----------------------+ | + | | + | System | + +------------------------------------------------------------+ + + +Tasks of **afm-user-daemon** +---------------------------- + +### Maintaining list of applications ### + +At start **afm-user-daemon** scans the directories containing +the applications and load in memory the list applications +availables to the current user. + +When **afm-system-daemon** installs or removes an application, +it sends the signal *org.AGL.afm.system.changed* on success. +If it receives that signal, **afm-user-daemon** rebuild its +list of applications. + +**afm-user-daemon** provides the data that it collected about +application to its clients that either want to get that list +or to get information about one application. + +### Launching applications ### + +**afm-user-daemon** launchs the applications. This means +that its builds a secure environment for the application +and then start it inside that secured environment. + +Applications of different kind can be launched. + +This is set using a configuration file that describes +how to launch an application of a given kind for a given +mode. + +There is two launching modes: local or remote. + +Launching an application locally means that +the application and its binder are launcher together. + +Launching application remotely means that only the +binder is launched for the application. + +Once launched, running instances of application receive +a runid that identify them. + +### Managing instances of running applications ### + +**afm-user-daemon** manages the list of applications +that it launched. + +With the good permissions, a client can get the list +of the running instances and details about a specific +running instance. It can also terminate, stop or +continue a given application. + +### Installing and uninstalling applications ### + +If the client has the good permission, +**afm-user-daemon** delegates that task +to **afm-system-daemon**. + + +Starting **afm-user-daemon** +----------------------------- + +**afm-user-daemon** is launched as a **systemd** service +attached to user sessions. Normally, the service file is +located at /usr/lib/systemd/user/afm-user-daemon.service. + +The options for launching **afm-user-daemon** are: + + -a + --application directory + + Includes the given application directory to + the database base of applications. + + -r + --root directory + + Includes the root application directory to + the database base of applications. + + Note that the default root directory for + applications is always added. It is defined + to be /usr/share/afm/applications (may change). + + -m + --mode (local|remote) + + Set the default launch mode. + The default value is 'local' + + -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. + + +Configuration of the launcher +----------------------------- + +It contains rules for launching applications. +When **afm-user-daemon** need to launch an application, +it looks to the mode of launch, local or remote, and the +type of the application as given by the file ***config.xml*** +of the widget. + +This couple mode and type allows to select the rule. + +The configuration file is **/etc/afm/afm-launch.conf**. + +It contains sections and rules. It can also contain comments +and empty lines to improve the readability. + +The separators are space and tabulation, any other character +is meaning something. + +The format is line oriented. +The new line character separate the lines. + +Lines having only separators are blank lines and are skipped. +Line having the character # (sharp) as first not separator character +are comment lines and are ignored. + +Lines starting with a not separator character are differents +of lines starting with a separator character. + +The grammar of the configuration file is defined below: + + CONF: *COMMENT *SECTION + + SECTION: MODE *RULE + + RULE: +TYPE VECTOR ?VECTOR + + MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL + + TYPE: DATA *SEP EOL + + VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL + + DATA: CHAR *NCHAR + NDATA: +NCHAR + + EOL: NL *COMMENT + COMMENT: *SEP CMT *(SEP | NCHAR) NL + + NL: '\x0a' + SEP: '\x20' | '\x09' + CMT: '#' + CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff' + NCHAR: CMT | CHAR + +Here is a sample of configuration file for defining how +to launch an application declared of types *application/x-executable*, +*text/x-shellscript* and *text/html* in mode local: + + mode local + + application/x-executable + text/x-shellscript + %r/%c + + text/html + /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon + /usr/bin/web-runtime http://localhost:%P/%c?token=%S + +This shows that: + + - within a section, several rules can be defined + - within a rule, several types can be defined + - within a rule, one or two vectors can be defined + - vectors are using %substitution + - launched binaries must be defined with their full path + +### mode local + +Within this mode, the launchers have either one or two vectors +describing them. All of these vectors are treated as programs +and are executed with the system call 'execve'. + +The first vector is the leader vector and it defines the process +group. The second vector (if any) is attached to the group +defined by this first vector. + +### mode remote + +Within this mode, the launchers have either one or two vectors +describing them. + +The first vector is treated as a program and is executed with +the system call 'execve'. + +The second vector (if any) defines a text that is returned +to the caller. This mechanism can be used to return the uri +to connect to for executing the application remotely. + +The daemon ***afm-user-daemon*** allocates a port for the +running the application remotely. +The current implmentation of the port allocation is just +incremental. +A more reliable (cacheable and same-originable) allocation +is to be defined. + +### %substitutions + +Vectors can include sequences of 2 characters that have a special +meaning. These sequences are named *%substitution* because their +first character is the percent sign (%) and because each occurrence +of the sequence is replaced, at launch time, by the value associated +to sequences. + +Here is the list of *%substitutions*: + + - ***%%***: %. + + This simply emits the percent sign % + + - ***%a***: appid + + This is the application Id of the launched application. + + Defined by the attribute **id** of the element **<widget>** + of **config.xml**. + + - ***%c***: content + + The file within the widget directory that is the entry point. + + For a HTML application, it is the relative path to the main + page (aka index.html). + + Defined by the attribute **src** of the element **<content>** + of **config.xml**. + + - ***%D***: datadir + + Path of the directory where the application runs (cwd) + and stores its data. + + It is equal to %h/%a. + + - ***%H***: height + + Requested height for the widget. + + Defined by the attribute **height** of the element **<widget>** + of **config.xml**. + + - ***%h***: homedir + + Path of the home directory for all applications. + + It is generally equal to $HOME/app-data + + - ***%I***: icondir + + Path of the directory were the icons of the applications can be found. + + - ***%m***: mime-type + + Mime type of the launched application. + + Defined by the attribute **type** of the element **<content>** + of **config.xml**. + + - ***%n***: name + + Name of the application as defined by the content of the + element **<name>** of **config.xml**. + + - ***%p***: plugins + + Unhandled until now. + + Will be the colon separated list of plugins and plugins directory. + + - ***%P***: port + + A port to use. It is currently a kind of random port. The precise + model is to be defined later. + + - ***%R***: readyfd + + Number of the file descriptor to use for signalling + readyness of the launched process. + + - ***%r***: rootdir + + Path of the directory containing the widget and its data. + + - ***%S***: secret + + An hexadecimal number that can be used to pair the client + with its server binder. + + - ***%W***: width + + Requested width for the widget. + + Defined by the attribute **width** of the element **<widget>** + of **config.xml**. + + +The D-Bus interface +------------------- + +### Overview of the dbus interface + +***afm-user-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 dbus of the session is by default adressed by the environment +variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd** +the variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for +user sessions. + +The **afm-user-daemon** is listening with the destination name +***org.AGL.afm.user*** at the object of path ***/org/AGL/afm/user*** +on the interface ***org.AGL.afm.user*** for the below detailed +members ***runnables***, ***detail***, ***start***, ***terminate***, +***stop***, ***continue***, ***runners***, ***state***, +***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.user** + + * PATH: **/org/AGL/afm/user** + + * INTERFACE: **org.AGL.afm.user** + +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.user \ + /org/AGL/afm/user \ + org.AGL.afm.user.runnables string:true + +### Using ***afm-util*** + +The command line tool ***afm-util*** uses dbus-send to send +orders to **afm-user-daemon**. This small scripts allows to +send command to ***afm-user-daemon*** either interactively +at shell prompt or scriptically. + +The syntax is simple: it accept a command and if the command +requires it, the argument to the command. + +Here is the summary of ***afm-util***: + + - **afm-util runnables **: + + list the runnable widgets installed + + - **afm-util install wgt **: + + install the wgt file + + - **afm-util uninstall id **: + + remove the installed widget of id + + - **afm-util detail id **: + + print detail about the installed widget of id + + - **afm-util runners **: + + list the running instance + + - **afm-util start id **: + + start an instance of the widget of id + + - **afm-util terminate rid **: + + terminate the running instance rid + + - **afm-util stop rid **: + + stop the running instance rid + + - **afm-util continue rid **: + + continue the previously rid + + - **afm-util state rid **: + + get status of the running instance rid + + +Here is how to list applications using ***afm-util***: + + afm-util runnables + +--- + +### The protocol over D-Bus + +Recall: + + * **DESTINATION**: org.AGL.afm.user + + * **PATH**: /org/AGL/afm/user + + * **INTERFACE**: org.AGL.afm.user + +--- + +#### Method org.AGL.afm.user.detail + +**Description**: Get details about an application from its id. + +**Input**: the id of the application as below. + +Either just a string: + + "appli@x.y" + +Or an object having the field "id" of type string: + + {"id":"appli@x.y"} + +**Output**: A JSON object describing the application containing +the fields described below. + + { + "id": string, the application id (id@version) + "version": string, the version of the application + "width": integer, requested width of the application + "height": integer, resqueted height of the application + "name": string, the name of the application + "description": string, the description of the application + "shortname": string, the short name of the application + "author": string, the author of the application + } + +--- + +#### Method org.AGL.afm.user.runnables + +**Description**: Get the list of applications that can be run. + +**Input**: any valid json entry, can be anything except null. + +**output**: An array of description of the runnable applications. +Each item of the array contains an object containing the detail of +an application as described above for the method +*org.AGL.afm.user.detail*. + +--- + +#### Method org.AGL.afm.user.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-user-daemon*** sends the signal ***org.AGL.afm.user.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.user.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-user-daemon*** sends the signal ***org.AGL.afm.user.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'. + +--- + +#### Method org.AGL.afm.user.start + +**Description**: + +**Input**: the *id* of the application and, optionaly, the +start *mode* as below. + +Either just a string: + + "appli@x.y" + +Or an object having the field "id" of type string and +optionaly a field mode: + + {"id":"appli@x.y","mode":"local"} + +The field "mode" as a string value being either "local" or "remote". + +**output**: The *runid* of the application launched. +The runid is an integer. + +--- + +#### Method org.AGL.afm.user.terminate + +**Description**: Terminates the application of *runid*. + +**Input**: The *runid* (an integer) of the running instance to terminate. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.stop + +**Description**: Stops the application of *runid* until terminate or continue. + +**Input**: The *runid* (an integer) of the running instance to stop. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.continue + +**Description**: Continues the application of *runid* previously stopped. + +**Input**: The *runid* (an integer) of the running instance to continue. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.state + +**Description**: Get informations about a running instance of *runid*. + +**Input**: The *runid* (an integer) of the running instance inspected. + +**output**: An object describing the state of the instance. It contains: +the runid (an integer), the id of the running application (a string), +the state of the application (a string being either "starting", "running" +or "stopped"). + +Example of returned state: + + { + "runid": 2, + "state": "running", + "id": "appli@x.y" + } + +--- + +#### Method org.AGL.afm.user.runners + +**Description**: Get the list of the currently running instances. + +**Input**: anything. + +**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 new file mode 100644 index 0000000..f77ee48 --- /dev/null +++ b/doc/application-framework.html @@ -0,0 +1,290 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="Application.framework"></a> +<h1>Application framework</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<a name="Foreword"></a> +<h2>Foreword</h2> + +<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>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> + +<p>The goal is to manage applications and to hide the details of +the security framework to the applications.</p> + +<p>For the reasons explained in introduction, we did not used the +application framework of Tizen as is but used an adaptation of it.</p> + +<p>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 <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a> of the W3 consortium.</p> + +<p>This model allows the distribution of HTML, QML and binary applications.</p> + +<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/framework.md b/doc/application-framework.md index 0fddbcd..35ad960 100644 --- a/framework.md +++ b/doc/application-framework.md @@ -1,10 +1,9 @@ - -AGL framework, proposal of IoT.bzh -================================== +Application framework +===================== version: 1 - Date: 29 february 2016 + Date: 14 March 2016 Author: José Bollo Foreword @@ -260,7 +259,7 @@ The application framework ------------------------- The application framework on top of the security framework -provides the compoenents to install and uninstall applications +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 @@ -280,180 +279,16 @@ 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. -The widgets ------------ - -### signature of the - -The application framework - -This is the original part of our work here - -### directory where are stored applications - -Applications can be installed in few places: on the system itself or on an extension device. -For my phone, for example, it is the sd card. - -This translates to: - - - /usr/applications: for system wide applications - - /opt/applications: for removable applications - -In the remaining of the document, these places are writen "APPDIR". - - -Organisation of directory of applications -========================================= - -The main path for applivcations are: APPDIR/PKGID/VER. - -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? - - - -API of the framework -==================== - -Data handled ------------- - -=== description of an application - -the JSON object: APPDESC - - { - "appid": string, the application id for the framework - "id": string, the application intrinsic id - "version": string, the version of the application - "path": string, the path of the directory of the application - "width": integer, requested width of the application - "height": integer, resqueted height of the application - "name": string, the name of the application - "description": string, the description of the application - "shortname": string, the short name of the application - "author": string, the author of the application - } - - -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 -*/ - -API of the store -================ - -The base of the path is STORAPI = /api/store -request STORAPI/search[?q=...] - subject to languages tuning - => [ { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author", "icon": "url" }... ] +Comparison to other frameworks +------------------------------ -/* -request STORAPI/icon?id=APPID - subject to languages tuning - => the icon image -*/ +### Tizen framework -request STORAPI/detail?id=APPID - => { "id": "APPID", "name": "name", "description": "description", "license": "license", "author": "author", "icon": "url", "permissions": [ "perm"... ] } +### xdg-app +### ostro -request STORAPI/install?id=APPID&permissions - => { "transaction": "XXX", "desc"= { see above } } or error diff --git a/doc/doc.css b/doc/doc.css new file mode 100644 index 0000000..19699bf --- /dev/null +++ b/doc/doc.css @@ -0,0 +1,9 @@ +body { + background: #fff url(triskel_iot_bzh.svg) no-repeat fixed right top; + font-family: "Verdana"; + color: #000; +} + +h1, h2, h3 { color: #306; } + + diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..f24d8b9 --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,290 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="AGL.framework..overview.of.the.proposal.of.IoT.bzh"></a> +<h1>AGL framework, overview of the proposal of IoT.bzh</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<a name="Foreword"></a> +<h2>Foreword</h2> + +<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>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> + +<p>The goal is to manage applications and to hide the details of +the security framework to the applications.</p> + +<p>For the reasons explained in introduction, we did not used the +application framework of Tizen as is but used an adaptation of it.</p> + +<p>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 <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a> of the W3 consortium.</p> + +<p>This model allows the distribution of HTML, QML and binary applications.</p> + +<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 new file mode 100644 index 0000000..a6922b1 --- /dev/null +++ b/doc/overview.md @@ -0,0 +1,310 @@ + +AGL framework, overview of the proposal of IoT.bzh +================================================== + + version: 1 + Date: 14 March 2016 + Author: José Bollo + +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 +------------ + +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. + +* ***afm-system-daemon***: in charge of installing and uninstalling 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. + +* ***afb-binder***: in charge of serving resources and features through an + HTTP interface. + +* ***afm-main-plugin***: This plugin allows applications to use the API + of the AGL framework. + + +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. + +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. + +The application framework manages the applications: +installing, uninstalling, starting, stopping, listing ... + +The application framework uses the security model/framework +to ensure the security and the privacy of the applications that +it manages. + +The application framework must be compliant with the underlyiong +security model/framework. But it should hide it to the applications. + + +The security framework +---------------------- + +The implemented security model is the security model of Tizen 3. +This model is described [here][tizen-secu-3]. + +The security framework then comes from Tizen 3 but through +the [meta-intel]. +It includes: **Security-Manager**, **Cynara** +and **D-Bus** compliant to Cynara. + +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. + +**Theoritically, the security framework/model is an implementation details +that should not impact the layers above the application framework**. + +The security framework of Tizen provides "nice lad" a valuable component to +scan log files and analyse auditing. This component is still in developement. + + +The application framework +------------------------- + +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. + +For the reasons explained in introduction, we did not used the +application framework of Tizen as is but used an adaptation of it. + +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. + +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. + + +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" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[openssl]: https://www.openssl.org "OpenSSL" +[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" +[json-c]: https://github.com/json-c/json-c "JSON-c" +[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" +[libzip]: http://www.nih.at/libzip "libzip" +[cmake]: https://cmake.org "CMake" +[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" +[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" +[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" + + diff --git a/doc/security-framework.html b/doc/security-framework.html new file mode 100644 index 0000000..e28909e --- /dev/null +++ b/doc/security-framework.html @@ -0,0 +1,46 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="The.security.framework"></a> +<h1>The security framework</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<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/security-framework.md b/doc/security-framework.md new file mode 100644 index 0000000..842e8c1 --- /dev/null +++ b/doc/security-framework.md @@ -0,0 +1,60 @@ + +The security framework +====================== + + version: 1 + Date: 14 March 2016 + Author: José Bollo + + +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? + + + + +[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[openssl]: https://www.openssl.org "OpenSSL" +[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" +[json-c]: https://github.com/json-c/json-c "JSON-c" +[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" +[libzip]: http://www.nih.at/libzip "libzip" +[cmake]: https://cmake.org "CMake" +[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" +[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" +[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" + + + + diff --git a/doc/triskel_iot_bzh.svg b/doc/triskel_iot_bzh.svg new file mode 100644 index 0000000..096f424 --- /dev/null +++ b/doc/triskel_iot_bzh.svg @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="205.71426" + height="197.14285" + id="svg4199" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="triskel_iot_bzh.svg"> + <defs + id="defs4201"> + <filter + color-interpolation-filters="sRGB" + id="filter4111" + inkscape:label="Drop Shadow"> + <feFlood + id="feFlood4113" + flood-opacity="0.475" + flood-color="rgb(0,0,0)" + result="flood" /> + <feComposite + id="feComposite4115" + in2="SourceGraphic" + in="flood" + operator="in" + result="composite1" /> + <feGaussianBlur + id="feGaussianBlur4117" + stdDeviation="5" + result="blur" /> + <feOffset + id="feOffset4119" + dx="8" + dy="8" + result="offset" /> + <feComposite + id="feComposite4121" + in2="offset" + in="SourceGraphic" + operator="over" + result="composite2" /> + </filter> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.35" + inkscape:cx="46.428557" + inkscape:cy="178.57144" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:window-width="500" + inkscape:window-height="435" + inkscape:window-x="1087" + inkscape:window-y="400" + inkscape:window-maximized="0" /> + <metadata + id="metadata4204"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-328.57144,-513.79077)"> + <path + id="path3415-4-2-2-5-0-3-7-4-4-1-9" + style="fill:#5a2ca0;display:inline;filter:url(#filter4111)" + d="m 470.88567,595.30412 c 28.21686,16.29102 28.75566,58.73778 0.99693,78.5383 -7.67688,5.47598 -8.77935,4.91028 -1.99529,-1.0238 17.47377,-15.28453 17.98492,-42.17774 1.08522,-57.09785 l -3.91266,-3.45435 0.72312,-3.71053 c 0.39771,-2.04076 0.5997,-5.73115 0.44885,-8.20083 -0.33876,-5.54623 0.15803,-6.49185 2.65383,-5.05094 z m -64.76568,11.40332 c 7.06047,-7.74198 18.64659,-14.16089 29.04027,-16.08874 l 6.87489,-1.27521 0.87404,2.89709 c 0.4807,1.59343 0.67439,5.2245 0.43037,8.06906 l -0.44364,5.17195 -6.13887,1.6918 c -10.91241,3.00731 -20.4022,10.85909 -25.4533,21.05979 l -2.41633,4.87984 -2.74281,-0.41238 c -5.14252,-0.77316 -12.72985,-3.97645 -12.79123,-5.40033 -0.092,-2.13451 8.34659,-15.74625 12.76661,-20.59287 z m 33.20546,36.39493 c -28.21687,16.291 -65.24624,-4.46574 -68.51461,-38.40577 -0.9039,-9.38637 0.13723,-10.0583 1.88428,-1.21608 4.49989,22.77499 27.53453,36.66428 48.90556,29.48876 l 4.94788,-1.66128 2.85184,2.48149 c 1.56852,1.36481 4.66349,3.38493 6.87772,4.48914 4.97257,2.47973 5.54308,3.38282 3.04733,4.82374 z m 22.50729,-61.7904 c 3.17451,9.98554 2.94038,23.2289 -0.58688,33.194 l -2.33309,6.59143 -2.94597,-0.69161 c -1.6203,-0.38041 -4.86173,-2.02821 -7.2032,-3.6618 l -4.25721,-2.97018 1.60429,-6.16234 c 2.85178,-10.95404 0.79685,-23.09834 -5.51167,-32.57308 l -3.01788,-4.53253 1.72854,-2.16916 c 3.24083,-4.06698 9.80863,-9.03614 11.07242,-8.37738 1.89457,0.98756 9.46336,15.1015 11.45065,21.35265 z m -48.80223,10.31438 c 0,-32.58202 36.49058,-54.27202 67.51771,-40.13251 8.58077,3.9104 8.6421,5.148 0.11108,2.23988 -21.97368,-7.49048 -45.51946,5.51348 -49.99082,27.6091 l -1.03521,5.11562 -3.57498,1.22902 c -1.96621,0.67596 -5.26316,2.34622 -7.32655,3.71171 -4.63379,3.06649 -5.70115,3.10904 -5.70115,0.22718 z m 42.25842,50.3871 c -10.23499,-2.24356 -21.58699,-9.06801 -28.45341,-17.10525 l -4.5418,-5.31622 2.07194,-2.20549 c 1.13957,-1.21302 4.18733,-3.19628 6.77282,-4.40726 l 4.70085,-2.20176 4.53458,4.47053 c 8.06061,7.94674 19.60535,12.23927 30.96496,11.51329 l 5.43422,-0.34731 1.01427,2.58154 c 1.90169,4.84014 2.92124,13.01261 1.71883,13.77769 -1.80254,1.14695 -17.80995,0.64475 -24.21726,-0.75976 z" + inkscape:connector-curvature="0" + inkscape:export-filename="/home/sdx/Pictures/Logo/triskel_iot_bzh_300dpi.png" + inkscape:export-xdpi="300" + inkscape:export-ydpi="300" /> + <rect + style="fill:none;stroke:none;display:inline" + id="rect4179" + width="205.71426" + height="197.14285" + x="328.57144" + y="513.79077" + inkscape:export-filename="/home/sdx/Pictures/Logo/triskel_iot_bzh_300dpi.png" + inkscape:export-xdpi="300" + inkscape:export-ydpi="300" /> + </g> +</svg> diff --git a/doc/updt.sh b/doc/updt.sh new file mode 100755 index 0000000..a6292c8 --- /dev/null +++ b/doc/updt.sh @@ -0,0 +1,25 @@ +#!/bin/sh + +fmd() { +cat << EOC +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +$(cat) +</body> +</html> +EOC +} + + +for x in *.md; do + t=$(stat -c %Y $x) + t=$(git log -n 1 --format=%ct $x) + d=$(LANG= date -d @$t +"%d %B %Y") + sed -i "s/^\( Date: *\).*/\1$d/" $x + markdown -f toc,autolink $x | fmd > ${x%%.md}.html +done + diff --git a/doc/widgets.html b/doc/widgets.html new file mode 100644 index 0000000..2906bd0 --- /dev/null +++ b/doc/widgets.html @@ -0,0 +1,77 @@ +<html> +<head> + <link rel="stylesheet" type="text/css" href="doc.css"> + <meta charset="UTF-8"> +</head> +<body> +<a name="The.widgets"></a> +<h1>The widgets</h1> + +<pre><code>version: 1 +Date: 14 March 2016 +Author: José Bollo +</code></pre> + +<a name="The.widgets"></a> +<h2>The widgets</h2> + +<p>The widgets are described by the technical recommendations +<a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a>.</p> + +<a name="signature.of.the"></a> +<h3>signature of the</h3> + +<p>The application framework</p> + +<p>This is the original part of our work here</p> + +<a name="directory.where.are.stored.applications"></a> +<h3>directory where are stored applications</h3> + +<p>Applications can be installed in few places: on the system itself or on an extension device. +For my phone, for example, it is the sd card.</p> + +<p>This translates to:</p> + +<ul> +<li>/usr/applications: for system wide applications</li> +<li>/opt/applications: for removable applications</li> +</ul> + + +<p>In the remaining of the document, these places are writen “APPDIR”.</p> + +<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> +</body> +</html> diff --git a/doc/widgets.md b/doc/widgets.md new file mode 100644 index 0000000..11a0da7 --- /dev/null +++ b/doc/widgets.md @@ -0,0 +1,86 @@ + +The widgets +=========== + + version: 1 + Date: 14 March 2016 + Author: José Bollo + +The widgets +----------- + +The widgets are described by the technical recommendations +[widgets] and [widgets-digsig]. + +### signature of the + +The application framework + +This is the original part of our work here + +### directory where are stored applications + +Applications can be installed in few places: on the system itself or on an extension device. +For my phone, for example, it is the sd card. + +This translates to: + + - /usr/applications: for system wide applications + - /opt/applications: for removable applications + +In the remaining of the document, these places are writen "APPDIR". + + +Organisation of directory of applications +========================================= + +The main path for applivcations are: APPDIR/PKGID/VER. + +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 + + + + +[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[openssl]: https://www.openssl.org "OpenSSL" +[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" +[json-c]: https://github.com/json-c/json-c "JSON-c" +[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" +[libzip]: http://www.nih.at/libzip "libzip" +[cmake]: https://cmake.org "CMake" +[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" +[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" +[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" + + + + |
