docs/widgets.md

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