+++ /dev/null
-{
- "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"
-}
-# 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.
-
-<!-- pagebreak -->
+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
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"
-# 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
### 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
### 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:
# 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 <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**.
+that specifies the configuration file **config.xml**.
## Overview
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***
-
<!-- pagebreak -->
## The configuration file afm-unit.conf
$ 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
```
* **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).
+++ /dev/null
-# 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).
+++ /dev/null
-# 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"
+++ /dev/null
-# 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"
--- /dev/null
+# 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);
+++ /dev/null
-# 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)
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.
+
+<!-- pagebreak -->
+
+## 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
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"
+++ /dev/null
-0-introduction.md
\ No newline at end of file
+++ /dev/null
-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'
Code Review / src / app-framework-main.git / commitdiff