documenting

Change-Id: I592074b392ecf75e4964756e3eed72f09652f0b4
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

1 files changed, 182 insertions, 13 deletions

diff --git a/README.md b/README.md
index 96640c5..53d54fa 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,10 @@ use of programs ***zip*** and ***unzip***, type:
 
 > cmake -DUSE_LIBZIP=0 .
 
+### Evaluation on AGL using yocto
+
+TO BE CONTINUED
+
 ## Content
 
 This package content source files for several programs.
@@ -81,7 +85,181 @@ The installed programs are:
 
 ## Description
 
-The framework defined by afm-main 
+### Actors
+
+The framework defined by afm-main is defining several actors:
+the platform designer, the application developper, the distributor,
+the user, the hacker.
+
+The platform designer defines the AGL system and its security.
+
+The application developer in link or not with hardware vendors
+is creating applications, modules, libraries, services that will
+be installed to the platform.
+
+The hacker is a user that also develops application for
+tuning its system.
+
+The distributor is the mediator between the developer and the
+user. It provides 
+
+The user is either the driver or a passenger of the car.
+
+The application, libraries, services are available on the
+platform. Somme of it are in direct interaction with users.
+Some others, like services, are used indirectly.
+
+
+### Scenarii
+
+#### Writing applications
+
+The application will receive an identifier.
+That identifier must be must have the following feature:
+
+- it must be unic to identify the application and its revisions
+- it should be short enough to be used with efficiency by
+  security components of the system
+- it can not be stolen by malicious applications that
+  would like to usurpate the application identity
+- it can be sold to other company
+
+The framework provide a facility to create an asymetric
+key that will serve all the above purposes (it currently
+doen't).
+
+Using its favorite environment, the developper
+produce applications for the target.
+
+Depending on its constraints either economic,
+technical or human, the developer choose the language
+and the environment for developing the applications.
+
+This step needs to test and to debug the application on
+a target or on a simulator of the target.
+In both cases, the code should be lively inspected and
+changed, as well as the permissions and the security
+aspects.
+
+The framework will provide facilities for debugging
+(it currently doesn't).
+
+#### Packaging applications
+
+Currently the frame work expect widgets packaged as
+specified by [Packaged Web Apps](http://www.w3.org/TR/widgets).
+
+When the application is ready, the developper
+creates a package for it. The creation of the package
+is made of few steps:
+
+- isolate the strict necessarily files and structure it 
+  to be children of only one root directory
+- sign the application with the developper key
+- sign the application with its application key
+- pack the application using zip
+
+The framework will provide facilities to package applications.
+
+Parts of the job can be made with tools provided by afm-main:
+
+- ***wgtpkg-sign*** is used to add signatures at root of the package
+- ***wgtpkg-pack*** is used to create the package file (with wgt extension).
+
+Currently, the ***config.xml*** file must be edited by hand.
+See below [Writing the config.xml](#writing-config).
+
+#### Distributing applications
+
+Normally a store will distribute the application.
+It will be the normal process. The distributor adds
+a signature to the distributed application.
+
+The added signature can allow more or less permission to
+applications. For example, a critical application nested
+in the system should have high level permissions allowing
+it to do things that should normally not be done (changing
+system configuration for example).
+To allow such an application, the distributor must sign
+it using its secret private key that will unlock the
+requested level of permissions.
+
+Currently, the frammework allows to make these steps by hand
+the programs ***unzip***, ***wgtpkg-sign*** and ***wgtpkg-pack***.
+
+The applications of the store will then be available
+for browsing and searching over HTTP/Internet.
+
+#### Installing applications
+
+The framework will provide an API for downloading and
+installing an application from stores (it currently doesn't).
+
+The current version of afm allows to install widgets
+from local files (either preinstalled or downloaded).
+
+To install a widget, you can use either the program
+***wgtpkg-installer*** while being the framework user.
+
+TO BE CONTINUED
+
+#### Launching application
+
+TO BE CONTINUED
+
+
+## Writing the config.xml <a id="writing-config"/>
+
+TO BE CONTINUED
+
+For permissions: ***urn:agl:perm:...***
+
+For plugins: ***urn:agl:plugin:...***
+
+
+## Cryptography
+
+The widgets are currently signed and checked using the library
+[XMLSec](https://www.aleksey.com/xmlsec).
+
+The current state isn't providing our keys.
+Will be done soon.
+
+TO BE CONTINUED
+
+## Extension to the packaging specifications
+
+The widgets are specified in that W3C recommandation: 
+[Packaged Web Apps](http://www.w3.org/TR/widgets).
+This model was initially designed for HTML applications.
+But it is well suited for other kind of applications.
+
+It relies on this specification that is the master
+piece of interest and the most useful part:
+[XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig).
+
+An other specification exist that isn't either mature
+nor suited for managing privileges:
+[Web App Manifest](http://www.w3.org/TR/appmanifest).
+However, it may become of actuallity in some future.
+
+The main idea is to use the file ***config.xml*** as a switch
+for several contants.
+The current specifications for ***config.xml*** are allowing
+to describe either HTML5, QML and native applications.
+Using *feature*, it is also possible to define uses of
+libraries.
+
+For more advanced uses like:
+
+- incremental updates
+- multiple application packages
+- system updates
+
+The file ***config.xml*** may:
+
+- either, contain a root different that *widget*
+- or, not exist, being replaced with something else.
 
 ## Comparison with Tizen framework
 
@@ -96,17 +274,8 @@ the following Tizen packages:
 
 ## Links
 
-### Details about widgets
-
-The widgets are specified in that W3C recommandation: 
-[Packaged Web Apps](http://www.w3.org/TR/widgets).
-This model was initially designed for HTML applications.
-But it is well suited for other kind of applications.
-
-### Details about dependencies
-
-For details, you can dig into internet the following links:
-
+- [Packaged Web Apps](http://www.w3.org/TR/widgets)
+- [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig)
 - [libxml2](http://xmlsoft.org/html/index.html)
 - [OpenSSL](https://www.openssl.org)
 - [XMLSec](https://www.aleksey.com/xmlsec)
@@ -115,4 +284,4 @@ For details, you can dig into internet the following links:
 - [libzip](http://www.nih.at/libzip)
 - [CMake](https://cmake.org)
 - [Security-Manager](https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager)
-
+- [Web App Manifest](http://www.w3.org/TR/appmanifest)