docs/2.1-widgets.md

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