summaryrefslogtreecommitdiffstats
path: root/docs/config.xml.md
blob: 889466752f22bbe488521e1074429e7fb59782bb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
The 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 dependancies of the application

The file MUST be at the root of the widget and MUST be case sensitively name
***config.xml***.

The file **config.xml** is a XML file described by the document
[widgets].

Here is the example of the config file for the QML application SmartHome.

```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"