docs/widgets.md

   1 The widgets
   2 ===========
   3
   4 The widgets
   5 -----------
   6
   7 The widgets are described by the technical recommendations
   8 [widgets] and [widgets-digsig].
   9
  10 In summary, **widgets are ZIP files that can be signed and
  11 whose content is described by the file <config.xml>**.
  12
  13 ### The configuration file config.xml
  14
  15 This is one of the important file of the widget.
  16 It fully describes the widget.
  17
  18 Here is the example of the config file for the QML application SmartHome.
  19
  20 ```xml
  21 <?xml version="1.0" encoding="UTF-8"?>
  22 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
  23   <name>SmartHome</name>
  24   <icon src="smarthome.png"/>
  25   <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
  26   <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
  27 automated house. The user interface is completely done with QML.</description>
  28   <author>Qt team</author>
  29   <license>GPL</license>
  30 </widget>
  31 ```
  32
  33 The most important items are:
  34
  35 - **\<widget id="......"\>**: gives the id of the widget. It must be unique.
  36
  37 - **\<widget version="......"\>**: gives the version of the widget
  38
  39 - **\<icon src="..."\>**: gives a path to the icon of the application
  40   (can be repeated with different sizes)
  41
  42 - **\<content src="..." type="..."\>**: this indicates the entry point and its type.
  43   The types handled are set through the file /etc/afm/afm-launch.conf
  44
  45 Further development will add handling of <feature> for requiring and providing
  46 permissions and services.
  47
  48 ### Tools for managing widgets
  49
  50 This project includes tools for managing widgets.
  51 These tools are:
  52
  53 - ***wgtpkg-info***: command line tool to display
  54   informations about a widget file.
  55
  56 - ***wgtpkg-installer***: command line tool to
  57   install a widget file.
  58
  59 - ***wgtpkg-pack***: command line tool to create
  60   a widget file from a widget directory.
  61
  62 - ***wgtpkg-sign***: command line tool to add a signature
  63   to a widget directory.
  64
  65 For all these commands, a tiny help is available with
  66 options **-h** or **--help**.
  67
  68 There is no tool for unpacking a widget. For doing such operation,
  69 you can use the command **unzip**.
  70
  71 To list the files of a widget:
  72
  73 ```bash
  74 $ unzip -l WIDGET
  75 ```
  76
  77 To extract a widget in some directory:
  78
  79 ```bash
  80 $ unzip WIDGET -d DIRECTORY
  81 ```
  82
  83 *Note that DIRECTORY will be created if needed*.
  84
  85 ### Signing a widget
  86
  87 To sign a widget, you need a private key and its certificate.
  88
  89 The tool **wgtpkg-sign** creates or replace a signature file in
  90 the directory of the widget BEFORE its packaging.
  91
  92 There are two types of signature files: author and distributor.
  93
  94 Example 1: add an author signature
  95
  96 ```bash
  97 $ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY
  98 ```
  99
 100 Example 2: add a distributor signature
 101
 102 ```bash
 103 $ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY
 104 ```
 105
 106 ### Packing a widget
 107
 108 This operation can be done using the command **zip** but
 109 we provide the tool **wgtpkg-pack** that may add checking.
 110
 111 Example:
 112 ```bash
 113 $ wgtpkg-pack DIRECTORY -o file.wgt
 114 ```
 115
 116 ### Getting data about a widget file
 117
 118 The command **wgtpkg-info** opens a widget file, reads its **config.xml**
 119 file and displays its content in a human readable way.
 120
 121 Writing a widget
 122 ----------------
 123
 124 ### What kind of application?
 125
 126 The file **/etc/afm/afm-launch.conf** explain how to launch applications.
 127 (It is the current state that use afm-user-daemon. In a future, it may be
 128 replace by systemd features.)
 129
 130 Currently the applications that can be run are:
 131
 132 - binary applications: their type is ***application/x-executable***
 133
 134 - HTML5 applications: their type is ***text/html***
 135
 136 - QML applications: their type is ***text/vnd.qt.qml***
 137
 138 ### The steps for writing a widget
 139
 140 1. make your application
 141
 142 2. create its configuration file **config.xml**
 143
 144 3. sign it
 145
 146 4. pack it
 147
 148 Fairly easy, no?
 149
 150 Organization of directory of applications
 151 -----------------------------------------
 152
 153 ### directory where are stored applications
 154
 155 Applications can be installed in different places: the system itself, extension device.
 156 On a phone application are typically installed on the sd card.
 157
 158 This translates to:
 159
 160  - /usr/applications: system wide applications
 161  - /opt/applications: removable applications
 162
 163 From here those paths are referenced as: "APPDIR".
 164
 165 The main path for applications is: APPDIR/PKGID/VER.
 166
 167 Where:
 168
 169  - APPDIR is as defined above
 170  - PKGID is a directory whose name is the package identifier
 171  - VER is the version of the package MAJOR.MINOR
 172
 173 This organization has the advantage to allow several versions to leave together.
 174 This is needed for some good reasons (rolling back) and also for less good reasons (user habits).
 175
 176 ### Identity of installed files
 177
 178 All files are installed as user "afm" and group "afm".
 179 All files have rw(x) for user and r-(x) for group and others.
 180
 181 This allows every user to read every file.
 182
 183 ### labeling the directories of applications
 184
 185 The data of a user are in its directory and are labelled by the security-manager
 186 using the labels of the application.
 187
 188 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 189 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 190 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 191 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 192 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 193 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 194 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 195 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 196 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 197 [cmake]:            https://cmake.org                                               "CMake"
 198 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 199 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 200 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 201 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 202
 203
 204
 205