diff options
| -rw-r--r-- | docs/0-introduction.md | 191 | ||||
| -rw-r--r-- | docs/1-afm-daemons.md | 322 | ||||
| -rw-r--r-- | docs/2-widgets.md | 3 | ||||
| -rw-r--r-- | docs/2.1-widgets.md | 64 | ||||
| -rw-r--r-- | docs/2.2-config.xml.md | 276 | ||||
| -rw-r--r-- | docs/3-permissions.md | 161 | ||||
| -rw-r--r-- | docs/4-quick-tutorial.md | 236 | ||||
| -rw-r--r-- | docs/5-frameworks.md | 22 | ||||
| -rw-r--r-- | docs/5.1-application-framework.md | 39 | ||||
| -rw-r--r-- | docs/5.2-security-framework.md | 18 |
10 files changed, 695 insertions, 637 deletions
diff --git a/docs/0-introduction.md b/docs/0-introduction.md index bb89613..e78c091 100644 --- a/docs/0-introduction.md +++ b/docs/0-introduction.md @@ -1,18 +1,14 @@ -AGL framework overview -====================== +# AGL framework overview -Foreword --------- +## Foreword -This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ. +This document describes what we intend to do. +It may happen that our current implementation and the content of this document differ. In case of differences, it is assumed that this document is right and the implementation is wrong. - -Introduction ------------- +## Introduction During the first works in having the security model of Tizen integrated in AGL (Automotive Grade Linux) distribution, it became @@ -21,37 +17,47 @@ to integrate was huge. Here is a minimal list of what was needed: - - platform/appfw/app-installers - - platform/core/security/cert-svc - - platform/core/appfw/ail - - platform/core/appfw/aul-1 - - platform/core/appfw/libslp-db-util - - platform/core/appfw/pkgmgr-info - - platform/core/appfw/slp-pkgmgr +- platform/appfw/app-installers +- platform/core/security/cert-svc +- platform/core/appfw/ail +- platform/core/appfw/aul-1 +- platform/core/appfw/libslp-db-util +- platform/core/appfw/pkgmgr-info +- platform/core/appfw/slp-pkgmgr -But this list isn't 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, ...). +tizen specific sub-components: + +- iniparser +- bundle +- dlog, +- libtzplatform-config +- db-util +- vconf-buxton +- ... -This is an issue because AGL is not expected to be Tizen. Taking it would -either need to patch it for removing unwanted components or to take all -of them. +This is an issue because AGL is not expected to be Tizen. +Taking it would either need to patch it for removing unwanted components or to take all of them. However, a careful study of the core components of the security framework of Tizen showed that their dependencies to Tizen are light (and since some -of our work, there is no more dependency to tizen). -Those components are **cynara**, **security-manager**, **D-Bus aware of cynara**. +of our work, there is no more dependency to tizen). +Those components are : + +- **cynara** +- **security-manager** +- **D-Bus aware of cynara** Luckily, these core security components of Tizen are provided -by [meta-intel-iot-security][meta-intel], a set of yocto layers. +by [meta-intel-iot-security][meta-intel], a set of yocto layers. These layers were created by Intel to isolate Tizen specific security -components from the initial port of Tizen to Yocto. +components from the initial port of Tizen to Yocto. The 3 layers are providing components for: - * Implementing Smack LSM - * Implementing Integrity Measurement Architecture - * Implementing Tizen Security Framework +- Implementing Smack LSM +- Implementing Integrity Measurement Architecture +- Implementing Tizen Security Framework The figure below shows the history of these layers. @@ -66,26 +72,32 @@ from Tizen, we decided to refit it by developing a tiny set of components that would implement the same behaviour but without all the dependencies and with minor architectural improvements for AGL. -These components are **afm-system-daemon** and **afm-user-daemon**. +These components are : + +- **afm-system-daemon** +- **afm-user-daemon** + They provides infrastructure for installing, uninstalling, launching, terminating, pausing and resuming applications in a multi user secure environment. -A third component exists in the framework, the binder **afb-daemon**. +A third component exists in the framework, the binder **afb-daemon**. The binder provides the easiest way to provide secured API for -any tier. Currently, the use of the binder is not absolutely mandatory. +any tier. +Currently, the use of the binder is not absolutely mandatory. This documentation explains the framework created by IoT.bzh -by rewriting the Tizen Application Framework. Be aware of the -previous foreword. +by rewriting the Tizen Application Framework. +Be aware of the previous foreword. <!-- pagebreak --> -Overview --------- + +## Overview The figure below shows the major components of the framework and their interactions going through the following scenario: -APPLICATION installs an other application and then launch it. + +- APPLICATION installs an other application and then launch it. ![AppFW-APP_install_sequences][AppFW-APP_install_sequences]{style width:70%} @@ -93,115 +105,120 @@ Let follow the sequence of calls: 1. APPLICATION calls its **binder** to install the OTHER application. -2. The binding **afm-main-binding** of the **binder** calls, through +1. The binding **afm-main-binding** of the **binder** calls, through **D-Bus** system, the system daemon to install the OTHER application. -3. The system **D-Bus** checks wether APPLICATION has the permission +1. The system **D-Bus** checks wether APPLICATION has the permission or not to install applications by calling **CYNARA**. -4. The system **D-Bus** transmits the request to **afm-system-daemon**. +1. The system **D-Bus** transmits the request to **afm-system-daemon**. **afm-system-daemon** checks the application to install, its signatures and rights and install it. -5. **afm-system-daemon** calls **SECURITY-MANAGER** for fulfilling +1. **afm-system-daemon** calls **SECURITY-MANAGER** for fulfilling security context of the installed application. -6. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions +1. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions for the application. -7. APPLICATION call its binder to start the nearly installed OTHER application. +1. APPLICATION call its binder to start the nearly installed OTHER application. -8. The binding **afm-main-binding** of the **binder** calls, through +1. The binding **afm-main-binding** of the **binder** calls, through **D-Bus** session, the user daemon to launch the OTHER application. -9. The session **D-Bus** checks wether APPLICATION has the permission +1. The session **D-Bus** checks wether APPLICATION has the permission or not to start an application by calling **CYNARA**. -10. The session **D-Bus** transmits the request to **afm-user-daemon**. +1. The session **D-Bus** transmits the request to **afm-user-daemon**. -11. **afm-user-daemon** checks wether APPLICATION has the permission +1. **afm-user-daemon** checks wether APPLICATION has the permission or not to start the OTHER application **CYNARA**. -12. **afm-user-daemon** uses **SECURITY-MANAGER** features to set +1. **afm-user-daemon** uses **SECURITY-MANAGER** features to set the security context for the OTHER application. -13. **afm-user-daemon** launches the OTHER application. +1. **afm-user-daemon** launches the OTHER application. -This scenario does not cover all the features of the frameworks. +This scenario does not cover all the features of the frameworks. Shortly because details will be revealed in the next chapters, the components are: -* ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules, +- ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules, of setting groups, and, of creating initial content of *CYNARA* rules for applications. -* ***CYNARA***: in charge of handling API access permissions by users and by +- ***CYNARA***: in charge of handling API access permissions by users and by applications. -* ***D-Bus***: in charge of checking security of messaging. The usual D-Bus +- ***D-Bus***: in charge of checking security of messaging. The usual D-Bus security rules are enhanced by *CYNARA* checking rules. -* ***afm-system-daemon***: in charge of installing and uninstalling applications. +- ***afm-system-daemon***: in charge of installing and uninstalling applications. -* ***afm-user-daemon***: in charge of listing applications, querying application details, +- ***afm-user-daemon***: in charge of listing applications, querying application details, starting, terminating, pausing, resuming applications and their instances for a given user context. -* ***afb-binder***: in charge of serving resources and features through an +- ***afb-binder***: in charge of serving resources and features through an HTTP interface. -* ***afm-main-binding***: This binding allows applications to use the API +- ***afm-main-binding***: This binding allows applications to use the API of the AGL framework. - -Links between the "Security framework" and the "Application framework" ----------------------------------------------------------------------- +## Links between the "Security framework" and the "Application framework" The security framework refers to the security model used to ensure security and to the tools that are provided for implementing that model. The security model refers to how DAC (Discretionary Access Control), MAC (Mandatory Access Control) and Capabilities are used by the system -to ensure security and privacy. It also includes features of reporting -using audit features and by managing logs and alerts. +to ensure security and privacy. +It also includes features of reporting using audit features and by managing +logs and alerts. The application framework manages the applications: -installing, uninstalling, starting, pausing, listing ... + +- installing +- uninstalling +- starting +- pausing +- listing +- ... The application framework uses the security model/framework to ensure the security and the privacy of the applications that it manages. The application framework must be compliant with the underlying -security model/framework. But it should hide it to the applications. - +security model/framework. +But it should hide it to the applications. -The security framework ----------------------- +## The security framework -The implemented security model is the security model of Tizen 3. +The implemented security model is the security model of Tizen 3. This model is described [here][tizen-secu-3]. The security framework then comes from Tizen 3 but through -the [meta-intel]. -It includes: **Security-Manager**, **Cynara** -and **D-Bus** compliant to Cynara. +the [meta-intel]. +It includes: -Two patches are applied to the security-manager. The goal of these patches -is to remove specific dependencies with Tizen packages that are not needed -by AGL. +- **Security-Manager** +- **Cynara** +- **D-Bus** compliant to Cynara. + +Two patches are applied to the security-manager. +The goal of these patches is to remove specific dependencies with Tizen packages that are not needed by AGL. None of these patches adds or removes any behaviour. **In theory, the security framework/model is an implementation details that should not impact the layers above the application framework**. The security framework of Tizen provides "nice lad" a valuable component to -scan log files and analyse auditing. This component is still in development. - +scan log files and analyse auditing. +This component is still in development. -The application framework -------------------------- +## The application framework The application framework on top of the security framework provides the components to install and uninstall applications @@ -213,18 +230,22 @@ the security framework to the applications. For the reasons explained in introduction, we did not used the application framework of Tizen as is but used an adaptation of it. -The basis is kept identical: the applications are distributed -in a digitally signed container that must match the specifications -of widgets (web applications). This is described by the technical -recommendations [widgets] and [widgets-digsig] of the W3 consortium. +The basis is kept identical: -This model allows the distribution of HTML, QML and binary applications. +- The applications are distributed in a digitally signed container that must + match the specifications of widgets (web applications). + +This is described by the technical 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 future to include for example incremental delivery. - [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/1-afm-daemons.md b/docs/1-afm-daemons.md index ec7307b..11781d5 100644 --- a/docs/1-afm-daemons.md +++ b/docs/1-afm-daemons.md @@ -1,25 +1,23 @@ -The application framework daemons -================================= +# The application framework daemons -Foreword --------- +## Foreword This document describes application framework daemons -FCS (Fully Conform to Specification) implementation is still under development. +FCS (Fully Conform to Specification) implementation is still under development. It may happen that current implementation somehow diverges with specifications. -Introduction ------------- +## Introduction Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications -life. Understand that they will manage operations like: +life. +Understand that they will manage operations like: - - ***installation*** - - ***uninstallation*** - - ***running*** - - ***suspend*** - - ***inventory*** - - ... +- ***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. @@ -32,13 +30,13 @@ The figure below summarizes the situation of both **afm-system-daemon** and ![afm-daemons][afm-daemons]{style width:65%;} -The D-Bus interface -------------------- +## 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 +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 @@ -51,47 +49,52 @@ 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*** +- ***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. +- ***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. +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" - +```bash +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 +```bash +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 @@ -101,11 +104,9 @@ 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] +- **DESTINATION**: org.AGL.afm.[user|system] +- **PATH**: /org/AGL/afm/[user|system] +- **INTERFACE**: org.AGL.afm.[user|system] #### Method org.AGL.afm.system.install @@ -129,22 +130,28 @@ 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" +```bash +"/a/path/driving/to/the/widget" +``` Or an object: - { - "wgt": "/a/path/to/the/widget", - "force": false, - "root": "/a/path/to/the/root" - } +```json +{ + "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"} +```json +{"added":"appli@x.y"} +``` --- @@ -152,7 +159,6 @@ the id of the added application. **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***. @@ -163,14 +169,18 @@ After the uninstallation and before returning to the sender, Either a string: - "appli@x.y" +```bash +"appli@x.y" +``` Or an object: - { - "id": "appli@x.y", - "root": "/a/path/to/the/root" - } +```json +{ + "id": "appli@x.y", + "root": "/a/path/to/the/root" +} +``` **output**: the value 'true'. @@ -178,32 +188,37 @@ Or an object: #### 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" +```bash +"appli@x.y" +``` Or an object having the field "id" of type string: - {"id":"appli@x.y"} +```json +{"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, requested 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 - } +```json +{ + "id": string, the application id (id@version) + "version": string, the version of the application + "width": integer, requested width of the application + "height": integer, requested 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 +} +``` --- @@ -243,21 +258,27 @@ 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" +```bash +"/a/path/driving/to/the/widget" +``` Or an object: - { - "wgt": "/a/path/to/the/widget", - "force": false, - "root": "/a/path/to/the/root" - } +```json +{ + "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"} +```json +{"added":"appli@x.y"} +``` --- @@ -265,7 +286,6 @@ Or an object: **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***. @@ -277,14 +297,18 @@ application *root*. Either a string: - "appli@x.y" +```bash +"appli@x.y" +``` Or an object: - { - "id": "appli@x.y", - "root": "/a/path/to/the/root" - } +```json +{ + "id": "appli@x.y", + "root": "/a/path/to/the/root" +} +``` **output**: the value 'true'. @@ -299,12 +323,16 @@ start *mode* as below. Either just a string: - "appli@x.y" +```bash +"appli@x.y" +``` Or an object containing field "id" of type string and optionally a field mode: - {"id":"appli@x.y","mode":"local"} +```json +{"id":"appli@x.y","mode":"local"} +``` The field "mode" is a string equal to either "local" or "remote". @@ -322,11 +350,15 @@ The field "mode" is a string equal to either "local" or "remote". Either just a string: - "appli@x.y" +```bash +"appli@x.y" +``` Or an object containing field "id" of type string. - {"id":"appli@x.y"} +```json +{"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 @@ -392,19 +424,25 @@ Use **org.AGL.afm.user.resume** instead. **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"). +**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: +```json { "runid": 2, "pids": [ 435, 436 ], "state": "running", "id": "appli@x.y" } +``` --- @@ -417,18 +455,18 @@ Example of returned state: **output**: An array of states, one per running instance, as returned by the method ***org.AGL.afm.user.state***. -Starting **afm daemons** ----------------------- +## 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 +services attached to system and user respectively. +Normally, service files are locatedat */lib/systemd/system/afm-system-daemon.service* and */usr/lib/systemd/user/afm-user-daemon.service*. ### ***afm-system-daemon*** options The options for launching **afm-system-daemon** are: +```bash -r --root directory @@ -456,11 +494,13 @@ The options for launching **afm-system-daemon** are: --help Prints a short help. +``` ### ***afm-user-daemon*** options The options for launching **afm-user-daemon** are: +```bash -a --application directory @@ -511,9 +551,9 @@ The options for launching **afm-user-daemon** are: --help Prints a short help. +``` -Tasks of **afm-user-daemon** ----------------------------- +## Tasks of **afm-user-daemon** ### Maintaining list of applications @@ -522,12 +562,13 @@ applications and load in memory a list of available 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*. +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 +applications to its clients. +Clients may either request the full list of available applications or a more specific information about a given application. @@ -538,8 +579,8 @@ Systemd builds a secure environment for the application before starting it. Once launched, running instances of application receive -a runid that identify them. To make interface with systemd -evident, the pid is the runid. +a runid that identify them. +To make interface with systemd evident, the pid is the runid. ### Managing instances of running applications @@ -548,7 +589,8 @@ 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 a given application. +running instance. +It can also terminate a given application. ### Installing and uninstalling applications @@ -556,58 +598,50 @@ If the client own the right permissions, **afm-user-daemon** delegates that task to **afm-system-daemon**. -Using ***afm-util*** --------------------- +## 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 +orders to **afm-user-daemon**. +This small scripts allows to send command to ***afm-user-daemon*** either +interactively at shell prompt or scriptically. - - **afm-util install wgt **: +The syntax is simple: - install the wgt file +- it accept a command and when requires attached arguments. - - **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 +Here is the summary of ***afm-util***: - - **afm-util start id **: +- **afm-util runnables **: + list the runnable widgets installed - start an instance of the widget of id +- **afm-util install wgt **: + install the wgt file - - **afm-util once id **: +- **afm-util uninstall id **: + remove the installed widget of id - run once an instance of the widget of id +- **afm-util detail id **: + print detail about the installed widget of id - - **afm-util terminate rid **: +- **afm-util runners **: + list the running instance - terminate the running instance rid +- **afm-util start id **: + start an instance of the widget of id - - **afm-util state rid **: +- **afm-util once id **: + run once an instance of the widget of id - get status of the running instance rid +- **afm-util terminate rid **: + terminate the running instance rid +- **afm-util state rid **: + get status of the running instance rid Here is how to list applications using ***afm-util***: +```bash afm-util runnables - +``` [afm-daemons]: pictures/afm-daemons.svg diff --git a/docs/2-widgets.md b/docs/2-widgets.md index 24de661..2a7972e 100644 --- a/docs/2-widgets.md +++ b/docs/2-widgets.md @@ -1,5 +1,4 @@ -The widgets -=========== +# The widgets The widgets are described by the W3C's technical recommendations [Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) and [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) diff --git a/docs/2.1-widgets.md b/docs/2.1-widgets.md index d1777c8..084ee98 100644 --- a/docs/2.1-widgets.md +++ b/docs/2.1-widgets.md @@ -1,7 +1,6 @@ -Tools for managing widgets --------------------------- +# Tools for managing widgets -This project includes tools for managing widgets. +This project includes tools for managing widgets. These tools are: - ***wgtpkg-info***: command line tool to display @@ -19,31 +18,29 @@ These tools are: For all these commands, a tiny help is available with options **-h** or **--help**. -There is no tool for unpacking a widget. For doing such operation, -you can use the command **unzip**. +There is no tool for unpacking a widget. +For doing such operation, you can use the command **unzip**. To list the files of a widget: ```bash -$ unzip -l WIDGET +unzip -l WIDGET ``` To extract a widget in some directory: ```bash -$ unzip WIDGET -d DIRECTORY +unzip WIDGET -d DIRECTORY ``` -*Note that DIRECTORY will be created if needed*. +*Note: that DIRECTORY will be created if needed*. -Getting data about a widget file ---------------------------------- +## 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 and packing widget ### Signing @@ -57,13 +54,13 @@ There are two types of signature files: author and distributor. Example 1: add an author signature ```bash -$ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY +wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY ``` Example 2: add a distributor signature ```bash -$ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY +wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY ``` ### Packing @@ -72,36 +69,36 @@ This operation can be done using the command **zip** but we provide the tool **wgtpkg-pack** that may add checking. Example: + ```bash -$ wgtpkg-pack DIRECTORY -o file.wgt +wgtpkg-pack DIRECTORY -o file.wgt ``` -Writing a widget ----------------- + +## Writing a widget ### The steps for writing a widget 1. make your application - -2. create its configuration file **config.xml** - -3. sign it - -4. pack it +1. create its configuration file **config.xml** +1. sign it +1. pack it Fairly easy, no? -Organization of directory of applications ------------------------------------------ +## Organization of directory of applications ### directory where are stored applications -Applications can be installed in different places: the system itself, extension device. +Applications can be installed in different places: + +- the system itself, extension device. + On a phone application are typically installed on the sd card. This translates to: - - /usr/applications: system wide applications - - /opt/applications: removable applications +- /usr/applications: system wide applications +- /opt/applications: removable applications From here those paths are referenced as: "APPDIR". @@ -109,16 +106,17 @@ The main path for applications is: APPDIR/PKGID/VER. Where: - - APPDIR is as defined above - - PKGID is a directory whose name is the package identifier - - VER is the version of the package MAJOR.MINOR +- APPDIR is as defined above +- PKGID is a directory whose name is the package identifier +- VER is the version of the package MAJOR.MINOR -This organization has the advantage to allow several versions to leave together. +This organization has the advantage to allow several versions +to leave together. This is needed for some good reasons (rolling back) and also for less good reasons (user habits). ### Identity of installed files -All files are installed as user "afm" and group "afm". +All files are installed as user "afm" and group "afm". All files have rw(x) for user and r-(x) for group and others. This allows every user to read every file. diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md index c50567d..f6c88ab 100644 --- a/docs/2.2-config.xml.md +++ b/docs/2.2-config.xml.md @@ -1,12 +1,10 @@ -Configuration file - config.xml -=============================== +# Configuration file - config.xml The widgets are described by the W3C's technical recommendations [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig] that specifies the configuration file **config.xml**. -Overview --------- +## Overview The file **config.xml** describes important data of the application to the framework: @@ -50,8 +48,7 @@ The most important items are: - **<content src="..." type="..."\>**: this indicates the entry point and its type. -Standard elements of "config.xml" ---------------------------------- +## Standard elements of "config.xml" ### The element widget @@ -74,7 +71,7 @@ Values for *version* 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. +Version values are dot separated fields MAJOR.MINOR.REVISION. Such version would preferably follow guidelines of [semantic versioning][semantic-version]. @@ -90,8 +87,7 @@ The content designed depends on its type. See below for the known types. The element *icon* is mandatory (for version 2.x, blowfish) and must be unique. It must designate an image file with its attribute *src*. -AGL features ------------- +## AGL features The AGL framework uses the feature tag for specifying security and binding requirement of the widget. @@ -99,31 +95,34 @@ requirement of the widget. Since the migration of the framework to leverage systemd power, the features are of important use to: - - declare more than just an application - - declare the expected dependencies - - declare the expected permissions - - declare the exported apis +- declare more than just an application +- declare the expected dependencies +- declare the expected permissions +- declare the exported apis The specification of [widgets][widgets] is intended to describe -only one application. In the present case, we expect to describe -more than just an application. For example, a publisher could -provide a widget containing a service, an application for tuning -that service, an application that leverage the service. +only one application. +In the present case, we expect to describe more than just an application. +For example, a publisher could provide a widget containing a service, +an application for tuning that service, an application that +leverage the service. Here, the term of service means a background application that runs without IHM and whose public api can be accessed by other applications. So the features are used to describe each of the possible -units of widgets. The "standard" unit in the -meaning of [widgets][widgets] is called the "main" unit. +units of widgets. +The "standard" unit in the meaning of [widgets][widgets] +is called the "main" unit. -### feature name="urn:AGL:widget:required-api" +### required-api: feature name="urn:AGL:widget:required-api" List of the api required by the widget. -Each required api must be explicited using a <param> entry. +Each required api must be explicited using a `<param>` entry. Example: + ```xml <feature name="urn:AGL:widget:required-api"> <param name="#target" value="main" />> @@ -133,6 +132,7 @@ Example: ``` This will be *virtually* translated for mustaches to the JSON + ```json "required-api": [ { "name": "gps", "value": "auto" }, @@ -140,56 +140,50 @@ This will be *virtually* translated for mustaches to the JSON ] ``` -#### param name="#target" +#### required-api: param name="#target" OPTIONAL Declares the name of the unit requiring the listed apis. -Only one instance of the param "#target" is allowed. +Only one instance of the param "#target" is allowed. When there is not instance of this param, it behave as if the target main was specified. -#### param name=[required api name] +#### required-api: param name=[required api name] The name is the name of the required API. -The value describes how to connect to the required api. +The value describes how to connect to the required api. It is either: - - local: - - The binding is a local shared object. - In that case, the name is the relative path of the - shared object to be loaded. - - - auto: - - The framework set automatically the kind of - the connection to the API +- local: + The binding is a local shared object. + In that case, the name is the relative path of the + shared object to be loaded. - - ws: +- auto: + The framework set automatically the kind of + the connection to the API - The framework connect using internal websockets +- ws: + The framework connect using internal websockets - - dbus: +- dbus: + The framework connect using internal dbus - The framework connect using internal dbus +- link: + The framework connect in memory by dynamically linking - - link: +- cloud: [PROPOSAL - NOT IMPLEMENTED] + The framework connect externally using websock. + In that case, the name includes data to access the service. + Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />` - The framework connect in memory by dynamically linking - - - cloud: [PROPOSAL - NOT IMPLEMENTED] - - The framework connect externally using websock. - In that case, the name includes data to access the service. - Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />` - -### feature name="urn:AGL:widget:required-permission" +### required-permission: feature name="urn:AGL:widget:required-permission" List of the permissions required by the unit. -Each required permission must be explicited using a <param> entry. +Each required permission must be explicited using a `<param>` entry. Example: @@ -216,31 +210,32 @@ This will be *virtually* translated for mustaches to the JSON } ``` -#### param name="#target" +#### required-permission: param name="#target" OPTIONAL -Declares the name of the unit requiring the listed permissions. -Only one instance of the param "#target" is allowed. +Declares the name of the unit requiring the listed permissions. +Only one instance of the param "#target" is allowed. When there is not instance of this param, it behave as if the target main was specified. -#### param name=[required permission name] +#### required-permission: 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. + isn't required (required="false") and in that case it is optional. - optional: the permission is optional - -### feature name="urn:AGL:widget:provided-unit" +### provided-unit: feature name="urn:AGL:widget:provided-unit" This feature is made for declaring new units -for the widget. Using this feature, a software publisher +for the widget. +Using this feature, a software publisher can provide more than one application in the same widget. Example: + ```xml <feature name="urn:AGL:widget:provided-unit"> <param name="#target" value="geoloc" /> @@ -251,6 +246,7 @@ Example: ``` This will be *virtually* translated for mustaches to the JSON + ```json { "#target":"geoloc", @@ -263,41 +259,40 @@ This will be *virtually* translated for mustaches to the JSON } ``` -#### param name="#target" +#### provided-unit: param name="#target" REQUIRED Declares the name of the unit. The default unit, the unit -of the main of the widget, has the name "main". The value -given here must be unique within the widget file. It will -be used in other places of the widget config.xml file to +of the main of the widget, has the name "main". +The value given here must be unique within the widget file. +It will be used in other places of the widget config.xml file to designate the unit. -Only one instance of the param "#target" is allowed. +Only one instance of the param "#target" is allowed. The value can't be "main". -#### param name="content.type" +#### provided-unit: param name="content.type" REQUIRED The mimetype of the provided unit. -#### param name="content.src" +#### provided-unit: param name="content.src" -A path to the +A path to the source #### other parameters The items that can be set for the main unit can also be set using the params if needed. - - description - - name.content - - name.short - - ... +- description +- name.content +- name.short +- ... - -### feature name="urn:AGL:widget:provided-api" +### provided-api: feature name="urn:AGL:widget:provided-api" Use this feature for exporting one or more API of a unit to other widgets of the platform. @@ -329,78 +324,70 @@ This will be *virtually* translated for mustaches to the JSON ], ``` -#### param name="#target" - +#### provided-api: param name="#target" OPTIONAL -Declares the name of the unit exporting the listed apis. -Only one instance of the param "#target" is allowed. +Declares the name of the unit exporting the listed apis. +Only one instance of the param "#target" is allowed. When there is not instance of this param, it behave as if the target main was specified. - -#### param name=[name of exported api] +#### provided-api: param name=[name of exported api] The name give the name of the api that is exported. The value is one of the following values: - - ws: - - export the api using UNIX websocket - - - dbus: - - export the API using dbus +- ws: + export the api using UNIX websocket - - auto: +- dbus: + export the API using dbus - export the api using the default method(s). +- auto: + export the api using the default method(s). - -Known content types -------------------- +## Known content types The configuration file ***/etc/afm/afm-unit.conf*** defines how to create systemd units for widgets. Known types for the type of content are: -- ***text/html***: - HTML application, - content.src designates the home page of the application +- ***text/html***: + HTML application, + content.src designates the home page of the application -- ***application/vnd.agl.native*** - AGL compatible native, - content.src designates the relative path of the binary. +- ***application/vnd.agl.native*** + AGL compatible native, + content.src designates the relative path of the binary. -- ***application/vnd.agl.service***: - AGL service, content.src is not used. +- ***application/vnd.agl.service***: + AGL service, content.src is not used. -- ***application/x-executable***: - Native application, - content.src designates the relative path of the binary. - For such application, only security setup is made. +- ***application/x-executable***: + Native application, + content.src designates the relative path of the binary. + For such application, only security setup is made. Adding more types is easy, it just need to edit the configuration file ***afm-unit.conf***. -### Older content type currently not supported at the moment. +### Older content type currently not supported at the moment This types were defined previously when the framework was not -leveraging systemd. The transition to systemd let these types -out at the moment. +leveraging systemd. +The transition to systemd let these types out at the moment. - ***application/vnd.agl.url*** - ***text/vnd.qt.qml***, ***application/vnd.agl.qml*** - ***application/vnd.agl.qml.hybrid*** - ***application/vnd.agl.html.hybrid*** - <!-- pagebreak --> -The configuration file afm-unit.conf -==================================== + +## The configuration file afm-unit.conf The integration of the framework with systemd mainly consists of creating the systemd unit @@ -410,9 +397,9 @@ of the installed widgets. This configuration file named `afm-unit.conf` installed on the system with the path `/etc/afm/afm-unit.conf` describes how to generate all units from the *config.xml* -configuration files of widgets. The description uses an extended -version of the templating formalism of [mustache][] -to describes all the units. +configuration files of widgets. +The description uses an extended version of the templating +formalism of [mustache][] to describes all the units. Let present how it works using the following diagram that describes graphically the workflow of creating the unit @@ -423,8 +410,8 @@ file of the widget `config.xml`: In a first step, and because [mustache][] is intended to work on JSON representations, the configuration file is -translated to an internal JSON representation. This -representation is shown along the examples of the documentation +translated to an internal JSON representation. +This representation is shown along the examples of the documentation of the config files of widgets. In a second step, the mustache template `afm-unit.conf` @@ -432,49 +419,43 @@ is instantiated using the C library [mustach][] that follows the rules of [mustache][mustache] and with all its available extensions: - - use of colon (:) for explicit substitution - - test of values with = or =! +- use of colon (:) for explicit substitution +- test of values with = or =! In a third step, the result of instantiating `afm-unit.conf` -for the widget is split in units. To achieve that goal, -the lines containing specific directives are searched. -Any directive occupy one full line. The directives are: - - - %nl - - Produce an empty line at the end - - - %begin systemd-unit - - %end systemd-unit - - Delimit the produced unit, its begin and its end - - - %systemd-unit user - - %systemd-unit system - - Tells the kind of unit (user/system) - - - %systemd-unit service NAME - - %systemd-unit socket NAME - - Gives the name and type (service or socket) of the unit. - The extension is automatically computed from the type - and must not be set in the name. - - - %systemd-unit wanted-by NAME - - Tells to install a link to the unit in the wants of NAME +for the widget is split in units. +To achieve that goal, the lines containing specific directives are searched. +Any directive occupy one full line. +The directives are: + +- %nl + Produce an empty line at the end +- %begin systemd-unit +- %end systemd-unit + Delimit the produced unit, its begin and its end +- %systemd-unit user +- %systemd-unit system + Tells the kind of unit (user/system) +- %systemd-unit service NAME +- %systemd-unit socket NAME + Gives the name and type (service or socket) of the unit. + The extension is automatically computed from the type + and must not be set in the name. +- %systemd-unit wanted-by NAME + Tells to install a link to the unit in the wants of NAME Then the computed units are then written to the filesystem and inserted in systemd. The generated unit files will contain variables for internal -use of the framework. These variables are starting with `X-AFM-`. +use of the framework. +These variables are starting with `X-AFM-`. The variables starting with `X-AFM-` but not with `X-AFM--` are -the public variables. These variables will be returned by the +the public variables. +These variables will be returned by the framework as the details of an application (see **afm-util detail ...**). -Variables starting with `X-AFM--` are private to the framework. +Variables starting with `X-AFM--` are private to the framework. By example, the variable `X-AFM--http-port` is used to record the allocated port for applications. @@ -495,6 +476,3 @@ record the allocated port for applications. [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" [semantic-version]: http://semver.org/ "Semantic versioning" - - - diff --git a/docs/3-permissions.md b/docs/3-permissions.md index 480bfef..957478e 100644 --- a/docs/3-permissions.md +++ b/docs/3-permissions.md @@ -1,42 +1,47 @@ -The permissions -=============== +# The permissions - -Permission's names ------------------- +## Permission's names The proposal here is to specify a naming scheme for permissions -that allows the system to be as stateless as possible. The current -specification includes in the naming of permissions either +that allows the system to be as stateless as possible. +The current specification includes in the naming of permissions either the name of the bound binding when existing and the level of the -permission itself. Doing this, there is no real need for the +permission itself. +Doing this, there is no real need for the framework to keep installed permissions in a database. The permission names are [URN][URN] of the form: - urn:AGL:permission:<api>:<level>:<hierarchical-name> +```bash + urn:AGL:permission:<api>:<level>:<hierarchical-name> +``` -where "AGL" is the NID (the namespace identifier) dedicated to -AGL (note: a RFC should be produced to standardize this name space). +where "AGL" is the NID (the namespace identifier) dedicated to AGL. +(note: a RFC should be produced to standardize this name space) The permission names are made of NSS (the namespace specific string) starting with "permission:" and followed by colon separated -fields. The 2 first fields are `<api>` and `<level>` and the remaining +fields. +The 2 first fields are `<api>` and `<level>` and the remaining fields are grouped to form the `<hierarchical-name>`. - <api> ::= [ <pname> ] +```bash + <api> ::= [ <pname> ] - <pname> ::= 1*<pchars> + <pname> ::= 1*<pchars> - <pchars> ::= <upper> | <lower> | <number> | <extra> + <pchars> ::= <upper> | <lower> | <number> | <extra> - <extra> ::= "-" | "." | "_" | "@" + <extra> ::= "-" | "." | "_" | "@" +``` The field `<api>` can be made of any valid character for NSS except -the characters colon and star (:*). This field designates the api -providing the permission. This scheme is used to deduce binding requirements -from permission requirements. The field `<api>` can be the empty -string when the permission is defined by the AGL system itself. +the characters colon and star (:*). +This field designates the api providing the permission. +This scheme is used to deduce binding requirements +from permission requirements. +The field `<api>` can be the empty string when the permission +is defined by the AGL system itself. [PROPOSAL 1] The field `<api>` if starting with the character "@" represents a transversal/cross permission not bound to any binding. @@ -46,35 +51,35 @@ in addition to a permission not bound to any binding, represents a permission that must be set at installation and that can not be revoked later. - <level> ::= 1*<lower> + <level> ::= 1*<lower> -The field `<level>` is made only of letters in lower case. +The field `<level>` is made only of letters in lower case. The field `<level>` can only take some predefined values: - - system - - platform - - partner - - tiers - - owner - - public +- system +- platform +- partner +- tiers +- owner +- public The field `<hierarchical-name>` is made of `<pname>` separated by colons. - <hierarchical-name> ::= <pname> 0*(":" <pname>) + <hierarchical-name> ::= <pname> 0*(":" <pname>) The names at left are hierarchically grouping the -names at right. This hierarchical behaviour is intended to +names at right. +This hierarchical behaviour is intended to be used to request permissions using hierarchical grouping. - -Permission value ----------------- +## Permission value In some case, it could be worth to add a value to a permission. Currently, the framework allows it for permissions linked to -systemd. But this not currently used. +systemd. +But this not currently used. Conversely, permissions linked to cynara can't carry data except in their name. @@ -82,61 +87,37 @@ except in their name. Thus to have a simple and cleaner model, it is better to forbid attachment of value to permission. - -Example of permissions ----------------------- - -Here is a list of some possible permissions. These -permissions are available the 17th of March 2017. - - - urn:AGL:permission::platform:no-oom - - Set OOMScoreAdjust=-500 to keep the out-of-memory - killer away. - - - urn:AGL:permission::partner:real-time - - Set IOSchedulingClass=realtime to give to the process - realtime scheduling. - - Conversely, not having this permission set RestrictRealtime=on - to forbid realtime features. - - - urn:AGL:permission::public:display - - Adds the group "display" to the list of supplementary groups - of the process. - - - urn:AGL:permission::public:syscall:clock - - Without this permission SystemCallFilter=~@clock is set to - forfid call to clock. - - - urn:AGL:permission::public:no-htdocs - - The http directory served is not "htdocs" but "." - - - urn:AGL:permission::public:applications:read - - Allows to read data of installed applications (and to - access icons). - - - urn:AGL:permission::partner:service:no-ws - - Forbids services to provide its API through websocket. - - - urn:AGL:permission::partner:service:no-dbus - - Forbids services to provide its API through D-Bus. - - - urn:AGL:permission::system:run-by-default - - Starts automatically the application. Example: home-screen. - - - http://tizen.org/privilege/internal/dbus - - Permission to use D-Bus. - +## Example of permissions + +Here is a list of some possible permissions. +These permissions are available the 17th of March 2017. + +- urn:AGL:permission::platform:no-oom + Set OOMScoreAdjust=-500 to keep the out-of-memory + killer away. +- urn:AGL:permission::partner:real-time + Set IOSchedulingClass=realtime to give to the process + realtime scheduling. + Conversely, not having this permission set RestrictRealtime=on + to forbid realtime features. +- urn:AGL:permission::public:display + Adds the group "display" to the list of supplementary groups + of the process. +- urn:AGL:permission::public:syscall:clock + Without this permission SystemCallFilter=~@clock is set to + forfid call to clock. +- urn:AGL:permission::public:no-htdocs + The http directory served is not "htdocs" but "." +- urn:AGL:permission::public:applications:read + Allows to read data of installed applications (and to + access icons). +- urn:AGL:permission::partner:service:no-ws + Forbids services to provide its API through websocket. +- urn:AGL:permission::partner:service:no-dbus + Forbids services to provide its API through D-Bus. +- urn:AGL:permission::system:run-by-default + Starts automatically the application. Example: home-screen. +- <http://tizen.org/privilege/internal/dbus> + Permission to use D-Bus. [URN]: https://tools.ietf.org/rfc/rfc2141.txt "RFC 2141: URN Syntax" - diff --git a/docs/4-quick-tutorial.md b/docs/4-quick-tutorial.md index 2ed7cf9..6ab07b7 100644 --- a/docs/4-quick-tutorial.md +++ b/docs/4-quick-tutorial.md @@ -1,199 +1,263 @@ +# AGL Application Framework: A Quick Tutorial -AGL Application Framework: A Quick Tutorial -=========================================== +## Introduction -Introduction ------------- -This document proposes a quick tutorial to demonstrate the major functionalities of the AGL Application Framework. For more complete information, please refer to the inline documentation available in the main git repository: +This document proposes a quick tutorial to demonstrate the major +functionalities 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] - -For more information on AGL, please visit: +For more information on AGL, please visit: [https://www.automotivelinux.org/] ---------- -Sample applications -------------------- -4 sample applications (.wgt files) are prebuilt and available at the following address: +## Sample applications + +4 sample applications (.wgt files) are prebuilt and available at the following address: [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): -``` -$ git clone https://github.com/iotbzh/afm-widget-examples +```bash +git clone https://github.com/iotbzh/afm-widget-examples ``` -Using the CLI tool ------------------- +## Using the CLI tool ### Setup Environment + Connect your AGL target board to the network and copy some sample widgets on it through SSH (set BOARDIP with your board IP address) : -``` -$ cd afm-widget-examples -$ BOARDIP=1.2.3.4 -$ scp *.wgt root@$BOARDIP:~/ +```bash +cd afm-widget-examples +BOARDIP=1.2.3.4 +scp *.wgt root@$BOARDIP:~/ ``` Connect through SSH on the target board and check for Application Framework daemons: - $ ssh root@$BOARDIP - root@porter:~# ps -ef|grep bin/afm - afm 409 1 0 13:00 ? 00:00:00 /usr/bin/afm-system-daemon - root 505 499 0 13:01 ? 00:00:00 /usr/bin/afm-user-daemon - root 596 550 0 13:22 pts/0 00:00:00 grep afm +```bash +$ ssh root@$BOARDIP +root@porter:~# ps -ef|grep bin/afm +afm 409 1 0 13:00 ? 00:00:00 /usr/bin/afm-system-daemon +root 505 499 0 13:01 ? 00:00:00 /usr/bin/afm-user-daemon +root 596 550 0 13:22 pts/0 00:00:00 grep afm +``` We can see that there are two daemons running: -* **afm-system-daemon** runs with a system user 'afm' and is responsible for installing/uninstalling packages -* **afm-user-daemon** runs as a user daemon (currently as root because it's the only real user on the target board) and is responsible for the whole life cycle of the applications running inside the user session. -The application framework has a tool running on the Command Line Interface (CLI). Using the **afm-util** command, you can install, uninstall, list, run, pause ... applications. +* **afm-system-daemon** runs with a system user 'afm' and is responsible for + installing/uninstalling packages +* **afm-user-daemon** runs as a user daemon (currently as root because it's the + only real user on the target board) and is responsible for the whole life + cycle of the applications running inside the user session. + +The application framework has a tool running on the +Command Line Interface (CLI). +Using the **afm-util** command, you can install, uninstall, list, run, pause ... applications. To begin, run '**afm-util help**' to get a quick help on commands: - root@porter:~# afm-util help - usage: afm-util command [arg] +```bash +root@porter:~# afm-util help +usage: afm-util command [arg] +``` - The commands are: +The commands are: - list - runnables list the runnable widgets installed +```bash +list +runnables list the runnable widgets installed - add wgt - install wgt install the wgt file +add wgt +install wgt install the wgt file - remove id - uninstall id remove the installed widget of id +remove id +uninstall id remove the installed widget of id - info id - detail id print detail about the installed widget of id +info id +detail id print detail about the installed widget of id - ps - runners list the running instance +ps +runners list the running instance - run id - start id start an instance of the widget of id +run id +start id start an instance of the widget of id - kill rid - terminate rid terminate the running instance rid +kill rid +terminate rid terminate the running instance rid - status rid - state rid get status of the running instance rid +status rid +state rid get status of the running instance rid +``` ### Install an application You can then install your first application: - root@porter:~# afm-util install /home/root/annex.wgt - { "added": "webapps-annex@0.0" } +```bash +root@porter:~# afm-util install /home/root/annex.wgt +{ "added": "webapps-annex@0.0" } +``` Let's install a second application: - root@porter:~# afm-util install /home/root/memory-match.wgt - { "added": "webapps-memory-match@1.1" } +```bash +root@porter:~# afm-util install /home/root/memory-match.wgt +{ "added": "webapps-memory-match@1.1" } +``` Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons. ### List installed applications + You can then list all installed applications: - root@porter:~# afm-util list - [ { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" }, - { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ] +```bash +root@porter:~# afm-util list +[ { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" }, +{ "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ] +``` Here, we can see the two previously installed applications. ### Get information about an application + Let's get some details about the first application: - root@porter:~# afm-util info webapps-annex@0.0 - { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } +```bash +root@porter:~# afm-util info webapps-annex@0.0 +{ "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } +``` -Note that AGL applications are mostly handled by afm-util through their IDs. In our example, the application ID is 'webapps-annex@0.0'. +Note: that AGL applications are mostly handled by afm-util through their IDs. +In our example, the application ID is 'webapps-annex@0.0'. ### Start application + Let's start the first application Annex: - root@porter:~# afm-util start webapps-annex@0.0 - 1 +```bash +root@porter:~# afm-util start webapps-annex@0.0 +1 +``` As the application is a HTML5 game, you should then get a webview running with QML on the board display. ### Security Context -The application has been started in the user session, with a dedicated security context, enforced by SMACK. To illustrate this, we can take a look at the running processes and their respective SMACK labels: - root@porter:~# ps -efZ |grep webapps-annex | grep -v grep - User::App::webapps-annex root 716 491 0 13:19 ? 00:00:00 /usr/bin/afb-daemon --mode=local --readyfd=8 --alias=/icons /usr/share/afm/icons --port=12348 --rootdir=/usr/share/afm/applications/webapps-annex/0.0 --token=7D6D2F16 --sessiondir=/home/root/app-data/webapps-annex/.afb-daemon - User::App::webapps-annex root 717 491 0 13:19 ? 00:00:00 /usr/bin/qt5/qmlscene http://localhost:12348/index.html?token=7D6D2F16 /usr/bin/web-runtime-webkit.qml +The application has been started in the user session, with a dedicated security context, enforced by SMACK. +To illustrate this, we can take a look at the running processes and their respective SMACK labels: + +```bash +root@porter:~# ps -efZ |grep webapps-annex | grep -v grep +User::App::webapps-annex root 716 491 0 13:19 ? 00:00:00 /usr/bin/afb-daemon --mode=local --readyfd=8 --alias=/icons /usr/share/afm/icons --port=12348 --rootdir=/usr/share/afm/applications/webapps-annex/0.0 --token=7D6D2F16 --sessiondir=/home/root/app-data/webapps-annex/.afb-daemon +User::App::webapps-annex root 717 491 0 13:19 ? 00:00:00 /usr/bin/qt5/qmlscene http://localhost:12348/index.html?token=7D6D2F16 /usr/bin/web-runtime-webkit.qml +``` In the previous result, we see that the application is composed of two processes: + * the application binder (afb-daemon) * the application UI (qmlscene ...) -While most system processes run with the label 'System', we see that the application runs with a specific SMACK label 'User::App::webapps-annex': this label is used to force the application to follow a Mandatory Access Control (MAC) scheme. This means that those processes run in their own security context, isolated from the rest of the system (and other applications). Global security rules can then be applied to restrict access to all other user or system resources. +While most system processes run with the label 'System', we see that the +application runs with a specific SMACK label 'User::App::webapps-annex': this +label is used to force the application to follow +a Mandatory Access Control (MAC) scheme. +This means that those processes run in their own security context, +isolated from the rest of the system (and other applications). +Global security rules can then be applied to restrict access +to all other user or system resources. ### Check running applications + To check for running applications, just run: - root@porter:~# afm-util ps - [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ] +```bash +root@porter:~# afm-util ps +[ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ] +``` -The 'runid' is the application instance ID and is used as an argument for the subcommands controlling the application runtime state (kill/pause/resume/status) +The 'runid' is the application instance ID and is used as an argument for the +subcommands controlling the application runtime state (kill/pause/resume/status) ### Uninstall application + To uninstall an application, simply use its ID: - root@porter:~# afm-util uninstall webapps-annex@0.0 - true +```bash +root@porter:~# afm-util uninstall webapps-annex@0.0 +true +``` Then list the installed apps to confirm the removal: - root@porter:~# afm-util list - [ { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ] +```bash +root@porter:~# afm-util list +[ { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ] +``` -afm-client: a sample HTML5 'Homescreen' ---------------------------------------- +## afm-client: a sample HTML5 'Homescreen' **afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util. -The HTML5 UI is accessible remotely through this URL: -http://[board_ip]:1234/opa?token=132456789 +The HTML5 UI is accessible remotely through this URL: +<http://[board_ip]:1234/opa?token=132456789> ### Installing an application -By clicking on the '**Upload**' button on the right, you can send an application package (WGT file) and install it. Select for example the file '**rabbit.wgt**' that was cloned initially from the git repository afm-widget-examples. +By clicking on the '**Upload**' button on the right, +you can send an application package (WGT file) and install it. +Select for example the file '**rabbit.wgt**' that was cloned initially + from the git repository afm-widget-examples. -Then a popup requester ask for a confirmation: 'Upload Application rabbit.wgt ?'. Click on the '**Install**' button. +Then a popup requester ask for a confirmation: +'Upload Application rabbit.wgt ?'. Click on the '**Install**' button. -You should then see some changes in the toolbar: a new icon appeared, representing the freshly installed application. +You should then see some changes in the toolbar: +a new icon appeared, representing the freshly installed application. ### Running an application -In the toolbar, click on the button representing the Rabbit application. You'll get a popup asking to: + +In the toolbar, click on the button representing the Rabbit application. +You'll get a popup asking to: + * start the application * or get some info about it * or uninstall it -Click on the 'start' item: the application starts and should be visible as a webview on the target board display. Note that at this point, we could also run the application remotely, that is in the same browser as the Homescreen app. By default, the application framework is configured to run applications 'locally' on the board display. +Click on the 'start' item: the application starts and should be visible + as a webview on the target board display. +Note that at this point, we could also run the application remotely, +that is in the same browser as the Homescreen app. +By default, the application framework is configured +to run applications 'locally' on the board display. ### Uninstalling an application -From the same popup menu, you can select 'uninstall' to remove the application from the system. As a consequence, the application icon should disappear from the toolbar. +From the same popup menu, you can select 'uninstall' +to remove the application from the system. +As a consequence, the application icon should disappear from the toolbar. -afb-client: a template for Angular Applications ------------------------------------------------ +## afb-client: a template for Angular Applications -Another package '**afb-client**' is also available for testing. -This is a sample HTML5 application demonstrating various basic capabilities of the Binder daemon. It can be used by developers as a template to start writing real AGL Applications. +Another package '**afb-client**' is also available for testing. +This is a sample HTML5 application demonstrating various basic +capabilities of the Binder daemon. +It can be used by developers as a template to start writing real AGL Applications. This application is not available as WGT file yet and it should be started manually without any specific security context: - root@porter:~# /usr/bin/afb-daemon --port=1235 --token='' --sessiondir=/home/root/.afm-daemon --rootdir=/usr/share/agl/afb-client --alias=/icons:/usr/share/afm/icons +```bash +root@porter:~# /usr/bin/afb-daemon --port=1235 --token='' --sessiondir=/home/root/.afm-daemon --rootdir=/usr/share/agl/afb-client --alias=/icons:/usr/share/afm/icons +``` -Then you can access it from a browser: -http://[board_ip]:1235/opa/?token=132456789 +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. diff --git a/docs/5-frameworks.md b/docs/5-frameworks.md index fb73ff2..6170421 100644 --- a/docs/5-frameworks.md +++ b/docs/5-frameworks.md @@ -1,15 +1,12 @@ -Application framework -===================== +# Application framework -Foreword --------- +## Foreword -This document describes application framework fundamentals. -FCS (Fully Conform to Specification) implementation is still under development. +This document describes application framework fundamentals. +FCS (Fully Conform to Specification) implementation is still under development. It may happen that current implementation somehow diverges with specifications. -Overview --------- +## Overview The application framework on top of the security framework provides components to install and uninstall applications @@ -23,12 +20,15 @@ application framework directly, but to rework a new framework inspired from Tize fundamentals remain identical: the applications are distributed in a digitally signed container that should match widget specifications -normalized by the W3C. This is described by the technical -recommendations [Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) and [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) of the W3 consortium. +normalized by the W3C. +This is described by the technical recommendations +[Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) and +[XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) + of the W3 consortium. As today this model allows the distribution of HTML, QML and binary applications but it could be extended to any other class of applications. -The management of widget package signatures. +The management of widget package signatures. Current model is only an initial step, it might be extended in the future to include new feature (ie: incremental delivery). diff --git a/docs/5.1-application-framework.md b/docs/5.1-application-framework.md index 942ff9c..71044d2 100644 --- a/docs/5.1-application-framework.md +++ b/docs/5.1-application-framework.md @@ -1,41 +1,36 @@ -Comparison to other frameworks ------------------------------- +# Comparison to other frameworks - - Tizen framework +- Tizen framework +- xdg-app +- ostro - - xdg-app - - - ostro - -### Organization of directory of applications ### +## Organization of directory of applications The main path for applications are: APPDIR/PKGID/VER. Where: - - APPDIR is as defined above - - PKGID is a directory whose name is the package identifier - - VER is the version of the package MAJOR.MINOR +- APPDIR is as defined above +- PKGID is a directory whose name is the package identifier +- VER is the version of the package MAJOR.MINOR -The advantage of such an organization is to allow several versions to live together. +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 the files are installed as user "userapp" and group "userapp". All files have rw(x) for user and r-(x) for group and others. This allows any user to read 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. @@ -58,9 +53,9 @@ 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. +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" @@ -77,5 +72,3 @@ How to manage that? [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/5.2-security-framework.md b/docs/5.2-security-framework.md index 45f1851..c1fff24 100644 --- a/docs/5.2-security-framework.md +++ b/docs/5.2-security-framework.md @@ -1,11 +1,8 @@ - -The security framework -====================== +# The security framework NOT STARTED !!!!!! -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. @@ -28,14 +25,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. +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" @@ -50,7 +44,3 @@ How to manage that? [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" - - - - |