From 047a822596f07a7d367db9fc2ab00e0198650ebf Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Thu, 17 Nov 2016 17:36:51 +0100 Subject: Doc reworked, relifted Change-Id: If41313a44cb66c0aa0f315b264284d081ff87f8e Signed-off-by: Romain Forlot --- docs/afm-daemons.md | 825 ++++++++++++++++++++++++++ docs/afm-system-daemon.md | 220 ------- docs/afm-user-daemon.md | 739 ----------------------- docs/application-framework.md | 25 +- docs/overview.md | 69 +-- docs/pictures/AppFW-APP_install_sequences.svg | 408 +++++++++++++ docs/pictures/Security_model_history.svg | 149 +++++ docs/pictures/afm-daemons.svg | 237 ++++++++ docs/pictures/triskel_iot_bzh.svg | 110 ++++ docs/quick-tutorial.md | 15 +- docs/triskel_iot_bzh.svg | 110 ---- docs/widgets.md | 236 +++++++- docs/writing-config.xml.md | 234 -------- 13 files changed, 1979 insertions(+), 1398 deletions(-) create mode 100644 docs/afm-daemons.md delete mode 100644 docs/afm-system-daemon.md delete mode 100644 docs/afm-user-daemon.md create mode 100644 docs/pictures/AppFW-APP_install_sequences.svg create mode 100644 docs/pictures/Security_model_history.svg create mode 100644 docs/pictures/afm-daemons.svg create mode 100644 docs/pictures/triskel_iot_bzh.svg delete mode 100644 docs/triskel_iot_bzh.svg delete mode 100644 docs/writing-config.xml.md (limited to 'docs') diff --git a/docs/afm-daemons.md b/docs/afm-daemons.md new file mode 100644 index 0000000..ca80d3c --- /dev/null +++ b/docs/afm-daemons.md @@ -0,0 +1,825 @@ +The application framework daemons +================================= + +Foreword +-------- + +This document describes application framework daemons +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications. + +Introduction +------------ + +Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications +life. Understand that they will manage operations like: + + - ***installation*** + - ***uninstallation*** + - ***running*** + - ***suspend*** + - ***inventory*** + - ... + +In addition, they ensure that operations use the security framework as needed +and that applications are executed in the correct context. + +***D-Bus*** is in charge of transmitting orders to the appropriate daemon +depending upon ***D-Bus*** destination. + +The figure below summarizes the situation of both **afm-system-daemon** and +**afm-user-daemon** in the system. + +![afm-daemons][afm-daemons] + +The D-Bus interface +------------------- + +### Overview of the dbus interface + +The ***afm daemons*** takes theirs 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 session is by default addressed by environment +variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd** +variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for +user sessions. + +They are listening with the destination name ***org.AGL.afm.[user|system]*** +at the object of path ***/org/AGL/afm/[user|system]*** on the interface +***org.AGL.afm.[user|system]*** for the below detailed members for the +***afm-system-daemon***: + + - ***install*** + - ***uninstall*** + +And for ***afm-user-daemon***: + + - ***runnables*** + - ***detail*** + - ***start*** + - ***once*** + - ***terminate*** + - ***pause*** + - ***resume*** + - ***runners*** + - ***state*** + - ***install*** + - ***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 serialization to +exchange data. Signature of any member of the D-Bus interface is +***string -> string*** for ***JSON -> JSON***. This is the normal case, if there +is an error, current implementation returns a dbus error that is a string. + +Here are examples using *dbus-send*, here to install an application from a +widget file: + + dbus-send --session --print-reply \ + --dest=org.AGL.afm.system \ + /org/AGL/afm/system \ + org.AGL.afm.system.install 'string:"/tmp/appli.wgt" + + +And here, to query data on installed applications that can be run: + + dbus-send --session --print-reply \ + --dest=org.AGL.afm.user \ + /org/AGL/afm/user \ + org.AGL.afm.user.runnables string:true + +### The protocol over D-Bus + +On all following sub-chapters we assume that we talk about either +***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters +are considered as self-explanatory. + +The D-Bus interface is defined by: + + * **DESTINATION**: org.AGL.afm.[user|system] + + * **PATH**: /org/AGL/afm/[user|system] + + * **INTERFACE**: org.AGL.afm.[user|system] + +#### Method org.AGL.afm.system.install + +**Description**: Install an application from a widget file. + +When an application with the same *id* and *version* already exists. Outside of +using *force=true* the application is not reinstalled. + +Applications are installed the subdirectories of applications common directory. +If *root* is specified, the application is installed under the +sub-directories of the *root* defined. + +Note that this methods is a simple accessor method of +***org.AGL.afm.system.install*** from ***afm-system-daemon***. + +After the installation and before returning to the sender, +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. + +**Input**: The *path* of the widget file to install and, optionally, +a flag to *force* reinstallation, and, optionally, a *root* directory. + +Either just a string being the absolute path of the widget file: + + "/a/path/driving/to/the/widget" + +Or an object: + + { + "wgt": "/a/path/to/the/widget", + "force": false, + "root": "/a/path/to/the/root" + } + +"wgt" and "root" must be absolute paths. + +**output**: An object with the field "added" being the string for +the id of the added application. + + {"added":"appli@x.y"} + +--- + +#### Method org.AGL.afm.system.uninstall + +**Description**: Uninstall an application from its id. + + +Note that this methods is a simple method accessor of +***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***. + +After the uninstallation and before returning to the sender, +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. + +**Input**: the *id* of the application and optionally the application *root* path. + +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.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 when *force=true*. + +Applications are installed in the subdirectories of the common directory +reserved for applications. +If *root* is specified, the application is installed under +sub-directories of defined *root*. + +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 widget file to be installed. Optionally, +a flag to *force* reinstallation and/or a *root* directory. + +Simple form a simple string containing the absolute widget path: + + "/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 containing field "added" to use as application ID. + + {"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 +***org.AGL.afm.system.uninstall*** method from ***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, optionally, the path to +application *root*. + +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, optionally, the +start *mode* as below. + +Either just a string: + + "appli@x.y" + +Or an object containing field "id" of type string and +optionally a field mode: + + {"id":"appli@x.y","mode":"local"} + +The field "mode" is a string equal to either "local" or "remote". + +**output**: The *runid* of the application launched. *runid* is an integer. + +--- + +#### Method org.AGL.afm.user.once + +**Description**: + +**Input**: the *id* of the application + +Either just a string: + + "appli@x.y" + +Or an object containing field "id" of type string. + + {"id":"appli@x.y"} + +**output**: The *state* of the application retrieved or launched. +See *org.AGL.afm.user.state* to get a description of the returned +object. + +--- + +#### Method org.AGL.afm.user.terminate + +**Description**: Terminates the application attached to *runid*. + +**Input**: The *runid* (an integer) of running instance to terminate. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.stop + +Obsolete since 8th November 2016 (2016/11/08). +Kept for compatibility. + +Use **org.AGL.afm.user.pause** instead. + +--- + +#### Method org.AGL.afm.user.continue + +Obsolete since 8th November 2016 (2016/11/08). +Kept for compatibility. + +Use **org.AGL.afm.user.resume** instead. + +--- + +#### Method org.AGL.afm.user.pause + +**Description**: Pauses the application attached to *runid* until terminate or resume. + +**Input**: The *runid* (integer) of the running instance to pause. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.resume + +**Description**: Resumes the application attached to *runid* previously paused. + +**Input**: The *runid* (integer) of the running instance to resume. + +**output**: the value 'true'. + +--- + +#### Method org.AGL.afm.user.state + +**Description**: Get informations about a running instance of *runid*. + +**Input**: The *runid* (integer) of the running instance inspected. + +**output**: An object describing instance state. It contains: +the runid (integer), the pids of the processes as an array starting +with the group leader, the id of the running application (string), +the state of the application (string either: "starting", "running", "paused"). + +Example of returned state: + + { + "runid": 2, + "pids": [ 435, 436 ], + "state": "running", + "id": "appli@x.y" + } + +--- + +#### Method org.AGL.afm.user.runners + +**Description**: Get the list of currently running instances. + +**Input**: anything. + +**output**: An array of states, one per running instance, as returned by +the method ***org.AGL.afm.user.state***. + +Starting **afm daemons** +---------------------- + +***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd +services attached to system and user respectively. Normally, service files are +locatedat */lib/systemd/system/afm-system-daemon.service* and +*/lib/systemd/user/afm-user-daemon.service*. + +### ***afm-system-daemon*** options + +The options for launching **afm-system-daemon** are: + + -r + --root directory + + Set the root application directory. + + Note that the default root directory is defined + to be /usr/share/afm/applications (may change). + + -d + --daemon + + Daemonizes the process. It is not needed by sytemd. + + -q + --quiet + + Reduces the verbosity (can be repeated). + + -v + --verbose + + Increases the verbosity (can be repeated). + + -h + --help + + Prints a short help. + +### ***afm-user-daemon*** options + +The options for launching **afm-user-daemon** are: + + -a + --application directory + + Includes the given application directory to + the database base of applications. + + Can be repeated. + + -r + --root directory + + Includes root application directory or directories when + passing multiple rootdir to + applications database. + + Note that default root directory for + applications is always added. In current version + /usr/share/afm/applications is used as default. + + -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. + +Tasks of **afm-user-daemon** +---------------------------- + +### Maintaining list of applications + +At start **afm-user-daemon** scans the directories containing +applications and load in memory a list of avaliable applications +accessible by current user. + +When **afm-system-daemon** installs or removes an application. +On success it sends the signal *org.AGL.afm.system.changed*. +When receiving such a signal, **afm-user-daemon** rebuilds its +applications list. + +**afm-user-daemon** provides the data it collects about +applications to its clients. Clients may either request the full list +of avaliable applications or a more specific information about a +given application. + +### Launching application + +**afm-user-daemon** launches application. Its builds a secure +environment for the application before starting it within a +secured environment. + +Different kind of applications can be launched. + +This is set using a configuration file that describes +how to launch an application of a given kind within a given +mode. + +There is two launching modes: local or remote. + +Launching an application locally means that +the application and its binder are launched together. + +Launching application remotely translates in only launching +the application binder. The UI by itself has to be activated +remotely by the requested (ie: HTML5 homescreen in a browser) + +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. + +When owning the right permissions, a client can get the list +of running instances and details about a specific +running instance. It can also terminate, pause or +resume a given application. + +### Installing and uninstalling applications + +If the client own the right permissions, +**afm-user-daemon** delegates that task +to **afm-system-daemon**. + +Launcher Configuration +---------------------- + +It contains rules for launching applications. +When **afm-user-daemon** has to launch an application, +it looks for launch mode (local or remote), as well as +for the type of application describe in ***config.xml*** +widget configuration file. + +This tuple mode+type allows to select the adequate rule. + +Configuration file is **/etc/afm/afm-launch.conf**. + +It contains sections and rules. It can also contain comments +and empty lines to improve readability. + +The separators are space and tabulation, any other character +should have a meaning. + +The format is line oriented. +The new line character separate the lines. + +Lines having only separators are blank lines and ignored. +Line having character #(sharp) at first position are comment +lines and ignored. + +Lines not starting with a separator are different +from 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 of types *application/x-executable*, +*text/x-shellscript* and *text/html* in local mode: + + 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 description vectors. +All of those vectors are treated as programs +and are executed with 'execve' system call. + +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 process as a program and is executed with +system call 'execve'. + +The second vector (if any) defines a text that is returned +to the caller. This mechanism can be used to return a uri +for remote UI to connect on the newly launched application. + +The daemon ***afm-user-daemon*** allocates a port for each +new remote application. +The current implementation port allocation is incremental. +A smarter (cacheable and discoverable) allocation should 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 + + Holds application Id of launched application. + + Defined by the attribute **id** of the element **** + of **config.xml**. + + - ***%b***: bindings + + In the future should represent the list of bindings and bindings directory separated by ','. + Warning: not supported in current version. + + - ***%c***: content + + The file within the widget directory that is the entry point. + + For HTML applications, it represents the relative path to main + page (aka index.html). + + Defined by attribute **src** of the element **** within **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***: 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 file descriptor to use for signaling + readiness of launched process. + + - ***%r***: rootdir + + Path of directory containing the widget and its data. + + - ***%S***: secret + + An hexadecimal number that can be used to initialize pairing of client + and application binder. + + - ***%W***: width + + Requested width for the widget. + + Defined by the attribute **width** of the element **** + of **config.xml**. + +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 when requires attached arguments. + +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 once id **: + + run once an instance of the widget of id + + - **afm-util terminate rid **: + + terminate the running instance rid + + - **afm-util pause rid **: + + pause the running instance rid + + - **afm-util resume rid **: + + resume the previously paused rid + + - **afm-util state rid **: + + get status of the running instance rid + + +Here is how to list applications using ***afm-util***: + + afm-util runnables + + +[afm-daemons]: pictures/afm-daemons.svg "afm daemons location in the system" diff --git a/docs/afm-system-daemon.md b/docs/afm-system-daemon.md deleted file mode 100644 index f7f9b3d..0000000 --- a/docs/afm-system-daemon.md +++ /dev/null @@ -1,220 +0,0 @@ - -The afm-system-daemon -===================== - -Foreword --------- - -This document describes application framework system daemon fundamentals. -FCF (Fully Conform to Specification) implementation is still under development. -It may happen that current implementation somehow diverges with specifications. - - -Introduction ------------- - -The daemon **afm-system-daemon** is in charge of installing -applications on AGL system. Its main tasks are: - - - installs applications and setup security framework - for newly installed application. - - - uninstall applications - -The **afm-system-daemon** takes its orders from system -instance of D-Bus. - -The figure below summarizes the situation of **afm-system-daemon** in the system. - - +------------------------------------------------------------+ - | User | - | | - | +-------------------------------------------------+ | - | | | | - | | afm-user-daemon | | - | | | | - | +----------+----------------------+----------+----+ | - | | | : | - | | | : | - :================|======================|==========:=========: - | | | : | - | +----------+----------+ +-----+-----+ : | - | | D-Bus system +-----+ CYNARA | : | - | +----------+----------+ +-----+-----+ : | - | | | : | - | +----------+---------+ +-------+----------+----+ | - | | afm-system-daemon +----+ SECURITY-MANAGER | | - | +--------------------+ +-----------------------+ | - | | - | System | - +------------------------------------------------------------+ - - -Starting **afm-system-daemon** ------------------------------- - -**afm-system-daemon** is launched as a **systemd** service -attached to system. Normally, the service file is -located at /lib/systemd/system/afm-system-daemon.service. - -The options for launching **afm-system-daemon** are: - - -r - --root directory - - Set the root application directory. - - Note that the default root directory is defined - to be /usr/share/afm/applications (may change). - - -d - --daemon - - Daemonizes the process. It is not needed by sytemd. - - -q - --quiet - - Reduces the verbosity (can be repeated). - - -v - --verbose - - Increases the verbosity (can be repeated). - - -h - --help - - Prints a short help. - -The D-Bus interface -------------------- - -### Overview of the dbus interface - -***afm-system-daemon*** takes its orders from the session instance -of D-Bus. The use of D-Bus is great because it allows to implement -discovery and signaling. - -The **afm-system-daemon** is listening with the destination name -***org.AGL.afm.system*** at the object of path ***/org/AGL/afm/system*** -on the interface ***org.AGL.afm.system*** for the below detailed -members ***install*** and ***uninstall***. - -D-Bus is mainly used for signaling and discovery. Its optimized -typed protocol is not used except for transmitting only one string -in both directions. - -The client and the service are using JSON serialization to -exchange data. - -The D-Bus interface is defined by: - - * DESTINATION: **org.AGL.afm.system** - - * PATH: **/org/AGL/afm/system** - - * INTERFACE: **org.AGL.afm.system** - -The signature of any member of the interface is ***string -> string*** -for ***JSON -> JSON***. - -This is the normal case. In case of error, the current implementation -returns a dbus error that is a string. - -Here is an example using *dbus-send* to query data on -installed applications. - - dbus-send --session --print-reply \ - --dest=org.AGL.afm.system \ - /org/AGL/afm/system \ - org.AGL.afm.system.install 'string:"/tmp/appli.wgt"' - -### The protocol over D-Bus - ---- - -#### Method org.AGL.afm.system.install - -**Description**: Install an application from a widget file. - -When an application with the same *id* and *version* already exists. Outside of -using *force=true* the application is not reinstalled. - -Applications are installed the subdirectories of applications common directory. -If *root* is specified, the application is installed under the -sub-directories of the *root* defined. - -Note that this methods is a simple accessor method of -***org.AGL.afm.system.install*** from ***afm-system-daemon***. - -After the installation and before returning to the sender, -***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. - -**Input**: The *path* of the widget file to install and, optionally, -a flag to *force* reinstallation, and, optionally, a *root* directory. - -Either just a string being the absolute path of the widget file: - - "/a/path/driving/to/the/widget" - -Or an object: - - { - "wgt": "/a/path/to/the/widget", - "force": false, - "root": "/a/path/to/the/root" - } - -"wgt" and "root" must be absolute paths. - -**output**: An object with the field "added" being the string for -the id of the added application. - - {"added":"appli@x.y"} - ---- - -#### Method org.AGL.afm.system.uninstall - -**Description**: Uninstall an application from its id. - - -Note that this methods is a simple method accessor of -***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***. - -After the uninstallation and before returning to the sender, -***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. - -**Input**: the *id* of the application and optionally the application *root* path. - -Either a string: - - "appli@x.y" - -Or an object: - - { - "id": "appli@x.y", - "root": "/a/path/to/the/root" - } - -**output**: the value 'true'. - -[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/docs/afm-user-daemon.md b/docs/afm-user-daemon.md deleted file mode 100644 index 37cf0e4..0000000 --- a/docs/afm-user-daemon.md +++ /dev/null @@ -1,739 +0,0 @@ - -The afm-user-daemon -=================== - -Foreword --------- - -This document describes application framework user daemon fundamentals. -FCF (Fully Conform to Specification) implementation is still under development. -It may happen that current implementation somehow diverges with specifications. - - -Introduction ------------- - -The daemon **afm-user-daemon** is in charge of handling -applications on behalf of a user. Its main tasks are: - - - enumerate applications that end user can run - and keep this list available on demand - - - start applications on behalf of end user, set user running - environment, set user security context - - - list current runnable or running applications - - - pause, resume, terminate a running instance of a given application - - - transfer requests for installation/uninstallation - of applications to the corresponding 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 **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 -applications and load in memory a list of avaliable applications -accessible by current user. - -When **afm-system-daemon** installs or removes an application. -On success it sends the signal *org.AGL.afm.system.changed*. -When receiving such a signal, **afm-user-daemon** rebuilds its -applications list. - -**afm-user-daemon** provides the data it collects about -applications to its clients. Clients may either request the full list -of avaliable applications or a more specific information about a -given application. - -### Launching application ### - -**afm-user-daemon** launches application. Its builds a secure -environment for the application before starting it within a -secured environment. - -Different kind of applications can be launched. - -This is set using a configuration file that describes -how to launch an application of a given kind within a given -mode. - -There is two launching modes: local or remote. - -Launching an application locally means that -the application and its binder are launched together. - -Launching application remotely translates in only launching -the application binder. The UI by itself has to be activated -remotely by the requested (ie: HTML5 homescreen in a browser) - -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. - -When owning the right permissions, a client can get the list -of running instances and details about a specific -running instance. It can also terminate, pause or -resume a given application. - -### Installing and uninstalling applications ### - -If the client own the right permissions, -**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. - - Can be repeated. - - -r - --root directory - - Includes root application directory or directories when - passing multiple rootdir to - applications database. - - Note that default root directory for - applications is always added. In current version - /usr/share/afm/applications is used as default. - - -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. - - -Launcher Configuration ------------------------------ - -It contains rules for launching applications. -When **afm-user-daemon** has to launch an application, -it looks for launch mode (local or remote), as well as -for the type of application describe in ***config.xml*** -widget configuration file. - -This tuple mode+type allows to select the adequate rule. - -Configuration file is **/etc/afm/afm-launch.conf**. - -It contains sections and rules. It can also contain comments -and empty lines to improve readability. - -The separators are space and tabulation, any other character -should have a meaning. - -The format is line oriented. -The new line character separate the lines. - -Lines having only separators are blank lines and ignored. -Line having character #(sharp) at first position are comment -lines and ignored. - -Lines not starting with a separator are different -from 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 of types *application/x-executable*, -*text/x-shellscript* and *text/html* in local mode: - - 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 description vectors. -All of those vectors are treated as programs -and are executed with 'execve' system call. - -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 process as a program and is executed with -system call 'execve'. - -The second vector (if any) defines a text that is returned -to the caller. This mechanism can be used to return a uri -for remote UI to connect on the newly launched application. - -The daemon ***afm-user-daemon*** allocates a port for each -new remote application. -The current implementation port allocation is incremental. -A smarter (cacheable and discoverable) allocation should 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 - - Holds application Id of launched application. - - Defined by the attribute **id** of the element **** - of **config.xml**. - - - ***%b***: bindings - - In the future should represent the list of bindings and bindings directory separated by ','. - Warning: not supported in current version. - - - ***%c***: content - - The file within the widget directory that is the entry point. - - For HTML applications, it represents the relative path to main - page (aka index.html). - - Defined by attribute **src** of the element **** within **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***: 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 file descriptor to use for signaling - readiness of launched process. - - - ***%r***: rootdir - - Path of directory containing the widget and its data. - - - ***%S***: secret - - An hexadecimal number that can be used to initialize pairing of client - and application 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. D-Bus is nice to use in this context because it allows -discovery and signaling. - -The dbus session is by default addressed by environment -variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd** -variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for -user sessions. - -The **afm-user-daemon** is listening on destination name -***org.AGL.afm.user*** at object path ***/org/AGL/afm/user*** -on interface ***org.AGL.afm.user*** for following members: - ***runnables***, ***detail***, ***start***, ***once***, ***terminate***, -***pause***, ***resume***, ***runners***, ***state***, -***install*** and ***uninstall***. - -D-Bus is mainly used for signaling and discovery. Its optimized -typed protocol is not used except for transmission of standalone strings. - -Clients and Services 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 implementation -returns a dbus error as a string. - -Here an example using *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 when requires attached arguments. - -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 once id **: - - run once an instance of the widget of id - - - **afm-util terminate rid **: - - terminate the running instance rid - - - **afm-util pause rid **: - - pause the running instance rid - - - **afm-util resume rid **: - - resume the previously paused 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 when *force=true*. - -Applications are installed in the subdirectories of the common directory -reserved for applications. -If *root* is specified, the application is installed under -sub-directories of defined *root*. - -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 widget file to be installed. Optionally, -a flag to *force* reinstallation and/or a *root* directory. - -Simple form a simple string containing the absolute widget path: - - "/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 containing field "added" to use as application ID. - - {"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 -***org.AGL.afm.system.uninstall*** method from ***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, optionally, the path to -application *root*. - -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, optionally, the -start *mode* as below. - -Either just a string: - - "appli@x.y" - -Or an object containing field "id" of type string and -optionally a field mode: - - {"id":"appli@x.y","mode":"local"} - -The field "mode" is a string equal to either "local" or "remote". - -**output**: The *runid* of the application launched. *runid* is an integer. - ---- - -#### Method org.AGL.afm.user.once - -**Description**: - -**Input**: the *id* of the application - -Either just a string: - - "appli@x.y" - -Or an object containing field "id" of type string. - - {"id":"appli@x.y"} - -**output**: The *state* of the application retrieved or launched. -See *org.AGL.afm.user.state* to get a description of the returned -object. - ---- - -#### Method org.AGL.afm.user.terminate - -**Description**: Terminates the application attached to *runid*. - -**Input**: The *runid* (an integer) of running instance to terminate. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.stop - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.pause** instead. - ---- - -#### Method org.AGL.afm.user.continue - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.resume** instead. - ---- - -#### Method org.AGL.afm.user.pause - -**Description**: Pauses the application attached to *runid* until terminate or resume. - -**Input**: The *runid* (integer) of the running instance to pause. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.resume - -**Description**: Resumes the application attached to *runid* previously paused. - -**Input**: The *runid* (integer) of the running instance to resume. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.state - -**Description**: Get informations about a running instance of *runid*. - -**Input**: The *runid* (integer) of the running instance inspected. - -**output**: An object describing instance state. It contains: -the runid (integer), the pids of the processes as an array starting -with the group leader, the id of the running application (string), -the state of the application (string either: "starting", "running", "paused"). - -Example of returned state: - - { - "runid": 2, - "pids": [ 435, 436 ], - "state": "running", - "id": "appli@x.y" - } - ---- - -#### Method org.AGL.afm.user.runners - -**Description**: Get the list of currently running instances. - -**Input**: anything. - -**output**: An array of states, one per running instance, as returned by -the methodd ***org.AGL.afm.user.state***. - diff --git a/docs/application-framework.md b/docs/application-framework.md index 0ebcdb7..fbd4513 100644 --- a/docs/application-framework.md +++ b/docs/application-framework.md @@ -38,14 +38,13 @@ future to include new feature (ie: incremental delivery). Comparison to other frameworks ------------------------------ -### Tizen framework + - Tizen framework -### xdg-app + - xdg-app -### ostro + - ostro -organization of directory of applications -========================================= +### Organization of directory of applications ### The main path for applications are: APPDIR/PKGID/VER. @@ -58,8 +57,7 @@ Where: The advantage of such an organization is to allow several versions to live together. This is required for multiple reasons (ie: roll back) and to comply with developers habits. -Identity of installed files ---------------------------- +#### Identity of installed files #### All the files are installed as user "userapp" and group "userapp". All files have rw(x) for user and r-(x) for group and others. @@ -67,17 +65,14 @@ All files have rw(x) for user and r-(x) for group and others. This allows any user to read files. -labeling the directories of applications ------------------------------------------ +#### Labeling the directories of applications #### -organization of data -==================== +### Organization of data ### The data of a user are contain within its directory and are labeled using the application labels -Setting Smack rules for the application -======================================= +### Setting Smack rules for the application ### For Tizen, the following rules are set by the security manager for each application. @@ -100,13 +95,11 @@ For Tizen, the following rules are set by the security manager for each applicat Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application. -What user can run an 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" diff --git a/docs/overview.md b/docs/overview.md index 99dcc1d..ad63dec 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,6 +1,5 @@ - -AGL framework, overview of the proposal of IoT.bzh -================================================== +AGL framework, IoT.bzh proposal overview +======================================== Foreword -------- @@ -30,7 +29,7 @@ Here is a minimal list of what was needed: - platform/core/appfw/pkgmgr-info - platform/core/appfw/slp-pkgmgr -But this list is complete because many dependencies are hidden. +But this list isn't 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, ...). @@ -56,15 +55,7 @@ The 3 layers are providing components for: The figure below shows the history of these layers. - - 2014 2015 - Tizen OBS ----------+---------------------------> - \ - \ - Tizen Yocto +---------+--------------> - \ - \ - meta-intel-iot-security +-----------> +![Security_model_history][Security_model_history] We took the decision to use these security layers that provides the basis of the Tizen security, the security framework. @@ -96,50 +87,7 @@ 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-binding | : | | | - | : +-----+--------------+--+ : +------^-------+------+---+ | - | :........|..............|......: | | : | - | |(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 | - +-----------------------------------------------------------------------+ +![AppFW-APP_install_sequences][AppFW-APP_install_sequences] Let follow the sequence of calls: @@ -267,11 +215,11 @@ 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. +recommendations [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 +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. @@ -293,4 +241,5 @@ futur to include for example incremental delivery. [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" - +[AppFW-APP_install_sequences]: pictures/AppFW-APP_install_sequences.svg (AppFW: APP installation sequences order) +[Security_model_history]: pictures/Security_model_history.svg (Security model history) diff --git a/docs/pictures/AppFW-APP_install_sequences.svg b/docs/pictures/AppFW-APP_install_sequences.svg new file mode 100644 index 0000000..e0cb250 --- /dev/null +++ b/docs/pictures/AppFW-APP_install_sequences.svg @@ -0,0 +1,408 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + System + + + + + + + + + + + + + + + User + + + + + + + + + + + D-Bus session + + + + + + + + + + SMACK isolatedother application + + + + + + + + + + SECURITY MANAGER + + + + + + + + + + afm-system-daemon + + + + + + + + + + CYNARA + + + + + + + + + + D-Bus system + + + + + + + + + + afm-user-daemon + + + + + + + + + + SMACK isolated Application + + + + + + + + + + + + + + + + + D-Bus session + + + + + + + + + + + binder afb-daemon + + + + + + + + + + afm-main-binding + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (1), (7) + + + + + + (2) + + + + + + (3) + + + + + + (4) + + + + + + (5) + + + + + + (6) + + + + + + (9) + + + + + + (11) + + + + + + (12) + + + + + + (10) + + + + + + (13) + + + + + + (8) + + + + + + + \ No newline at end of file diff --git a/docs/pictures/Security_model_history.svg b/docs/pictures/Security_model_history.svg new file mode 100644 index 0000000..7935437 --- /dev/null +++ b/docs/pictures/Security_model_history.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tizen OBS + + + + + + Tizen Yocto + + + + + + meta-intel-iot-security + + + + + + 2014 + + + + + + 2015 + + + + + + + \ No newline at end of file diff --git a/docs/pictures/afm-daemons.svg b/docs/pictures/afm-daemons.svg new file mode 100644 index 0000000..02b2c92 --- /dev/null +++ b/docs/pictures/afm-daemons.svg @@ -0,0 +1,237 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + System + + + + + + + + + + + + + + + User + + + + + + + + + + + D-Bus session + + + + + + + + + + SMACK isolatedApplication + + + + + + + + + + SECURITY MANAGER + + + + + + + + + + afm-system-daemon + + + + + + + + + + CYNARA + + + + + + + + + + D-Bus system + + + + + + + + + + afm-user-daemon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/pictures/triskel_iot_bzh.svg b/docs/pictures/triskel_iot_bzh.svg new file mode 100644 index 0000000..096f424 --- /dev/null +++ b/docs/pictures/triskel_iot_bzh.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/docs/quick-tutorial.md b/docs/quick-tutorial.md index f55d4d0..fd10d8a 100644 --- a/docs/quick-tutorial.md +++ b/docs/quick-tutorial.md @@ -5,18 +5,20 @@ AGL Application Framework: A Quick Tutorial Introduction ------------ This document proposes a quick tutorial to demonstrate the major functionnalities of the AGL Application Framework. For more complete information, please refer to the inline documentation available in the main git repository: -https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main -https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder + +[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main] +[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder] + For more information on AGL, please visit: -https://www.automotivelinux.org/ +[https://www.automotivelinux.org/] ---------- Sample applications ------------------- 4 sample applications (.wgt files) are prebuilt and available at the following address: -https://github.com/iotbzh/afm-widget-examples +[https://github.com/iotbzh/afm-widget-examples] You can get them by cloning this git repository on your desktop (will be useful later in this tutorial): @@ -216,3 +218,8 @@ Then you can access it from a browser: http://[board_ip]:1235/opa/?token=132456789 afb-client is a simple application to demonstrate the built-in capabilities of the binder daemon (handling sessions and security tokens, testing POSTs uploads...) and was used during the application framework development to validate the proposed features. + +[https://github.com/iotbzh/afm-widget-examples]: https://github.com/iotbzh/afm-widget-examples (afm-widget-examples) +[https://www.automotivelinux.org/]: https://www.automotivelinux.org/ (AGL) +[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder (app-framework-binder) +[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main (app-framework-main) diff --git a/docs/triskel_iot_bzh.svg b/docs/triskel_iot_bzh.svg deleted file mode 100644 index 096f424..0000000 --- a/docs/triskel_iot_bzh.svg +++ /dev/null @@ -1,110 +0,0 @@ - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - diff --git a/docs/widgets.md b/docs/widgets.md index 5637f2c..c23faa8 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -1,19 +1,30 @@ The widgets =========== -The widgets ------------ - The widgets are described by the technical recommendations [widgets] and [widgets-digsig]. In summary, **widgets are ZIP files that can be signed and whose content is described by the file **. -### The configuration file config.xml +The configuration file config.xml +--------------------------------- + +The file **config.xml** describes important data of the application +to the framework: -This is one of the important file of the widget. -It fully describes the widget. +- the unique identifier of the application +- the name of the application +- the type of the application +- the icon of the application +- the permissions linked to the application +- the services and dependancies of the application + +The file MUST be at the root of the widget and MUST be case sensitively name +***config.xml***. + +The file **config.xml** is a XML file described by the document +[widgets]. Here is the example of the config file for the QML application SmartHome. @@ -45,7 +56,193 @@ The most important items are: Further development will add handling of for requiring and providing permissions and services. -### Tools for managing widgets +--- + +### Standard elements of "config.xml" + +#### The element widget + +##### the attribute id of widget + +The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. + +Values for *id* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'_' (underscore). + +Authors can use a mnemonic id or can pick a unique id using +command **uuid** or **uuidgen**. + +#### the attribute version of widget + +The attribute *version* is mandatory (for version 2.x, blowfish). + +Values for *id* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'_' (underscore). + +Version values are dot separated fields MAJOR.MINOR.REVISION. + +#### The element content + +The element *content* is mandatory (for version 2.x, blowfish) and must designate a file +(subject to localisation) with its attribute *src*. + +The content designed depends on its type. See below for the known types. + +#### The element icon + +The element *icon* is mandatory (for version 2.x, blowfish) and must +be unique. It must designate an image file with its attribute *src*. + +### Known widget types and content + +The configuration file ***/etc/afm/afm-launch.conf*** defines the types +of widget known and how to launch it. + +Known types for the type of content are (for version 2.x, blowfish): + +- ***text/html***: + HTML application, + content.src designates the home page of the application + +- ***application/x-executable***: + Native application, + content.src designates the relative path of the binary + +- ***application/vnd.agl.url***: + Internet url, + content.src designates the url to be used + +- ***application/vnd.agl.service***: + AGL service defined as a binder, + content.src designates the directory of provided binders, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***application/vnd.agl.native***: + Native application with AGL service defined as a binder, + content.src designates the relative path of the binary, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***: + QML application, + content.src designate the relative path of the QML root, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.qml.hybrid***: + QML application with bindings, + content.src designate the relative path of the QML root, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.html.hybrid***: + HTML application, + content.src designates the home page of the application, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content must be put in the subdirectory ***htdocs*** of the widget + +--- + +### AGL features + +The AGL framework uses the feature tag for specifying security and binding +requirement of the widget. + +The current version of AGL (up to 2.0.1, blowfish) has no fully implemented +features. + +The features planned to be implemented are described below. + +#### feature name="urn:AGL:required-binding" + +List of the bindings required by the widget. + +Each required binding must be explicited using a entry. + +##### param name=[required binding name] + +The value is either: + +- required: the binding is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the binding is optional + +#### feature name="urn:AGL:required-permission" + +List of the permissions required by the widget. + +Each required permission must be explicited using a entry. + +##### param name=[required permission name] + +The value is either: + +- required: the permission is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the permission is optional + +#### feature name="urn:AGL:provided-binding" + +Use this feature for each provided binding of the widget. +The parameters are: + +##### param name="name" + +REQUIRED + +The value is the string that must match the binding prefix. +It must be unique. + +##### param name="src" + +REQUIRED + +The value is the path of the shared library for the binding. + +##### param name="type" + +REQUIRED + +Currently it must be ***application/vnd.agl.binding.v1***. + + +##### param name="scope" + +REQUIRED + +The value indicate the availability of the binidng: + +- private: used only by the widget +- public: available to allowed clients as a remote service (requires permission+) +- inline: available to allowed clients inside their binding (unsafe, requires permission+++) + +##### param name="needed-binding" + +OPTIONAL + +The value is a space separated list of binding's names that the binding needs. + +#### feature name="urn:AGL:defined-permission" + +Each required permission must be explicited using a entry. + +##### param name=[defined permission name] + +The value is the level of the defined permission. +Standard levels are: + +- system +- platform +- partner +- public + +This level defines the level of accreditation required to get the given +permission. The accreditions are given by signatures of widgets. + + +Tools for managing widgets +-------------------------- This project includes tools for managing widgets. These tools are: @@ -82,7 +279,16 @@ $ unzip WIDGET -d DIRECTORY *Note that DIRECTORY will be created if needed*. -### Signing a widget +Getting data about a widget file +--------------------------------- + +The command **wgtpkg-info** opens a widget file, reads its **config.xml** +file and displays its content in a human readable way. + +Signing and packing widget +-------------------------- + +### Signing To sign a widget, you need a private key and its certificate. @@ -103,7 +309,7 @@ Example 2: add a distributor signature $ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY ``` -### Packing a widget +### Packing This operation can be done using the command **zip** but we provide the tool **wgtpkg-pack** that may add checking. @@ -112,12 +318,6 @@ Example: ```bash $ wgtpkg-pack DIRECTORY -o file.wgt ``` - -### Getting data about a widget file - -The command **wgtpkg-info** opens a widget file, reads its **config.xml** -file and displays its content in a human readable way. - Writing a widget ---------------- @@ -185,6 +385,12 @@ This allows every user to read every file. The data of a user are in its directory and are labelled by the security-manager using the labels of the application. +[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" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" + + [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" diff --git a/docs/writing-config.xml.md b/docs/writing-config.xml.md deleted file mode 100644 index f74f8bc..0000000 --- a/docs/writing-config.xml.md +++ /dev/null @@ -1,234 +0,0 @@ -Writing the configuration file "config.xml" -=========================================== - -About "config.xml" ------------------- - -The file **config.xml** describes important data of the application -to the framework: - -- the unique identifier of the application -- the name of the application -- the type of the application -- the icon of the application -- the permissions linked to the application -- the services and dependancies of the application - -The file MUST be at the root of the widget and MUST be case sensitively name -***config.xml***. - -The file **config.xml** is a XML file described by the document -[widgets]. - -Example of "config.xml" ------------------------ - -Here is the example of the config file for the QML application SmartHome. - -```xml - - - SmartHome - - - - This is the Smarthome QML demo application. - It shows some user interfaces for controlling an automated house. - The user interface is completely done with QML. - - Qt team - GPL - -``` - -Standard elements of "config.xml" ---------------------------------- - -### The element widget - -#### the attribute id of widget - -The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'_' (underscore). - -Authors can use a mnemonic id or can pick a unique id using -command **uuid** or **uuidgen**. - -#### the attribute version of widget - -The attribute *version* is mandatory (for version 2.x, blowfish). - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'_' (underscore). - -Version values are dot separated fields MAJOR.MINOR.REVISION. - -### The element content - -The element *content* is mandatory (for version 2.x, blowfish) and must designate a file -(subject to localisation) with its attribute *src*. - -The content designed depends on its type. See below for the known types. - -### The element icon - -The element *icon* is mandatory (for version 2.x, blowfish) and must -be unique. It must designate an image file with its attribute *src*. - -Known widget types and content ------------------------------- - -The configuration file ***/etc/afm/afm-launch.conf*** defines the types -of widget known and how to launch it. - -Known types for the type of content are (for version 2.x, blowfish): - -- ***text/html***: - HTML application, - content.src designates the home page of the application - -- ***application/x-executable***: - Native application, - content.src designates the relative path of the binary - -- ***application/vnd.agl.url***: - Internet url, - content.src designates the url to be used - -- ***application/vnd.agl.service***: - AGL service defined as a binder, - content.src designates the directory of provided binders, - http content, if any, must be put in the subdirectory ***htdocs*** of the widget - -- ***application/vnd.agl.native***: - Native application with AGL service defined as a binder, - content.src designates the relative path of the binary, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - http content, if any, must be put in the subdirectory ***htdocs*** of the widget - -- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***: - QML application, - content.src designate the relative path of the QML root, - imports must be put in the subdirectory ***imports*** of the widget - -- ***application/vnd.agl.qml.hybrid***: - QML application with bindings, - content.src designate the relative path of the QML root, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - imports must be put in the subdirectory ***imports*** of the widget - -- ***application/vnd.agl.html.hybrid***: - HTML application, - content.src designates the home page of the application, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - http content must be put in the subdirectory ***htdocs*** of the widget - - -AGL features ------------- - -The AGL framework uses the feature tag for specifying security and binding -requirement of the widget. - -The current version of AGL (up to 2.0.1, blowfish) has no fully implemented -features. - -The features planned to be implemented are described below. - -### feature name="urn:AGL:required-binding" - -List of the bindings required by the widget. - -Each required binding must be explicited using a entry. - -#### param name=[required binding name] - -The value is either: - -- required: the binding is mandatorily needed except if the feature -isn't required (required="false") and in that case it is optional. -- optional: the binding is optional - -### feature name="urn:AGL:required-permission" - -List of the permissions required by the widget. - -Each required permission must be explicited using a entry. - -#### param name=[required permission name] - -The value is either: - -- required: the permission is mandatorily needed except if the feature -isn't required (required="false") and in that case it is optional. -- optional: the permission is optional - -### feature name="urn:AGL:provided-binding" - -Use this feature for each provided binding of the widget. -The parameters are: - -#### param name="name" - -REQUIRED - -The value is the string that must match the binding prefix. -It must be unique. - -#### param name="src" - -REQUIRED - -The value is the path of the shared library for the binding. - -#### param name="type" - -REQUIRED - -Currently it must be ***application/vnd.agl.binding.v1***. - - -#### param name="scope" - -REQUIRED - -The value indicate the availability of the binidng: - -- private: used only by the widget -- public: available to allowed clients as a remote service (requires permission+) -- inline: available to allowed clients inside their binding (unsafe, requires permission+++) - -#### param name="needed-binding" - -OPTIONAL - -The value is a space separated list of binding's names that the binding needs. - -### feature name="urn:AGL:defined-permission" - -Each required permission must be explicited using a entry. - -#### param name=[defined permission name] - -The value is the level of the defined permission. -Standard levels are: - -- system -- platform -- partner -- public - -This level defines the level of accreditation required to get the given -permission. The accreditions are given by signatures of widgets. - - - -[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" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" - -- cgit 1.2.3-korg