README.md

   1 # afm-main
   2
   3 ## Overview
   4
   5 This repository is named **afm-main** because
   6 it stands for **AGL Framework Master - Main**.
   7
   8 It contains programs and services to create widgets,
   9 to install widgets, to run widgets.
  10
  11 ## How to compile?
  12
  13 This project uses CMAKE and C compiler suite to be compiled.
  14
  15 ### Dependencies
  16
  17 This package requires the following libraries or modules:
  18
  19 - ***libxml-2.0***
  20 - ***openssl***
  21 - ***xmlsec1***
  22 - ***xmlsec1-openssl***
  23 - ***json-c***
  24 - ***dbus-1***
  25 - ***security-manager***
  26
  27 This package also requires either ***libzip*** (version >= 0.11)
  28 or the binaries ***zip*** and ***unzip***. By default, it will
  29 use ***libzip***.
  30
  31 ### Compiling
  32
  33 The main scheme for compiling the project is:
  34
  35 > cmake .
  36 >
  37 > make
  38 >
  39 > sudo make install
  40
  41 By default, the installation is made in ***/usr***.
  42 To change this behaviour, you should set the variable
  43 CMAKE_INSTALL_PREFIX as in the below example:
  44
  45 > cmake -DCMAKE_INSTALL_PREFIX=/some/where .
  46
  47 You could check the documentation of the standard CMake module
  48 [GNUInstallDirs](https://cmake.org/cmake/help/v3.4/module/GNUInstallDirs.html).
  49
  50 To forbid the use of ***libzip*** and replace it with the
  51 use of programs ***zip*** and ***unzip***, type:
  52
  53 > cmake -DUSE_LIBZIP=0 .
  54
  55 ### Evaluation on AGL using yocto
  56
  57 TO BE CONTINUED
  58
  59 ## Content
  60
  61 This package content source files for several programs.
  62 The installed programs are:
  63
  64 - ***afm-system-daemon***: D-Bus daemon to install,
  65   uninstall, list the widgets.
  66
  67   It runs on the system bus.
  68
  69 - ***afm-user-daemon***: D-Bus daemon to list
  70   available widgets, to start, pause, resume, stop it.
  71
  72   It runs on the user session bus.
  73
  74 - ***wgtpkg-info***: command line tool to display
  75   information about a widget file.
  76
  77 - ***wgtpkg-installer***: command line tool to
  78   install a widget file.
  79
  80 - ***wgtpkg-pack***: command line tool to create
  81   a widget file from a widget directory.
  82
  83 - ***wgtpkg-sign***: command line tool to add a signature
  84   to a widget directory.
  85
  86 ## Description
  87
  88 ### Actors
  89
  90 The framework defined by afm-main is defining several actors:
  91 the platform designer, the application developer, the distributor,
  92 the user, the hacker.
  93
  94 The platform designer defines the AGL system and its security.
  95
  96 The application developer in link or not with hardware vendors
  97 is creating applications, modules, libraries, services that will
  98 be installed to the platform.
  99
 100 The hacker is a user that also develops application for
 101 tuning its system.
 102
 103 The distributor is the mediator between the developer and the
 104 user. It provides
 105
 106 The user is either the driver or a passenger of the car.
 107
 108 The application, libraries, services are available on the
 109 platform. Some of them are in direct interaction with users.
 110 Some others, like services, are used indirectly.
 111
 112
 113 ### Scenarii
 114
 115 #### Writing applications
 116
 117 The application will receive an identifier.
 118 That identifier must have the following feature:
 119
 120 - it must be unique to identify the application and its revisions
 121 - it should be short enough to be used with efficiency by
 122   security components of the system
 123 - it can not be stolen by malicious applications that
 124   would like to spoof the application identity
 125 - it can be sold to other company
 126
 127 The framework provide a facility to create an asymetric
 128 key that will serve all the above purposes (it currently
 129 doesn't).
 130
 131 Using its favorite environment, the developer
 132 produces applications for the target.
 133
 134 Depending on its constraints either economic,
 135 technical or human, the developer chooses the language
 136 and the environment for developing the applications.
 137
 138 This step needs to test and to debug the application on
 139 a target or on a simulator of the target.
 140 In both cases, the code should be lively inspected and
 141 changed, as well as the permissions and the security
 142 aspects.
 143
 144 The framework will provide facilities for debugging
 145 (it currently doesn't).
 146
 147 #### Packaging applications
 148
 149 Currently the framework expects widgets packaged as
 150 specified by [Packaged Web Apps](http://www.w3.org/TR/widgets).
 151
 152 When the application is ready, the developer
 153 creates a package for it. The creation of the package
 154 is made of few steps:
 155
 156 - isolate the strict necessarily files and structure it
 157   to be children of only one root directory
 158 - sign the application with the developer key
 159 - sign the application with its application key
 160 - pack the application using zip
 161
 162 The framework will provide facilities to package applications.
 163
 164 Parts of the job can be done with tools provided by afm-main:
 165
 166 - ***wgtpkg-sign*** is used to add signatures at root of the package
 167 - ***wgtpkg-pack*** is used to create the package file (with wgt extension).
 168
 169 Currently, the ***config.xml*** file must be edited by hand.
 170 See below [Writing the config.xml](#writing-config).
 171
 172 #### Distributing applications
 173
 174 Normally a store will distribute the application.
 175 It will be the normal process. The distributor adds
 176 a signature to the distributed application.
 177
 178 The added signature can allow more or less permission to
 179 applications. For example, a critical application nested
 180 in the system should have high level permissions allowing
 181 it to do things that should normally not be done (changing
 182 system configuration for example).
 183 To allow such application, the distributor must sign
 184 it using its secret private key that will unlock the
 185 requested level of permissions.
 186
 187 Currently, the framework allows to make these steps manually
 188 using ***unzip***, ***wgtpkg-sign*** and ***wgtpkg-pack*** utilities.
 189
 190 Applications of the store will then be available
 191 for browsing and searching over HTTP/Internet.
 192
 193 #### Installing applications
 194
 195 The framework will provide an API for downloading and
 196 installing an application from stores (it currently doesn't).
 197
 198 The current version of afm allows to install widgets
 199 from local files (either pre-installed or downloaded).
 200
 201 To install a widget, you can use either the program
 202 ***wgtpkg-installer*** while being the framework user.
 203
 204 TO BE CONTINUED
 205
 206 #### Launching application
 207
 208 TO BE CONTINUED
 209
 210
 211 ## Writing the config.xml <a id="writing-config"/>
 212
 213 TO BE CONTINUED
 214
 215 For permissions: ***urn:agl:perm:...***
 216
 217 For plugins: ***urn:agl:plugin:...***
 218
 219
 220 ## Cryptography
 221
 222 The widgets are currently signed and checked using the library
 223 [XMLSec](https://www.aleksey.com/xmlsec).
 224
 225 The current state isn't providing our keys.
 226 Will be done soon.
 227
 228 TO BE CONTINUED
 229
 230 ## Extension to the packaging specifications
 231
 232 The widgets are specified in that W3C recommendation:
 233 [Packaged Web Apps](http://www.w3.org/TR/widgets).
 234 This model was initially designed for HTML applications.
 235 But it is well suited for other kind of applications.
 236
 237 It relies on this specification that is the master
 238 piece of interest and the most useful part:
 239 [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig).
 240
 241 An other specification exist that isn't either mature
 242 nor suited for managing privileges:
 243 [Web App Manifest](http://www.w3.org/TR/appmanifest).
 244 However, it may become of actuallity in some future.
 245
 246 The main idea is to use the file ***config.xml*** as a switch
 247 for several constants.
 248 The current specifications for ***config.xml*** are allowing
 249 to describe either HTML5, QML and native applications.
 250 Using *feature*, it is also possible to define uses of
 251 libraries.
 252
 253 For more advanced uses like:
 254
 255 - incremental updates
 256 - multiple application packages
 257 - system updates
 258
 259 The file ***config.xml*** may:
 260
 261 - either, contain a root different that *widget*
 262 - or, not exist, being replaced with something else.
 263
 264 ## Comparison with Tizen framework
 265
 266 This package is providing few less behaviour than
 267 the following Tizen packages:
 268
 269 - platform/appfw/app-installers
 270 - platform/core/security/cert-svc
 271 - platform/core/appfw/ail
 272 - platform/core/appfw/aul-1
 273 - platform/core/appfw/libslp-db-util
 274 - platform/core/appfw/pkgmgr-info
 275 - platform/core/appfw/slp-pkgmgr
 276
 277
 278
 279 ## Links
 280
 281 - [Packaged Web Apps](http://www.w3.org/TR/widgets)
 282 - [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig)
 283 - [libxml2](http://xmlsoft.org/html/index.html)
 284 - [OpenSSL](https://www.openssl.org)
 285 - [XMLSec](https://www.aleksey.com/xmlsec)
 286 - [JSON-c](https://github.com/json-c/json-c)
 287 - [D-Bus](http://www.freedesktop.org/wiki/Software/dbus)
 288 - [libzip](http://www.nih.at/libzip)
 289 - [CMake](https://cmake.org)
 290 - [Security-Manager](https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager)
 291 - [Web App Manifest](http://www.w3.org/TR/appmanifest)