diff options
Diffstat (limited to 'docs/2.2-config.xml.md')
| -rw-r--r-- | docs/2.2-config.xml.md | 507 |
1 files changed, 507 insertions, 0 deletions
diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md new file mode 100644 index 0000000..cccedd4 --- /dev/null +++ b/docs/2.2-config.xml.md @@ -0,0 +1,507 @@ +Configuration file - config.xml +=============================== + +The widgets are described by the W3C's technical recommendations +[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig] + that specifies the configuration file **config.xml**. + +Overview +-------- + +The file **config.xml** describes important data of the application +to the framework: + +- the unique identifier of the application +- the name of the application +- the type of the application +- the icon of the application +- the permissions linked to the application +- the services and dependencies of the application + +The file MUST be at the root of the widget and MUST be case sensitively name +***config.xml***. + +The file **config.xml** is a XML file described by the document +[widgets]. + +Here is the example of the config file for the QML application SmartHome. + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1"> + <name>SmartHome</name> + <icon src="smarthome.png"/> + <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/> + <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an +automated house. The user interface is completely done with QML.</description> + <author>Qt team</author> + <license>GPL</license> +</widget> +``` + +The most important items are: + +- **<widget id="......"\>**: gives the id of the widget. It must be unique. + +- **<widget version="......"\>**: gives the version of the widget + +- **<icon src="..."\>**: gives a path to the icon of the application + (can be repeated with different sizes) + +- **<content src="..." type="..."\>**: this indicates the entry point and its type. + +Standard elements of "config.xml" +--------------------------------- + +### The element widget + +#### the attribute id of widget + +The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. + +Values for *id* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'\_' (underscore). + +Authors can use a mnemonic id or can pick a unique id using +command **uuid** or **uuidgen**. + +### the attribute version of widget + +The attribute *version* is mandatory (for version 2.x, blowfish). + +Values for *version* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'\_' (underscore). + +Version values are dot separated fields MAJOR.MINOR.REVISION. +Such version would preferabily follow guidelines of +[semantic versionning][semantic-version]. + +### The element content + +The element *content* is mandatory (for version 2.x, blowfish) and must designate a file +(subject to localisation) with its attribute *src*. + +The content designed depends on its type. See below for the known types. + +### The element icon + +The element *icon* is mandatory (for version 2.x, blowfish) and must +be unique. It must designate an image file with its attribute *src*. + +AGL features +------------ + +The AGL framework uses the feature tag for specifying security and binding +requirement of the widget. + +Since the migration of the framework to leverage systemd power, +the features are of important use to: + + - declare more than just an application + - declare the expected dependencies + - declare the expected permissions + - declare the exported apis + +The specification of [widgets][widgets] is intentded to describe +only one application. In the present case, we expect to describe +more than just an application. For example, a publisher could +provide a widget containing a service, an application for tuning +that service, an application that leverage the service. +Here, the term of service means a background application that +runs without IHM and whose public api can be accessed by other +applications. + +So the features are used to describe each of the possible +units of widgets. The "standard" unit in the +meaning of [widgets][widgets] is called the "main" unit. + +### feature name="urn:AGL:widget:required-api" + +List of the api required by the widget. + +Each required api must be explicited using a <param> entry. + +Example: +```xml +<feature name="urn:AGL:widget:required-api"> + <param name="#target" value="main" />> + <param name="gps" value="auto" /> + <param name="afm-main" value="link" /> +</feature> +``` + +This will be *virtually* translated for mustaches to the JSON +```json +"required-api": [ + { "name": "gps", "value": "auto" }, + { "name": "afm-main", "value": "link" } + ] +``` + +#### param name="#target" + +OPTIONAL + +Declares the name of the unit requiring the listed apis. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + +#### param name=[required api name] + +The name is the name of the required API. + +The value describes how to connect to the required api. +It is either: + + - local: + + The binding is a local shared object. + In that case, the name is the relative path of the + shared object to be loaded. + + - auto: + + The framework set automatically the kind of + the connection to the API + + - ws: + + The framework connect using internal websockets + + - dbus: + + The framework connect using internal dbus + + - link: + + The framework connect in memory by dinamically linking + + - cloud: [PROPOSAL - NOT IMPLEMENTED] + + The framework connect externally using websock. + In that case, the name includes data to access the service. + Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />` + +### feature name="urn:AGL:widget:required-permission" + +List of the permissions required by the unit. + +Each required permission must be explicited using a <param> entry. + +Example: + +```xml + <feature name="urn:AGL:widget:required-permission"> + <param name="#target" value="geoloc" /> + <param name="urn:AGL:permission:real-time" value="required" /> + <param name="urn:AGL:permission:syscall:*" value="required" /> + </feature> +``` + +This will be *virtually* translated for mustaches to the JSON + +```json +"required-permission":{ + "urn:AGL:permission:real-time":{ + "name":"urn:AGL:permission:real-time", + "value":"required" + }, + "urn:AGL:permission:syscall:*":{ + "name":"urn:AGL:permission:syscall:*", + "value":"required" + } +} +``` + +#### param name="#target" + +OPTIONAL + +Declares the name of the unit requiring the listed permissions. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + +#### param name=[required permission name] + +The value is either: + +- required: the permission is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the permission is optional + + +### feature name="urn:AGL:widget:provided-unit" + +This feature is made for declaring new units +for the widget. Using this feature, a software publisher +can provide more than one application in the same widget. + +Example: +```xml + <feature name="urn:AGL:widget:provided-unit"> + <param name="#target" value="geoloc" /> + <param name="description" value="binding of name geoloc" /> + <param name="content.src" value="index.html" /> + <param name="content.type" value="application/vnd.agl.service" /> + </feature> +``` + +This will be *virtually* translated for mustaches to the JSON +```json + { + "#target":"geoloc", + "description":"binding of name geoloc", + "content":{ + "src":"index.html", + "type":"application\/vnd.agl.service" + }, + ... + } +``` + +#### param name="#target" + +REQUIRED + +Declares the name of the unit. The default unit, the unit +of the main of the widget, has the name "main". The value +given here must be unique within the widget file. It will +be used in other places of the widget config.xml file to +designate the unit. + +Only one instance of the param "#target" is allowed. +The value can't be "main". + +#### param name="content.type" + +REQUIRED + +The mimetype of the provided unit. + +#### param name="content.src" + +A path to the + +#### other parameters + +The items that can be set for the main unit +can also be set using the params if needed. + + - description + - name.content + - name.short + - ... + + +### feature name="urn:AGL:widget:provided-api" + +Use this feature for exporting one or more API of a unit +to other widgets of the platform. + +This feature is an important feature of the framework. + +Example: + +```xml + <feature name="urn:AGL:widget:provided-api"> + <param name="#target" value="geoloc" /> + <param name="geoloc" value="auto" /> + <param name="moonloc" value="auto" /> + </feature> +``` + +This will be *virtually* translated for mustaches to the JSON + +```json + "provided-api":[ + { + "name":"geoloc", + "value":"auto" + }, + { + "name":"moonloc", + "value":"auto" + } + ], +``` + +#### param name="#target" + + +OPTIONAL + +Declares the name of the unit exporting the listed apis. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + + +#### param name=[name of exported api] + +The name give the name of the api that is exported. + +The value is one of the following values: + + - ws: + + export the api using UNIX websocket + + - dbus: + + export the API using dbus + + - auto: + + export the api using the default method(s). + + +Known content types +------------------- + +The configuration file ***/etc/afm/afm-unit.conf*** defines +how to create systemd units for widgets. + +Known types for the type of content are: + +- ***text/html***: + HTML application, + content.src designates the home page of the application + +- ***application/vnd.agl.native*** + AGL compatible native, + content.src designates the relative path of the binary. + +- ***application/vnd.agl.service***: + AGL service, content.src is not used. + +- ***application/x-executable***: + Native application, + content.src designates the relative path of the binary. + For such application, only security setup is made. + +Adding more types is easy, it just need to edit the configuration +file ***afm-unit.conf***. + +### Older content type currently not supported at the moment. + +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 +==================================== + +The integration of the framework with systemd +mainly consists of creating the systemd unit +files corresponding to the need and requirements +of the installed widgets. + +This configuration file named `afm-unit.conf` installed +on the system wiht the path `/etc/afm/afm-unit.conf` +describes how to generate all units from the *config.xml* +configuration files of widgets. The description uses an extended +version of the templating formalism of [mustache][] +to describes all the units. + +Let present how it works using the following diagram that +describes graphically the workflow of creating the unit +files for systemd `afm-unit.conf` from the configuration +file of the widget `config.xml`: + +![make-units][make-units] + +In a first step, and because [mustache][] is intended +to work on JSON representations, the configuration file is +translated to an internal JSON representation. This +representation is shown along the examples of the documentation +of the config files of widgets. + +In a second step, the mustache template `afm-unit.conf` +is instanciated using the C library [mustach][] that follows +the rules of [mustache][mustache] and with all its available +extensions: + + - use of colon (:) for explicit substitution + - test of values with = or =! + +In a third step, the result of instanciating `afm-unit.conf` +for the widget is splited in units. To achieve that goal, +the lines containing specific directives are searched. +Any directive occupy one full line. The directives are: + + - %nl + + Produce an empty line at the end + + - %begin systemd-unit + - %end systemd-unit + + Delimit the produced unit, its begin and its end + + - %systemd-unit user + - %systemd-unit system + + Tells the kind of unit (user/system) + + - %systemd-unit service NAME + - %systemd-unit socket NAME + + Gives the name and type (service or socket) of the unit. + The extension is automatically computed from the type + and must not be set in the name. + + - %systemd-unit wanted-by NAME + + Tells to install a link to the unit in the wants of NAME + +Then the computed units are then written to the filesystem +and inserted in systemd. + +The generated unit files will contain variables for internal +use of the framework. These variables are starting with `X-AFM-`. +The variables starting with `X-AFM-` but not with `X-AFM--` are +the public variables. These variables will be returned by the +framework as the details of an application (see **afm-util detail ...**). + +Variables starting with `X-AFM--` are private to the framework. +By example, the variable `X-AFM--http-port` is used to +record the allocated port for applications. + + +[mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache" +[mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates" +[make-units]: pictures/make-units.svg +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" + + +[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[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" +[semantic-version]: http://semver.org/ "Semantic versionning" + + + |