From 047a822596f07a7d367db9fc2ab00e0198650ebf Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Thu, 17 Nov 2016 17:36:51 +0100 Subject: [PATCH] Doc reworked, relifted Change-Id: If41313a44cb66c0aa0f315b264284d081ff87f8e Signed-off-by: Romain Forlot --- docs/{afm-user-daemon.md => afm-daemons.md} | 1058 +++++++++++++------------ docs/afm-system-daemon.md | 220 ----- 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 | 0 docs/quick-tutorial.md | 15 +- docs/widgets.md | 236 +++++- docs/writing-config.xml.md | 234 ------ mkdocs.yml | 10 +- 12 files changed, 1620 insertions(+), 1041 deletions(-) rename docs/{afm-user-daemon.md => afm-daemons.md} (72%) delete mode 100644 docs/afm-system-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 rename docs/{ => pictures}/triskel_iot_bzh.svg (100%) delete mode 100644 docs/writing-config.xml.md diff --git a/docs/afm-user-daemon.md b/docs/afm-daemons.md similarity index 72% rename from docs/afm-user-daemon.md rename to docs/afm-daemons.md index 37cf0e4..ca80d3c 100644 --- a/docs/afm-user-daemon.md +++ b/docs/afm-daemons.md @@ -1,575 +1,249 @@ - -The afm-user-daemon -=================== +The application framework daemons +================================= Foreword -------- -This document describes application framework user daemon fundamentals. +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 ------------ -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 | - +------------------------------------------------------------+ +Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications +life. Understand that they will manage operations like: + - ***installation*** + - ***uninstallation*** + - ***running*** + - ***suspend*** + - ***inventory*** + - ... -Tasks of **afm-user-daemon** ----------------------------- +In addition, they ensure that operations use the security framework as needed +and that applications are executed in the correct context. -### Maintaining list of applications ### +***D-Bus*** is in charge of transmitting orders to the appropriate daemon +depending upon ***D-Bus*** destination. -At start **afm-user-daemon** scans the directories containing -applications and load in memory a list of avaliable applications -accessible by current user. +The figure below summarizes the situation of both **afm-system-daemon** and +**afm-user-daemon** in the system. -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-daemons][afm-daemons] -**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. +The D-Bus interface +------------------- -### Launching application ### +### Overview of the dbus interface -**afm-user-daemon** launches application. Its builds a secure -environment for the application before starting it within a -secured environment. +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. -Different kind of applications can be launched. +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. -This is set using a configuration file that describes -how to launch an application of a given kind within a given -mode. +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***: -There is two launching modes: local or remote. + - ***install*** + - ***uninstall*** -Launching an application locally means that -the application and its binder are launched together. +And for ***afm-user-daemon***: -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) + - ***runnables*** + - ***detail*** + - ***start*** + - ***once*** + - ***terminate*** + - ***pause*** + - ***resume*** + - ***runners*** + - ***state*** + - ***install*** + - ***uninstall*** -Once launched, running instances of application receive -a runid that identify them. +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. -### Managing instances of running applications ### +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. -**afm-user-daemon** manages the list of applications -that it launched. +Here are examples using *dbus-send*, here to install an application from a +widget file: -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. + dbus-send --session --print-reply \ + --dest=org.AGL.afm.system \ + /org/AGL/afm/system \ + org.AGL.afm.system.install 'string:"/tmp/appli.wgt" -### Installing and uninstalling applications ### -If the client own the right permissions, -**afm-user-daemon** delegates that task -to **afm-system-daemon**. +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 -Starting **afm-user-daemon** ------------------------------ +### The protocol over D-Bus -**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. +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 options for launching **afm-user-daemon** are: +The D-Bus interface is defined by: - -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. + * **DESTINATION**: org.AGL.afm.[user|system] - 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. - + * **PATH**: /org/AGL/afm/[user|system] -Launcher Configuration ------------------------------ + * **INTERFACE**: org.AGL.afm.[user|system] -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. +#### Method org.AGL.afm.system.install -This tuple mode+type allows to select the adequate rule. +**Description**: Install an application from a widget file. -Configuration file is **/etc/afm/afm-launch.conf**. +When an application with the same *id* and *version* already exists. Outside of +using *force=true* the application is not reinstalled. -It contains sections and rules. It can also contain comments -and empty lines to improve readability. +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. -The separators are space and tabulation, any other character -should have a meaning. +Note that this methods is a simple accessor method of +***org.AGL.afm.system.install*** from ***afm-system-daemon***. -The format is line oriented. -The new line character separate the lines. +After the installation and before returning to the sender, +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. -Lines having only separators are blank lines and ignored. -Line having character #(sharp) at first position are comment -lines and ignored. +**Input**: The *path* of the widget file to install and, optionally, +a flag to *force* reinstallation, and, optionally, a *root* directory. -Lines not starting with a separator are different -from lines starting with a separator character. +Either just a string being the absolute path of the widget file: -The grammar of the configuration file is defined below: + "/a/path/driving/to/the/widget" - 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 +Or an object: - EOL: NL *COMMENT - COMMENT: *SEP CMT *(SEP | NCHAR) NL + { + "wgt": "/a/path/to/the/widget", + "force": false, + "root": "/a/path/to/the/root" + } - 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: +"wgt" and "root" must be absolute paths. - 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 +**output**: An object with the field "added" being the string for +the id of the added application. -This shows that: + {"added":"appli@x.y"} - - 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 +#### Method org.AGL.afm.system.uninstall -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. +**Description**: Uninstall an application from its id. -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 +Note that this methods is a simple method accessor of +***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***. -Within this mode, the launchers have either one or two vectors -describing them. +After the uninstallation and before returning to the sender, +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. -The first vector is process as a program and is executed with -system call 'execve'. +**Input**: the *id* of the application and optionally the application *root* path. -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. +Either a string: -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. + "appli@x.y" -### %substitutions +Or an object: -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. + { + "id": "appli@x.y", + "root": "/a/path/to/the/root" + } -Here is the list of *%substitutions*: +**output**: the value 'true'. - - ***%%***: %. +--- - This simply emits the percent sign % +#### Method org.AGL.afm.user.detail - - ***%a***: appid - Holds application Id of launched application. +**Description**: Get details about an application from its id. - Defined by the attribute **id** of the element **** - of **config.xml**. +**Input**: the id of the application as below. - - ***%b***: bindings +Either just a string: - In the future should represent the list of bindings and bindings directory separated by ','. - Warning: not supported in current version. + "appli@x.y" - - ***%c***: content +Or an object having the field "id" of type string: - The file within the widget directory that is the entry point. + {"id":"appli@x.y"} - For HTML applications, it represents the relative path to main - page (aka index.html). +**Output**: A JSON object describing the application containing +the fields described below. - Defined by attribute **src** of the element **** within **config.xml**. + { + "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 + } - - ***%D***: datadir +--- - Path of the directory where the application runs (cwd) - and stores its data. +#### Method org.AGL.afm.user.runnables - It is equal to %h/%a. +**Description**: Get the list of applications that can be run. - - ***%H***: height +**Input**: any valid json entry, can be anything except null. - Requested height for the widget. +**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*. - Defined by the attribute **height** of the element **** - of **config.xml**. +--- - - ***%h***: homedir +#### Method org.AGL.afm.user.install - Path of the home directory for all applications. +**Description**: Install an application from its widget file. - It is generally equal to $HOME/app-data +If an application of the same *id* and *version* exists, it is not +reinstalled except when *force=true*. - - ***%I***: icondir +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*. - Path of the directory were the icons of the applications can be found. +Note that this methods is a simple accessor to the method +***org.AGL.afm.system.install*** of ***afm-system-daemon***. - - ***%m***: mime-type +After the installation and before returning to the sender, +***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. - Mime type of the launched application. +**Input**: The *path* of widget file to be installed. Optionally, +a flag to *force* reinstallation and/or a *root* directory. - Defined by the attribute **type** of the element **** - of **config.xml**. +Simple form a simple string containing the absolute widget path: - - ***%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" + "/a/path/driving/to/the/widget" Or an object: @@ -579,7 +253,7 @@ Or an object: "root": "/a/path/to/the/root" } -"wgt" and "root" MUST be absolute paths. +***wgt*** and ***root*** MUST be absolute paths. **output**: An object containing field "added" to use as application ID. @@ -735,5 +409,417 @@ Example of returned state: **Input**: anything. **output**: An array of states, one per running instance, as returned by -the methodd ***org.AGL.afm.user.state***. +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/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/triskel_iot_bzh.svg b/docs/pictures/triskel_iot_bzh.svg similarity index 100% rename from docs/triskel_iot_bzh.svg rename to docs/pictures/triskel_iot_bzh.svg 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/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" - diff --git a/mkdocs.yml b/mkdocs.yml index 065b230..1102944 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,10 +4,8 @@ docs_dir: docs pages: - 'Overview' : 'index.md' - 'Quick tutorial' : 'quick-tutorial.md' - - 'The system daemon' : 'afm-system-daemon.md' - - 'The user daemon' : 'afm-user-daemon.md' + - 'The frameworks' : + - 'The application framework': 'application-framework.md' + - 'The security framework': 'security-framework.md' + - 'The afm daemons' : 'afm-daemons.md' - 'Widgets of the framework' : 'widgets.md' - - 'Writing widget''s configuration' : 'writing-config.xml.md' - - 'The security framework' : 'security-framework.md' - - 'The application framework' : 'application-framework.md' - -- 2.16.6