From 34a92a2ac87558067a96886e5d1f1d5eecb0a135 Mon Sep 17 00:00:00 2001 From: José Bollo Date: Fri, 21 Jun 2019 16:59:34 +0200 Subject: WIP: documenting Change-Id: Ica30d4ae05e0541e6dd4ed0292cb16abab461269 --- book.json | 11 - docs/0-introduction.md | 256 ++++------------- docs/1-afm-daemons.md | 581 ++------------------------------------ docs/2-widgets.md | 36 ++- docs/2.1-widget-tools.md | 153 ++++++++++ docs/2.1-widgets.md | 153 ---------- docs/2.2-config.xml.md | 13 +- docs/4-quick-tutorial.md | 4 - docs/5-frameworks.md | 34 --- docs/5.1-application-framework.md | 74 ----- docs/5.2-security-framework.md | 46 --- docs/7-debugging.md | 16 ++ docs/SUMMARY.md | 11 - docs/a-history.md | 221 ++++++++++++++- docs/api-services-book.yml | 4 +- docs/index.md | 1 - docs/pictures/pictures.odp | Bin 0 -> 238291 bytes mkdocs.yml | 14 - 18 files changed, 502 insertions(+), 1126 deletions(-) delete mode 100644 book.json create mode 100644 docs/2.1-widget-tools.md delete mode 100644 docs/2.1-widgets.md delete mode 100644 docs/5-frameworks.md delete mode 100644 docs/5.1-application-framework.md delete mode 100644 docs/5.2-security-framework.md create mode 100644 docs/7-debugging.md delete mode 100644 docs/SUMMARY.md delete mode 120000 docs/index.md create mode 100644 docs/pictures/pictures.odp delete mode 100644 mkdocs.yml diff --git a/book.json b/book.json deleted file mode 100644 index 8212b89..0000000 --- a/book.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "title": "Application Framework Service", - "subtitle": "", - "description": "Application Framework Service of Automotive Grade Linux", - "keywords": "AGL, Development, application, framework, service", - "author": "IoT.Bzh Team", - "website": "http://iot.bzh", - "published": "September 2017", - "version": "4.99-EERC1", - "pdf_filename": "Application-Framework-Service-Guide" -} diff --git a/docs/0-introduction.md b/docs/0-introduction.md index 42324f5..6e7e606 100644 --- a/docs/0-introduction.md +++ b/docs/0-introduction.md @@ -1,175 +1,77 @@ -# AGL framework overview +# AGL framework ## Foreword -This document describes what we intend to do. -It may happen that our current implementation and the content of this document differ. - -In case of differences, it is assumed that this document is right -and the implementation is wrong. - -## Introduction - -During the first works in having the security model of Tizen -integrated in AGL (Automotive Grade Linux) distribution, it became -quickly obvious that the count of components specific to Tizen -to integrate was huge. - -Here is a minimal list of what was needed: - -- platform/appfw/app-installers -- platform/core/security/cert-svc -- platform/core/appfw/ail -- platform/core/appfw/aul-1 -- platform/core/appfw/libslp-db-util -- platform/core/appfw/pkgmgr-info -- platform/core/appfw/slp-pkgmgr - -But this list 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 -- ... - -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** - -Luckily, these core security components of Tizen are provided -by [meta-intel-iot-security][meta-intel], a set of yocto layers. -These layers were created by Intel to isolate Tizen specific security -components from the initial port of Tizen to Yocto. -The 3 layers are providing components for: - -- Implementing Smack LSM -- Implementing Integrity Measurement Architecture -- Implementing Tizen Security Framework - -The figure below shows the history of these layers. - -![Security_model_history][Security_model_history] - -We took the decision to use these security layers that provide the -basis of the Tizen security, the security framework. - -For the components of the application framework, built top of -the security framework, instead of pulling the huge set of packages -from Tizen, we decided to refit it by 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** -- **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**. -The binder provides the easiest way to provide secured API for -any tier. -Currently, the use of the binder is not absolutely mandatory. - -This documentation explains the framework created by IoT.bzh -by rewriting the Tizen Application Framework. -Be aware of the previous foreword. - - +This document describes the application framework of Automotive Grade Linux (AGL). +FCS (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications. ## Overview -The figure below shows the major components of the framework -and their interactions going through the following scenario: +The application framework of AGL (Automotive Grade Linux) +provides components to install and uninstall applications +as well as to run them in a secured environment. -- APPLICATION installs an other application and then launch it. +The main functionalities are: -![AppFW-APP_install_sequences][AppFW-APP_install_sequences]{:: style="width:70%;"} +- install/uninstall applications and services -Let follow the sequence of calls: +- start/terminate installed applications and services -1. APPLICATION calls its **binder** to install the OTHER application. +- answer simple queries: what is installed? what runs? -1. The binding **afm-main-binding** of the **binder** calls, through - **D-Bus** system, the system daemon to install the OTHER application. +The application framework fills the gap between the applications +development model and the effective system implementation. -1. The system **D-Bus** checks wether APPLICATION has the permission - or not to install applications by calling **CYNARA**. +In one hand, there is a programming model that includes security +features through permissions, micro service architecture through +flexible high level API, and, in the other hand, there is an +implementation of the security on the system that constrains how +to implement the programming model. -1. The system **D-Bus** transmits the request to **afm-system-daemon**. +The framework manages applications and hides them security details. +To achieves it, the framework is built on top of a secured Linux. +The current implementation uses Smack and DAC Linux security modules (LSM). - **afm-system-daemon** checks the application to install, its - signatures and rights and install it. +The programming model and the security are inspired from Tizen 3. -1. **afm-system-daemon** calls **SECURITY-MANAGER** for fulfilling - security context of the installed application. +## The programming model -1. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions - for the application. +The framework ensures that sensitive services, devices or resources +of the platform are protected. Applications can access these sensitive +resources only if explicitly permitted to do so. -1. APPLICATION call its binder to start the nearly installed OTHER application. +Applications are packaged and delivered in a digitally signed container +named *widget*. A widget contains: -1. The binding **afm-main-binding** of the **binder** calls, through - **D-Bus** session, the user daemon to launch the OTHER application. +- the application and its data +- a configuration file *config.xml* +- signature files -1. The session **D-Bus** checks wether APPLICATION has the permission - or not to start an application by calling **CYNARA**. +The format of widgets is described by W3C (World Wide Web Consortium) +technical recommendations: -1. The session **D-Bus** transmits the request to **afm-user-daemon**. +- [Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) + (note: now deprecated) -1. **afm-user-daemon** checks wether APPLICATION has the permission - or not to start the OTHER application **CYNARA**. +- [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) -1. **afm-user-daemon** uses **SECURITY-MANAGER** features to set - the security context for the OTHER application. +The format is enough flexible to include the description of permissions +and dependencies required or provided by the application. -1. **afm-user-daemon** launches the OTHER application. +Signature make possible to allow or deny permissions required by the +application based on certificates of signers. -This scenario does not cover all the features of the frameworks. -Shortly because details will be revealed in the next chapters, -the components are: +A chain of trust in the creation of certificates allows a hierarchical +structuring of permissions. -- ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules, - of setting groups, and, of creating initial content of *CYNARA* rules - for applications. +It also adds the description of dependency to other service because AGL +programming model emphasis micro-services architecture design. -- ***CYNARA***: in charge of handling API access permissions by users and by - applications. +As today this model allows the distribution of HTML, QML and binary applications +but it could be extended to any other class of applications. -- ***D-Bus***: in charge of checking security of messaging. The usual D-Bus - security rules are enhanced by *CYNARA* checking rules. - -- ***afm-system-daemon***: in charge of installing and uninstalling applications. - -- ***afm-user-daemon***: in charge of listing applications, querying application details, - starting, terminating, pausing, resuming applications and their instances - for a given user context. - -- ***afb-binder***: in charge of serving resources and features through an - HTTP interface. - -- ***afm-main-binding***: This binding allows applications to use the API - of the AGL framework. - -## Links between the "Security framework" and the "Application framework" - -The security framework refers to the security model used to ensure -security and to the tools that are provided for implementing that model. +## The security model The security model refers to how DAC (Discretionary Access Control), MAC (Mandatory Access Control) and Capabilities are used by the system @@ -177,74 +79,22 @@ 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 -- ... - 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. - -## The security framework - -The implemented security model is the security model of Tizen 3. +The implemented security model comes from 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** -- **D-Bus** compliant to Cynara. +The security framework 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. -None of these patches adds or removes any behaviour. +- **Security-Manager**: component that interact with the security module of linux (Smack) +- **Cynagora**: component to manage permissions +- **D-Bus** compliant to Cynagora: checks the permissions to deliver messages **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. - -## The application framework - -The application framework on top of the security framework -provides the components to install and uninstall applications -and to run it in a secured environment. - -The goal is to manage applications and to hide the details of -the security framework to the applications. - -For the reasons explained in introduction, we did not used the -application framework of Tizen as is but used an adaptation of it. - -The basis is kept identical: - -- The applications are distributed in a digitally signed container that must - match the specifications of widgets (web applications). - -This is described by the technical 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. +that should not impact the programming model from a user point of view**. -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" diff --git a/docs/1-afm-daemons.md b/docs/1-afm-daemons.md index a02c9f9..6ed8d09 100644 --- a/docs/1-afm-daemons.md +++ b/docs/1-afm-daemons.md @@ -1,572 +1,45 @@ -# The application framework daemons - -## Foreword - -This document describes application framework daemons -FCS (Fully Conform to Specification) implementation is still under development. -It may happen that current implementation somehow diverges with specifications. +# The application framework ## Introduction -Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications -life. -Understand that they will manage operations like: +The daemon ***afm-system-daemon*** handle applications life. +Understand that they will manage operations that mainly are: - ***installation*** - ***uninstallation*** - ***running*** -- ***suspend*** +- ***terminating*** - ***inventory*** -- ... In addition, they ensure that operations use the security framework as needed and that applications are executed in the correct context. -***D-Bus*** is in charge of transmitting orders to the appropriate daemon -depending upon ***D-Bus*** destination. - -The figure below summarizes the situation of both **afm-system-daemon** and -**afm-user-daemon** in the system. - -![afm-daemons][afm-daemons]{:: style="width:65%;"} - -## The D-Bus interface - -### Overview of the dbus interface - -The ***afm daemons*** takes theirs orders from the session instance -of D-Bus. -The use of D-Bus is great because it allows to implement -discovery and signaling. - -The dbus session is by default addressed by environment -variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd** -variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for -user sessions. - -They are listening with the destination name ***org.AGL.afm.[user|system]*** -at the object of path ***/org/AGL/afm/[user|system]*** on the interface -***org.AGL.afm.[user|system]*** for the below detailed members for the -***afm-system-daemon***: - -- ***install*** -- ***uninstall*** - -And for ***afm-user-daemon***: - -- ***runnables*** -- ***detail*** -- ***start*** -- ***once*** -- ***terminate*** -- ***pause*** -- ***resume*** -- ***runners*** -- ***state*** -- ***install*** -- ***uninstall*** - -D-Bus is mainly used for signaling and discovery. -Its optimized typed protocol is not used except for transmitting - only one string in both directions. - -The client and the service are using JSON serialization to -exchange data. -Signature of any member of the D-Bus interface is -***string -> string*** for ***JSON -> JSON***. -This is the normal case, if there is an error, current implementation -returns a dbus error that is a string. - -Here are examples using *dbus-send*, here to install an application from a -widget file: - -```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: - -```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 - -On all following sub-chapters we assume that we talk about either -***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters -are considered as self-explanatory. - -The D-Bus interface is defined by: - -- **DESTINATION**: org.AGL.afm.[user|system] -- **PATH**: /org/AGL/afm/[user|system] -- **INTERFACE**: org.AGL.afm.[user|system] - -#### Method org.AGL.afm.system.install - -**Description**: Install an application from a widget file. - -When an application with the same *id* and *version* already exists. Outside of -using *force=true* the application is not reinstalled. - -Applications are installed the subdirectories of applications common directory. -If *root* is specified, the application is installed under the -sub-directories of the *root* defined. - -Note that this methods is a simple accessor method of -***org.AGL.afm.system.install*** from ***afm-system-daemon***. - -After the installation and before returning to the sender, -***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. - -**Input**: The *path* of the widget file to install and, optionally, -a flag to *force* reinstallation, and, optionally, a *root* directory. - -Either just a string being the absolute path of the widget file: - -```bash -"/a/path/driving/to/the/widget" -``` - -Or an object: - -```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. - -```json -{"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: - -```bash -"appli@x.y" -``` - -Or an object: - -```json -{ - "id": "appli@x.y", - "root": "/a/path/to/the/root" -} -``` - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.detail - -**Description**: Get details about an application from its id. - -**Input**: the id of the application as below. - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object having the field "id" of type string: - -```json -{"id":"appli@x.y"} -``` - -**Output**: A JSON object describing the application containing -the fields described below. - -```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 -} -``` - ---- - -#### 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: - -```bash -"/a/path/driving/to/the/widget" -``` - -Or an object: - -```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. - -```json -{"added":"appli@x.y"} -``` - ---- - -#### Method org.AGL.afm.user.uninstall - -**Description**: Uninstall an application from its id. - -Note that this methods is a simple accessor to -***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***. - -After the uninstallation and before returning to the sender, -***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. - -**Input**: the *id* of the application and, optionally, the path to -application *root*. - -Either a string: - -```bash -"appli@x.y" -``` - -Or an object: +The daemon ***afm-system-daemon*** is accessible through AGL +micro-service architecture using either the binder ***afb-binder*** or +the client library ***libafbwsc***. -```json -{ - "id": "appli@x.y", - "root": "/a/path/to/the/root" -} -``` - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.start - -**Description**: - -**Input**: the *id* of the application and, optionally, the -start *mode* as below. - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object containing field "id" of type string and -optionally a field mode: - -```json -{"id":"appli@x.y","mode":"local"} -``` - -The field "mode" is a string equal to either "local" or "remote". - -[Currently the mode is not available in the systemd version] - -**output**: The *runid* of the application launched. *runid* is an integer. - ---- - -#### Method org.AGL.afm.user.once - -**Description**: - -**Input**: the *id* of the application - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object containing field "id" of type string. - -```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 -object. - ---- - -#### Method org.AGL.afm.user.terminate - -**Description**: Terminates the application attached to *runid*. - -**Input**: The *runid* (an integer) of running instance to terminate. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.stop - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.pause** instead. - ---- - -#### Method org.AGL.afm.user.continue - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.resume** instead. - ---- - -#### Method org.AGL.afm.user.pause - -[Currently not available in the systemd version] - -**Description**: Pauses the application attached to *runid* until terminate or resume. - -**Input**: The *runid* (integer) of the running instance to pause. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.resume - -[Currently not available in the systemd version] - -**Description**: Resumes the application attached to *runid* previously paused. - -**Input**: The *runid* (integer) of the running instance to resume. - -**output**: the value 'true'. +## Starting **afm-system-daemon** ---- +***afm-system-daemon*** is launched by systemd services. +Normally, service files are located in the directory +*/lib/systemd/system/afm-system-daemon.service*. -#### Method org.AGL.afm.user.state +Internally, the daemon is built as a binding served by afb-daemon. -**Description**: Get information about a running instance of *runid*. - -**Input**: The *runid* (integer) of the running instance inspected. - -**output**: An object describing instance state. -It contains: - -- the runid (integer) -- the pids of the processes as an array starting -- with the group leader -- the id of the running application (string) -- the state of the application (string either: "starting", "running", "paused"). - -Example of returned state: - -```json - { - "runid": 2, - "pids": [ 435, 436 ], - "state": "running", - "id": "appli@x.y" - } -``` - ---- - -#### Method org.AGL.afm.user.runners - -**Description**: Get the list of currently running instances. - -**Input**: anything. - -**output**: An array of states, one per running instance, as returned by -the method ***org.AGL.afm.user.state***. - -## Starting **afm daemons** - -***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd -services attached to system and user respectively. -Normally, service files are locatedat */lib/systemd/system/afm-system-daemon.service* and -*/usr/lib/systemd/user/afm-user-daemon.service*. - -### ***afm-system-daemon*** options - -The options for launching **afm-system-daemon** are: - -```bash - -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 systemd. - - -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: - -```bash - -a - --application directory - - [Currently not available in the systemd version] - - Includes the given application directory to - the database base of applications. - - Can be repeated. - - -r - --root directory - - [Currently not available in the systemd version] - - 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) - - [Currently not available in the systemd version] - - Set the default launch mode. - The default value is 'local' - - -d - --daemon - - Daemonizes the process. It is not needed by systemd. - - -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** +## Tasks of **afm-system-daemon** ### Maintaining list of applications -At start **afm-user-daemon** scans the directories containing +At start **afm-system-daemon** scans the directories containing 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*. -When receiving such a signal, **afm-user-daemon** rebuilds its +When **afm-system-daemon** installs or removes an application, +on success it sends the signal **. +When receiving such a signal, **afm-system-daemon** rebuilds its applications list. -**afm-user-daemon** provides the data it collects about +**afm-system-daemon** provides the data it collects about applications to its clients. Clients may either request the full list of available applications or a more specific information about a @@ -574,17 +47,18 @@ given application. ### Launching application -**afm-user-daemon** launches application by using systemd. +**afm-system-daemon** launches application by using systemd. 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. On previous versions, the *runid* +had a special meaning. The current version uses the linux *PID* +of the launched process as *runid*. ### Managing instances of running applications -**afm-user-daemon** manages the list of applications +**afm-system-daemon** manages the list of applications that it launched. When owning the right permissions, a client can get the list @@ -595,14 +69,15 @@ It can also terminate a given application. ### Installing and uninstalling applications If the client own the right permissions, -**afm-user-daemon** delegates that task +**afm-system-daemon** delegates that task to **afm-system-daemon**. ## 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 +The command line tool ***afm-util*** is available in devel mode. + +It uses afb-client-demo to send orders to **afm-system-daemon**. +This small scripts allows to send command to ***afm-system-daemon*** either interactively at shell prompt or scriptically. The syntax is simple: diff --git a/docs/2-widgets.md b/docs/2-widgets.md index 2a7972e..6b76027 100644 --- a/docs/2-widgets.md +++ b/docs/2-widgets.md @@ -1,7 +1,35 @@ # 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) +Applications are packaged and delivered in a digitally signed container +named *widget*. A widget contains: + +- the application and its data +- a configuration file *config.xml* +- signature files + +The format of widgets is described by W3C (World Wide Web Consortium) +technical recommendations: + +- [Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) + (note: now deprecated) + +- [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) + +Note that the technical recommendation +[Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) +is now obsolete (since 11 october 2018). +It implies that a new format of widgets can be proposed in replacement. + + +The format is enough flexible to include the description of permissions +and dependencies required or provided by the application. + +Signature make possible to allow or deny permissions required by the +application based on certificates of signers. + +A chain of trust in the creation of certificates allows a hierarchical +structuring of permissions. + +It also adds the description of dependency to other service because AGL +programming model emphasis micro-services architecture design. -In summary, **widgets are ZIP files that can be signed and -whose content is described by the file **. diff --git a/docs/2.1-widget-tools.md b/docs/2.1-widget-tools.md new file mode 100644 index 0000000..f41e2d9 --- /dev/null +++ b/docs/2.1-widget-tools.md @@ -0,0 +1,153 @@ +# Tools for managing widgets + +This project includes tools for managing widgets. +These tools are: + +- ***wgtpkg-info***: command line tool to display + informations about a widget file. + +- ***wgtpkg-install***: command line tool to + install a widget file. + +- ***wgtpkg-pack***: command line tool to create + a widget file from a widget directory. + +- ***wgtpkg-sign***: command line tool to add a signature + to a widget directory. + +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**. + +To list the files of a widget: + +```bash +unzip -l WIDGET +``` + +To extract a widget in some directory: + +```bash +unzip WIDGET -d DIRECTORY +``` + +*Note: that DIRECTORY will be created if needed*. + +## 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. + +The tool **wgtpkg-sign** creates or replace a signature file in +the directory of the widget BEFORE its packaging. + +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 +``` + +Example 2: add a distributor signature + +```bash +wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY +``` + +### Packing + +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 +``` + +## Writing a widget + +### App directory organization + +There are few directories that are by default used in the binder. At the root +directory of the widget folder, here are the directories that could be used: + +- *lib* : default directory where lies external libraries needed for + the binding. Binding could be stored here too or in another directory of your + choice. +- *htdocs* : root HTTP directory if binding has web UI. + +### The steps for writing a widget + +1. make your application +1. create its configuration file **config.xml** +1. sign it +1. pack it + +Fairly easy, no? + +## Organization of directory of applications + +### directory where are stored applications + +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: + +- /var/local/lib/afm/applications + +From here this path is referenced as: "APPDIR". + +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 + +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 have rw(x) for user and r-(x) for group and others. + +This allows every user to read every file. + +### labeling the directories of applications + +The data of a user are in its directory and are labelled by the security-manager using the application labels. + +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[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" +[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/2.1-widgets.md b/docs/2.1-widgets.md deleted file mode 100644 index f41e2d9..0000000 --- a/docs/2.1-widgets.md +++ /dev/null @@ -1,153 +0,0 @@ -# Tools for managing widgets - -This project includes tools for managing widgets. -These tools are: - -- ***wgtpkg-info***: command line tool to display - informations about a widget file. - -- ***wgtpkg-install***: command line tool to - install a widget file. - -- ***wgtpkg-pack***: command line tool to create - a widget file from a widget directory. - -- ***wgtpkg-sign***: command line tool to add a signature - to a widget directory. - -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**. - -To list the files of a widget: - -```bash -unzip -l WIDGET -``` - -To extract a widget in some directory: - -```bash -unzip WIDGET -d DIRECTORY -``` - -*Note: that DIRECTORY will be created if needed*. - -## 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. - -The tool **wgtpkg-sign** creates or replace a signature file in -the directory of the widget BEFORE its packaging. - -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 -``` - -Example 2: add a distributor signature - -```bash -wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY -``` - -### Packing - -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 -``` - -## Writing a widget - -### App directory organization - -There are few directories that are by default used in the binder. At the root -directory of the widget folder, here are the directories that could be used: - -- *lib* : default directory where lies external libraries needed for - the binding. Binding could be stored here too or in another directory of your - choice. -- *htdocs* : root HTTP directory if binding has web UI. - -### The steps for writing a widget - -1. make your application -1. create its configuration file **config.xml** -1. sign it -1. pack it - -Fairly easy, no? - -## Organization of directory of applications - -### directory where are stored applications - -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: - -- /var/local/lib/afm/applications - -From here this path is referenced as: "APPDIR". - -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 - -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 have rw(x) for user and r-(x) for group and others. - -This allows every user to read every file. - -### labeling the directories of applications - -The data of a user are in its directory and are labelled by the security-manager using the application labels. - -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[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" -[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/2.2-config.xml.md b/docs/2.2-config.xml.md index de0b8d7..413eb39 100644 --- a/docs/2.2-config.xml.md +++ b/docs/2.2-config.xml.md @@ -2,7 +2,7 @@ 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**. +that specifies the configuration file **config.xml**. ## Overview @@ -482,17 +482,6 @@ Known types for the type of content are: 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 - -This types were defined previously when the framework was not -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*** - ## The configuration file afm-unit.conf diff --git a/docs/4-quick-tutorial.md b/docs/4-quick-tutorial.md index 6ab07b7..9f455df 100644 --- a/docs/4-quick-tutorial.md +++ b/docs/4-quick-tutorial.md @@ -44,7 +44,6 @@ Connect through SSH on the target board and check for Application Framework daem $ 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 ``` @@ -52,9 +51,6 @@ 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). diff --git a/docs/5-frameworks.md b/docs/5-frameworks.md deleted file mode 100644 index 6170421..0000000 --- a/docs/5-frameworks.md +++ /dev/null @@ -1,34 +0,0 @@ -# Application framework - -## Foreword - -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 - -The application framework on top of the security framework -provides components to install and uninstall applications -as well as to run them in a secured environment. - -The goal of the framework is to manage applications and hide security details -to applications. - -For the reasons explained in introduction, it was choose not to reuse Tizen -application framework directly, but to rework a new framework inspired from Tizen. - -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. - -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. -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 deleted file mode 100644 index 71044d2..0000000 --- a/docs/5.1-application-framework.md +++ /dev/null @@ -1,74 +0,0 @@ -# Comparison to other frameworks - -- Tizen framework -- xdg-app -- ostro - -## 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 - -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 - -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 - -## 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 - -For Tizen, the following rules are set by the security manager for each application. - - System ~APP~ rwx - System ~PKG~ rwxat - System ~PKG~::RO rwxat - ~APP~ System wx - ~APP~ System::Shared rxl - ~APP~ System::Run rwxat - ~APP~ System::Log rwxa - ~APP~ _ l - User ~APP~ rwx - User ~PKG~ rwxat - User ~PKG~::RO rwxat - ~APP~ User wx - ~APP~ User::Home rxl - ~APP~ User::App::Shared rwxat - ~APP~ ~PKG~ rwxat - ~APP~ ~PKG~::RO rxl - -Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application. - -## What user can run an application`?` - -Not all user are able to run all applications. -How to manage that? - -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" diff --git a/docs/5.2-security-framework.md b/docs/5.2-security-framework.md deleted file mode 100644 index c1fff24..0000000 --- a/docs/5.2-security-framework.md +++ /dev/null @@ -1,46 +0,0 @@ -# The security framework - -NOT STARTED !!!!!! - -## Setting Smack rules for the application - -For Tizen, the following rules are set by the security manager for each application. - - System ~APP~ rwx - System ~PKG~ rwxat - System ~PKG~::RO rwxat - ~APP~ System wx - ~APP~ System::Shared rxl - ~APP~ System::Run rwxat - ~APP~ System::Log rwxa - ~APP~ _ l - User ~APP~ rwx - User ~PKG~ rwxat - User ~PKG~::RO rwxat - ~APP~ User wx - ~APP~ User::Home rxl - ~APP~ User::App::Shared rwxat - ~APP~ ~PKG~ rwxat - ~APP~ ~PKG~::RO rxl - -Here, ~PKG~ is the identifier of the package and ~APP~ is the identifier of the application. - -## What user can run an application`?` - -Not all user are able to run all applications. -How to manage that? - -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" diff --git a/docs/7-debugging.md b/docs/7-debugging.md new file mode 100644 index 0000000..c53214f --- /dev/null +++ b/docs/7-debugging.md @@ -0,0 +1,16 @@ +# Debugging + +When AGL_DEVEL is ON, the framework include several settings +in the unit generated files that can be used for debugging. + +allows several + + +/run/platform/debug/homescreen-service@0.1.env +/etc/afm/widget.env.d/ + + on_environment_enum(config, SET_TRACEREQ, "AFB_TRACEREQ", afb_hook_flags_xreq_from_text); + on_environment_enum(config, SET_TRACEEVT, "AFB_TRACEEVT", afb_hook_flags_evt_from_text); + on_environment_enum(config, SET_TRACESES, "AFB_TRACESES", afb_hook_flags_session_from_text); + on_environment_enum(config, SET_TRACEAPI, "AFB_TRACEAPI", afb_hook_flags_api_from_text); + on_environment_enum(config, SET_TRACEGLOB, "AFB_TRACEGLOB", afb_hook_flags_global_from_text); diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index bee17f1..0000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,11 +0,0 @@ -# Summary - -* [Document revisions](REVISIONS.md) -* [Introduction](0-introduction.md) -* [The afm daemons](1-afm-daemons.md) -* [Widgets](2-widgets.md) - * [Overview of widgets](2.1-widgets.md) - * [The configuration file](2.2-config.xml.md) -* [The permissions](3-permissions.md) -* [Quick tutorial](4-quick-tutorial.md) -* [History](a-history.md) diff --git a/docs/a-history.md b/docs/a-history.md index 645d7d0..0f61fce 100644 --- a/docs/a-history.md +++ b/docs/a-history.md @@ -1,7 +1,220 @@ HISTORY OF THE AGL FRAMEWORK ============================ - - march 2016: proposal of IoT.BzH - - december 2016: adoption for AGL - - march 2017: switch to systemd launcher - - november 2017: switch to systemd "system" +## Brief history + +- March 2016: proposal of IoT.BzH based on refit of tizen framework +- December 2016: adoption for AGL +- March 2017: switch to systemd launcher +- November 2017: switch to systemd "system" +- May 2018: switch to meta-security +- June 2019: switch to multi-user (to agl-driver only) +- October 2019: switch to cynagora +- January 2020: Integrates Token logic compatible with OAuth2 + +## Origin of the AGL Application Framework + +The Application Framework of AGL implements the security model +of Tizen 3 but differs from the Application Framework of Tizen +3. + +During the first works in having the security model of Tizen +integrated in AGL (Automotive Grade Linux) distribution, it became +quickly obvious that the count of components specific to Tizen +to integrate was huge. + +Here is a minimal list of what was needed: + +- platform/appfw/app-installers +- platform/core/security/cert-svc +- platform/core/appfw/ail +- platform/core/appfw/aul-1 +- platform/core/appfw/libslp-db-util +- platform/core/appfw/pkgmgr-info +- platform/core/appfw/slp-pkgmgr + +But this list 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 +- ... + +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). + +These components are : + +- **cynara** +- **security-manager** +- **D-Bus aware of cynara** + +Luckily, at the time of that work, 2016, these core security components of +Tizen were provided by [meta-intel-iot-security][meta-intel], a set of yocto +layers. + +These layers were created by Intel to isolate Tizen specific security +components from the initial port of Tizen to Yocto. +The 3 layers are providing components for: + +- Implementing Smack LSM +- Implementing Integrity Measurement Architecture +- Implementing Tizen Security Framework + +We took the decision to use these security layers that provide the +basis of the Tizen security, the security framework. + +For the components of the application framework, built top of +the security framework, instead of pulling the huge set of packages +from Tizen, we decided to refit it by 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 were : + +- **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**. +The binder provides the easiest way to provide secured API for +any tier. + + + +## Evolution of the application framework within AGL + +After its first version in March 2016 and its adoption by AGL +in december 2016, the framework evolved slowly. + +In March 2017, the application launcher of the framework was +fully replaced by systemd as a launcher. Many good reasons +advocated this replacement: + +- one less component to maintain +- immediate availability of many advanced features (cgroups, security, + automatic start, ...) +- systemd is now a well known and used standard +- the process of generating systemd services is tunable by implementors + +In November 2017, after feedback from experiments with systemd and for +solving issues related to security of AGL, the user applications and services +are switched from the systemd user space to the system space using +parametric UID. + +After Intel abandonned their [meta-intel-iot-security][meta-intel], +AGL switched to [meta-security][meta-security]. + +In June 2019, the started user is no more root and most of services +are running as not root and with lowered capabilities. + +## 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. + +The application framework manages the applications: + +- 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. + +## The security framework + +The implemented security model is the security model of Tizen 3. +This model is described [here][tizen-secu-3]. + +The security framework then comes from Tizen 3 but through +the [meta-intel]. +It includes: + +- **Security-Manager** +- **Cynara** +- **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. + +## The application framework + +The application framework on top of the security framework +provides the components to install and uninstall applications +and to run it in a secured environment. + +The goal is to manage applications and to hide the details of +the security framework to the applications. + +For the reasons explained in introduction, we did not used the +application framework of Tizen as is but used an adaptation of it. + +The basis is kept identical: + +- The applications are distributed in a digitally signed container that must + match the specifications of widgets (web applications). + +This is described by the technical 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. + +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" +[meta-security]: https://git.yoctoproject.org/cgit/cgit.cgi/meta-security/ "security and hardening tools and libraries for Linux" +[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" +[AppFW-APP_install_sequences]: pictures/AppFW-APP_install_sequences.svg +[Security_model_history]: pictures/Security_model_history.svg diff --git a/docs/api-services-book.yml b/docs/api-services-book.yml index 7e33680..4c1161e 100644 --- a/docs/api-services-book.yml +++ b/docs/api-services-book.yml @@ -14,8 +14,8 @@ books: name: The afm daemons - url: "2-widgets.md" name: Widgets - - url: "2.1-widgets.md" - name: Overview of widgets + - url: "2.1-widget-tools.md" + name: Tools for managing widgets - url: "2.2-config.xml.md" name: Widget configuration file - url: "3-permissions.md" diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index b71888b..0000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -0-introduction.md \ No newline at end of file diff --git a/docs/pictures/pictures.odp b/docs/pictures/pictures.odp new file mode 100644 index 0000000..0afac7d Binary files /dev/null and b/docs/pictures/pictures.odp differ diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 52c0fd1..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,14 +0,0 @@ -site_name: AGL Application Framework -theme: readthedocs -docs_dir: docs -pages: - - 'Introduction' : 'index.md' - - 'The afm daemons' : '1-afm-daemons.md' - - 'Widgets' : - - '' : '2-widgets.md' - - 'Overview of widgets' : '2.1-widgets.md' - - 'The configuration file' : '2.2-config.xml.md' - - 'The permissions' : '3-permissions.md' - - 'Quick tutorial' : '4-quick-tutorial.md' - - 'History' : 'a-history.md' - - 'Document revisions' : 'REVISIONS.md' -- cgit 1.2.3-korg