4 The widgets are described by the technical recommendations
5 [widgets] and [widgets-digsig].
7 In summary, **widgets are ZIP files that can be signed and
8 whose content is described by the file <config.xml>**.
10 The configuration file config.xml
11 ---------------------------------
13 The file **config.xml** describes important data of the application
16 - the unique identifier of the application
17 - the name of the application
18 - the type of the application
19 - the icon of the application
20 - the permissions linked to the application
21 - the services and dependancies of the application
23 The file MUST be at the root of the widget and MUST be case sensitively name
26 The file **config.xml** is a XML file described by the document
29 Here is the example of the config file for the QML application SmartHome.
32 <?xml version="1.0" encoding="UTF-8"?>
33 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
34 <name>SmartHome</name>
35 <icon src="smarthome.png"/>
36 <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
37 <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
38 automated house. The user interface is completely done with QML.</description>
39 <author>Qt team</author>
40 <license>GPL</license>
44 The most important items are:
46 - **\<widget id="......"\>**: gives the id of the widget. It must be unique.
48 - **\<widget version="......"\>**: gives the version of the widget
50 - **\<icon src="..."\>**: gives a path to the icon of the application
51 (can be repeated with different sizes)
53 - **\<content src="..." type="..."\>**: this indicates the entry point and its type.
54 The types handled are set through the file /etc/afm/afm-launch.conf
56 Further development will add handling of <feature> for requiring and providing
57 permissions and services.
61 ### Standard elements of "config.xml"
63 #### The element widget
65 ##### the attribute id of widget
67 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
69 Values for *id* are any non empty string containing only latin letters,
70 arabic digits, and the three characters '.' (dot), '-' (dash) and
73 Authors can use a mnemonic id or can pick a unique id using
74 command **uuid** or **uuidgen**.
76 #### the attribute version of widget
78 The attribute *version* is mandatory (for version 2.x, blowfish).
80 Values for *id* are any non empty string containing only latin letters,
81 arabic digits, and the three characters '.' (dot), '-' (dash) and
84 Version values are dot separated fields MAJOR.MINOR.REVISION.
86 #### The element content
88 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
89 (subject to localisation) with its attribute *src*.
91 The content designed depends on its type. See below for the known types.
95 The element *icon* is mandatory (for version 2.x, blowfish) and must
96 be unique. It must designate an image file with its attribute *src*.
98 ### Known widget types and content
100 The configuration file ***/etc/afm/afm-launch.conf*** defines the types
101 of widget known and how to launch it.
103 Known types for the type of content are (for version 2.x, blowfish):
107 content.src designates the home page of the application
109 - ***application/x-executable***:
111 content.src designates the relative path of the binary
113 - ***application/vnd.agl.url***:
115 content.src designates the url to be used
117 - ***application/vnd.agl.service***:
118 AGL service defined as a binder,
119 content.src designates the directory of provided binders,
120 http content, if any, must be put in the subdirectory ***htdocs*** of the widget
122 - ***application/vnd.agl.native***:
123 Native application with AGL service defined as a binder,
124 content.src designates the relative path of the binary,
125 bindings, if any must be put in the subdirectory ***lib*** of the widget,
126 http content, if any, must be put in the subdirectory ***htdocs*** of the widget
128 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***:
130 content.src designate the relative path of the QML root,
131 imports must be put in the subdirectory ***imports*** of the widget
133 - ***application/vnd.agl.qml.hybrid***:
134 QML application with bindings,
135 content.src designate the relative path of the QML root,
136 bindings, if any must be put in the subdirectory ***lib*** of the widget,
137 imports must be put in the subdirectory ***imports*** of the widget
139 - ***application/vnd.agl.html.hybrid***:
141 content.src designates the home page of the application,
142 bindings, if any must be put in the subdirectory ***lib*** of the widget,
143 http content must be put in the subdirectory ***htdocs*** of the widget
149 The AGL framework uses the feature tag for specifying security and binding
150 requirement of the widget.
152 The current version of AGL (up to 2.0.1, blowfish) has no fully implemented
155 The features planned to be implemented are described below.
157 #### feature name="urn:AGL:required-binding"
159 List of the bindings required by the widget.
161 Each required binding must be explicited using a <param> entry.
163 ##### param name=[required binding name]
167 - required: the binding is mandatorily needed except if the feature
168 isn't required (required="false") and in that case it is optional.
169 - optional: the binding is optional
171 #### feature name="urn:AGL:required-permission"
173 List of the permissions required by the widget.
175 Each required permission must be explicited using a <param> entry.
177 ##### param name=[required permission name]
181 - required: the permission is mandatorily needed except if the feature
182 isn't required (required="false") and in that case it is optional.
183 - optional: the permission is optional
185 #### feature name="urn:AGL:provided-binding"
187 Use this feature for each provided binding of the widget.
190 ##### param name="name"
194 The value is the string that must match the binding prefix.
197 ##### param name="src"
201 The value is the path of the shared library for the binding.
203 ##### param name="type"
207 Currently it must be ***application/vnd.agl.binding.v1***.
210 ##### param name="scope"
214 The value indicate the availability of the binidng:
216 - private: used only by the widget
217 - public: available to allowed clients as a remote service (requires permission+)
218 - inline: available to allowed clients inside their binding (unsafe, requires permission+++)
220 ##### param name="needed-binding"
224 The value is a space separated list of binding's names that the binding needs.
226 #### feature name="urn:AGL:defined-permission"
228 Each required permission must be explicited using a <param> entry.
230 ##### param name=[defined permission name]
232 The value is the level of the defined permission.
240 This level defines the level of accreditation required to get the given
241 permission. The accreditions are given by signatures of widgets.
244 Tools for managing widgets
245 --------------------------
247 This project includes tools for managing widgets.
250 - ***wgtpkg-info***: command line tool to display
251 informations about a widget file.
253 - ***wgtpkg-installer***: command line tool to
254 install a widget file.
256 - ***wgtpkg-pack***: command line tool to create
257 a widget file from a widget directory.
259 - ***wgtpkg-sign***: command line tool to add a signature
260 to a widget directory.
262 For all these commands, a tiny help is available with
263 options **-h** or **--help**.
265 There is no tool for unpacking a widget. For doing such operation,
266 you can use the command **unzip**.
268 To list the files of a widget:
274 To extract a widget in some directory:
277 $ unzip WIDGET -d DIRECTORY
280 *Note that DIRECTORY will be created if needed*.
282 Getting data about a widget file
283 ---------------------------------
285 The command **wgtpkg-info** opens a widget file, reads its **config.xml**
286 file and displays its content in a human readable way.
288 Signing and packing widget
289 --------------------------
293 To sign a widget, you need a private key and its certificate.
295 The tool **wgtpkg-sign** creates or replace a signature file in
296 the directory of the widget BEFORE its packaging.
298 There are two types of signature files: author and distributor.
300 Example 1: add an author signature
303 $ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY
306 Example 2: add a distributor signature
309 $ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY
314 This operation can be done using the command **zip** but
315 we provide the tool **wgtpkg-pack** that may add checking.
319 $ wgtpkg-pack DIRECTORY -o file.wgt
324 ### What kind of application?
326 The file **/etc/afm/afm-launch.conf** explain how to launch applications.
327 (It is the current state that use afm-user-daemon. In a future, it may be
328 replace by systemd features.)
330 Currently the applications that can be run are:
332 - binary applications: their type is ***application/x-executable***
334 - HTML5 applications: their type is ***text/html***
336 - QML applications: their type is ***text/vnd.qt.qml***
338 ### The steps for writing a widget
340 1. make your application
342 2. create its configuration file **config.xml**
350 Organization of directory of applications
351 -----------------------------------------
353 ### directory where are stored applications
355 Applications can be installed in different places: the system itself, extension device.
356 On a phone application are typically installed on the sd card.
360 - /usr/applications: system wide applications
361 - /opt/applications: removable applications
363 From here those paths are referenced as: "APPDIR".
365 The main path for applications is: APPDIR/PKGID/VER.
369 - APPDIR is as defined above
370 - PKGID is a directory whose name is the package identifier
371 - VER is the version of the package MAJOR.MINOR
373 This organization has the advantage to allow several versions to leave together.
374 This is needed for some good reasons (rolling back) and also for less good reasons (user habits).
376 ### Identity of installed files
378 All files are installed as user "afm" and group "afm".
379 All files have rw(x) for user and r-(x) for group and others.
381 This allows every user to read every file.
383 ### labeling the directories of applications
385 The data of a user are in its directory and are labelled by the security-manager
386 using the labels of the application.
388 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
389 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
390 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
391 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
394 [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies"
395 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
396 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
397 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
398 [openssl]: https://www.openssl.org "OpenSSL"
399 [xmlsec]: https://www.aleksey.com/xmlsec "XMLSec"
400 [json-c]: https://github.com/json-c/json-c "JSON-c"
401 [d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus"
402 [libzip]: http://www.nih.at/libzip "libzip"
403 [cmake]: https://cmake.org "CMake"
404 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
405 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
406 [tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page"
407 [tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview"