From ddd10705d70b598160a41d197f364d2f792359f5 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Tue, 15 Mar 2016 09:51:56 +0100 Subject: [PATCH] doc: create documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Create more documentation about afm-main. Change-Id: I8b73017b666ac42da248df4219ec7abc08c7e877 Signed-off-by: JosÃ© Bollo --- doc/afm-system-daemon.html | 79 +++ doc/afm-system-daemon.md | 91 ++++ doc/afm-user-daemon.html | 777 +++++++++++++++++++++++++++ doc/afm-user-daemon.md | 758 ++++++++++++++++++++++++++ doc/application-framework.html | 290 ++++++++++ framework.md => doc/application-framework.md | 183 +------ doc/doc.css | 9 + doc/overview.html | 290 ++++++++++ doc/overview.md | 310 +++++++++++ doc/security-framework.html | 46 ++ doc/security-framework.md | 60 +++ doc/triskel_iot_bzh.svg | 110 ++++ doc/updt.sh | 25 + doc/widgets.html | 77 +++ doc/widgets.md | 86 +++ 15 files changed, 3017 insertions(+), 174 deletions(-) create mode 100644 doc/afm-system-daemon.html create mode 100644 doc/afm-system-daemon.md create mode 100644 doc/afm-user-daemon.html create mode 100644 doc/afm-user-daemon.md create mode 100644 doc/application-framework.html rename framework.md => doc/application-framework.md (73%) create mode 100644 doc/doc.css create mode 100644 doc/overview.html create mode 100644 doc/overview.md create mode 100644 doc/security-framework.html create mode 100644 doc/security-framework.md create mode 100644 doc/triskel_iot_bzh.svg create mode 100755 doc/updt.sh create mode 100644 doc/widgets.html create mode 100644 doc/widgets.md 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 @@ + + + + + + + +

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?

+ + 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 @@ + + + + + + + +

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 +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 +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 +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 +of config.xml.
%n: name
+ +
Name of the application as defined by the content of the +element 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 +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/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 **** + 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 **** + 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 **** + 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 **** + of **config.xml**. + + - ***%n***: name + + Name of the application as defined by the content of the + element **** 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 **** + 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 @@ + + + + + + + +

Application framework

+ +

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, 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:

+ +

APPLICATION calls its binder to install the OTHER application.
The plugin afm-main-plugin of the binder calls, through +D-Bus system, the system daemon to install the OTHER application.
The system D-Bus checks wether APPLICATION has the permission +or not to install applications by calling CYNARA.
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.
afm-system-daemon calls SECURITY-MANAGER for fullfilling +security context of the installed application.
SECURITY-MANAGER calls CYNARA to install initial permissions +for the application.
APPLICATION call its binder to start the nearly installed OTHER application.
The plugin afm-main-plugin of the binder calls, through +D-Bus session, the user daemon to launch the OTHER application.
The session D-Bus checks wether APPLICATION has the permission +or not to start an application by calling CYNARA.
The session D-Bus transmits the request to afm-user-daemon.
afm-user-daemon checks wether APPLICATION has the permission +or not to start the OTHER application CYNARA.
afm-user-daemon uses SECURITY-MANAGER features to set +the seciruty context for the OTHER application.
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.

+ +

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

+ + diff --git a/framework.md b/doc/application-framework.md similarity index 73% rename from framework.md rename to 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 @@ + + + + + + + +

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

+ +

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

+ + +

+ +

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.

+ +

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.

+ +

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:

+ +

APPLICATION calls its binder to install the OTHER application.
The plugin afm-main-plugin of the binder calls, through +D-Bus system, the system daemon to install the OTHER application.
The system D-Bus checks wether APPLICATION has the permission +or not to install applications by calling CYNARA.
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.
afm-system-daemon calls SECURITY-MANAGER for fullfilling +security context of the installed application.
SECURITY-MANAGER calls CYNARA to install initial permissions +for the application.
APPLICATION call its binder to start the nearly installed OTHER application.
The plugin afm-main-plugin of the binder calls, through +D-Bus session, the user daemon to launch the OTHER application.
The session D-Bus checks wether APPLICATION has the permission +or not to start an application by calling CYNARA.
The session D-Bus transmits the request to afm-user-daemon.
afm-user-daemon checks wether APPLICATION has the permission +or not to start the OTHER application CYNARA.
afm-user-daemon uses SECURITY-MANAGER features to set +the seciruty context for the OTHER application.
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 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.

+ +

The security framework then comes from Tizen 3 but through +the meta-intel. +It includes: Security-Manager, Cynara +and D-Bus compliant to Cynara.

+ +

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.

+ +

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

+ + 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 @@ + + + + + + + +

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?

+ + 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 @@ + + + + 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 + + + + + + +$(cat) + + +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 @@ + + + + + + + +

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

+ + 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" + + + + -- 2.16.6