From 1d4de11a907e41c06063a2cd5028dc4101690f50 Mon Sep 17 00:00:00 2001 From: José Bollo Date: Tue, 11 Oct 2016 17:07:16 +0200 Subject: Prepare the Integration with systemd MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is an intermediate commit providing basic functionnalities for setting up integration of the framework with systemd. - file afm-unit.conf is a mustache template - translation of config.xml to json object - mustache (extended) application of the json to the template - post processing of the result for extracting unit files This processing is currently available as a test (and a tool) and will be integrated after more developement, test and validation. Signed-off-by: José Bollo --- docs/config.xml.md | 303 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/permissions.md | 61 +++++++++++ docs/widgets.md | 238 +---------------------------------------- 3 files changed, 366 insertions(+), 236 deletions(-) create mode 100644 docs/config.xml.md create mode 100644 docs/permissions.md (limited to 'docs') diff --git a/docs/config.xml.md b/docs/config.xml.md new file mode 100644 index 0000000..7f413d5 --- /dev/null +++ b/docs/config.xml.md @@ -0,0 +1,303 @@ +The configuration file config.xml +=========== + +The widgets are described by the W3C's technical recommendations +[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig] + that specifies the configuration file **config.xml**. + +Overview +-------- + +The file **config.xml** describes important data of the application +to the framework: + +- the unique identifier of the application +- the name of the application +- the type of the application +- the icon of the application +- the permissions linked to the application +- the services and dependancies of the application + +The file MUST be at the root of the widget and MUST be case sensitively name +***config.xml***. + +The file **config.xml** is a XML file described by the document +[widgets]. + +Here is the example of the config file for the QML application SmartHome. + +```xml + + + SmartHome + + + This is the Smarthome QML demo application. It shows some user interfaces for controlling an +automated house. The user interface is completely done with QML. + Qt team + GPL + +``` + +The most important items are: + +- ****: gives the id of the widget. It must be unique. + +- ****: gives the version of the widget + +- ****: gives a path to the icon of the application + (can be repeated with different sizes) + +- ****: this indicates the entry point and its type. + +Standard elements of "config.xml" +--------------------------------- + +### The element widget + +#### the attribute id of widget + +The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. + +Values for *id* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'_' (underscore). + +Authors can use a mnemonic id or can pick a unique id using +command **uuid** or **uuidgen**. + +### the attribute version of widget + +The attribute *version* is mandatory (for version 2.x, blowfish). + +Values for *version* are any non empty string containing only latin letters, +arabic digits, and the three characters '.' (dot), '-' (dash) and +'_' (underscore). + +Version values are dot separated fields MAJOR.MINOR.REVISION. +Such version would preferabily follow guidelines of +[semantic versionning][semantic-version]. + +### The element content + +The element *content* is mandatory (for version 2.x, blowfish) and must designate a file +(subject to localisation) with its attribute *src*. + +The content designed depends on its type. See below for the known types. + +### The element icon + +The element *icon* is mandatory (for version 2.x, blowfish) and must +be unique. It must designate an image file with its attribute *src*. + +AGL features +------------ + +The AGL framework uses the feature tag for specifying security and binding +requirement of the widget. + +The current version of AGL (up to 2.0.1, blowfish) has no fully implemented +features. + +The features planned to be implemented are described below. + +### feature name="urn:AGL:widget:required-binding" + +List of the bindings required by the widget. + +Each required binding must be explicited using a entry. + +Example: +```xml + + + + +``` + +This will be *virtually* translated for mustaches to the JSON +```json +"required-binding": { + "param": [ + { "name": "urn:AGL:permission:A", "value": "required", "required": true }, + { "name": "urn:AGL:permission:A", "value": "optional", "optional": true } + ], + "urn:AGL:permission:A": { "name": "urn:AGL:permission:A", "value": "required", "required": true }, + "urn:AGL:permission:B": { "name": "urn:AGL:permission:B", "value": "optional", "optional": true } +} +``` + +#### param name="#target" + +Declares the name of the component requiring the listed bindings. +Only one instance of the param "#target" is allowed. +When there is not instance of the param +The value is either: + +- required: the binding is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the binding is optional + +#### param name=[required binding name] + +The value is either: + +- required: the binding is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the binding is optional + +### feature name="urn:AGL:widget:required-permission" + +List of the permissions required by the widget. + +Each required permission must be explicited using a entry. + +#### param name=[required permission name] + +The value is either: + +- required: the permission is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the permission is optional + +### feature name="urn:AGL:widget:provided-binding" + +Use this feature for each provided binding of the widget. +The parameters are: + +#### param name="subid" + +REQUIRED + +The value is the string that must match the binding prefix. +It must be unique. + +#### param name="name" + +REQUIRED + +The value is the string that must match the binding prefix. +It must be unique. + +#### param name="src" + +REQUIRED + +The value is the path of the shared library for the binding. + +#### param name="type" + +REQUIRED + +Currently it must be ***application/vnd.agl.binding.v1***. + + +#### param name="scope" + +REQUIRED + +The value indicate the availability of the binidng: + +- private: used only by the widget +- public: available to allowed clients as a remote service (requires permission+) +- inline: available to allowed clients inside their binding (unsafe, requires permission+++) + +#### param name="needed-binding" + +OPTIONAL + +The value is a space separated list of binding's names that the binding needs. + +### feature name="urn:AGL:widget:defined-permission" + +Each required permission must be explicited using a entry. + +#### param name=[defined permission name] + +The value is the level of the defined permission. +Standard levels are: + +- system +- platform +- partner +- tiers +- public + +This level defines the level of accreditation required to get the given +permission. The accreditions are given by signatures of widgets. + +Known content types +------------------- + +The configuration file ***/etc/afm/afm-unit.conf*** defines the types +of widget known and how to launch it. + +Known types for the type of content are (for version 2.x, blowfish): + +- ***text/html***: + HTML application, + content.src designates the home page of the application + +- ***application/x-executable***: + Native application, + content.src designates the relative path of the binary + +- ***application/vnd.agl.url***: + Internet url, + content.src designates the url to be used + +- ***application/vnd.agl.service***: + AGL service defined as a binder, + content.src designates the directory of provided binders, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***application/vnd.agl.native***: + Native application with AGL service defined as a binder, + content.src designates the relative path of the binary, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***: + QML application, + content.src designate the relative path of the QML root, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.qml.hybrid***: + QML application with bindings, + content.src designate the relative path of the QML root, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.html.hybrid***: + HTML application, + content.src designates the home page of the application, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content must be put in the subdirectory ***htdocs*** of the widget + +--- + + +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" + + +[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" +[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" +[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" +[libxml2]: http://xmlsoft.org/html/index.html "libxml2" +[openssl]: https://www.openssl.org "OpenSSL" +[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" +[json-c]: https://github.com/json-c/json-c "JSON-c" +[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" +[libzip]: http://www.nih.at/libzip "libzip" +[cmake]: https://cmake.org "CMake" +[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" +[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" +[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" +[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" +[semantic-version]: http://semver.org/ "Semantic versionning" + + + diff --git a/docs/permissions.md b/docs/permissions.md new file mode 100644 index 0000000..300a719 --- /dev/null +++ b/docs/permissions.md @@ -0,0 +1,61 @@ +The permissions +=============== + + +Permission's names +------------------ + +The proposal here is to specify a naming scheme for permissions +that allows the system to be as stateless as possible. The current +current specification includes in the naming of permissions either +the name of the bound binding when existing and the level of the +permission itself. Doing this, there is no real need for the +framework to keep updated a database of installed permissions. + +The permission names are [URN][URN] of the form: + + urn:AGL:permission::: + +where "AGL" is the NID (the namespace identifier) dedicated to +AGL (note: a RFC should be produced to standardize this name space). + +The permission names are made of NSS (the namespace specific string) +starting with "permission:" and followed by colon separated +fields. The 2 first fields are and and the remaining +fields are gouped to form the . + + ::= [ ] + + ::= 1* + + ::= | | | + + ::= "-" | "." | "_" | "@" + +The field can be made of any valid character for NSS except +the characters colon and star (:*). This field designate the binding +providing the permission. It is use to deduce binding requirements +from permission requirements. The field can be the empty +string when the permission is defined by the AGL system itself. +The field if starting with the character "@" represents +a transversal permission not bound to any binding. + + ::= 1* + +The field is made only of letters in lower case. +The field can only take some predefined values: +"system", "platform", "partner", "tiers", "owner", "public". + + ::= 0*(":" ) + +The field is made separated by +colons. The names at left are hierarchically grouping the +names at right. This hierarchical behaviour is intended to +be used to request permissions using hierarchical grouping. + +Permission's level +------------------ + + +[URN]: https://tools.ietf.org/rfc/rfc2141.txt "RFC 2141: URN Syntax" + diff --git a/docs/widgets.md b/docs/widgets.md index c23faa8..2acc92a 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -1,246 +1,12 @@ The widgets =========== -The widgets are described by the technical recommendations -[widgets] and [widgets-digsig]. +The widgets are described by the W3C's technical recommendations +[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig] In summary, **widgets are ZIP files that can be signed and whose content is described by the file **. -The configuration file config.xml ---------------------------------- - -The file **config.xml** describes important data of the application -to the framework: - -- the unique identifier of the application -- the name of the application -- the type of the application -- the icon of the application -- the permissions linked to the application -- the services and dependancies of the application - -The file MUST be at the root of the widget and MUST be case sensitively name -***config.xml***. - -The file **config.xml** is a XML file described by the document -[widgets]. - -Here is the example of the config file for the QML application SmartHome. - -```xml - - - SmartHome - - - This is the Smarthome QML demo application. It shows some user interfaces for controlling an -automated house. The user interface is completely done with QML. - Qt team - GPL - -``` - -The most important items are: - -- **\**: gives the id of the widget. It must be unique. - -- **\**: gives the version of the widget - -- **\**: gives a path to the icon of the application - (can be repeated with different sizes) - -- **\**: this indicates the entry point and its type. - The types handled are set through the file /etc/afm/afm-launch.conf - -Further development will add handling of for requiring and providing -permissions and services. - ---- - -### Standard elements of "config.xml" - -#### The element widget - -##### the attribute id of widget - -The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'_' (underscore). - -Authors can use a mnemonic id or can pick a unique id using -command **uuid** or **uuidgen**. - -#### the attribute version of widget - -The attribute *version* is mandatory (for version 2.x, blowfish). - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'_' (underscore). - -Version values are dot separated fields MAJOR.MINOR.REVISION. - -#### The element content - -The element *content* is mandatory (for version 2.x, blowfish) and must designate a file -(subject to localisation) with its attribute *src*. - -The content designed depends on its type. See below for the known types. - -#### The element icon - -The element *icon* is mandatory (for version 2.x, blowfish) and must -be unique. It must designate an image file with its attribute *src*. - -### Known widget types and content - -The configuration file ***/etc/afm/afm-launch.conf*** defines the types -of widget known and how to launch it. - -Known types for the type of content are (for version 2.x, blowfish): - -- ***text/html***: - HTML application, - content.src designates the home page of the application - -- ***application/x-executable***: - Native application, - content.src designates the relative path of the binary - -- ***application/vnd.agl.url***: - Internet url, - content.src designates the url to be used - -- ***application/vnd.agl.service***: - AGL service defined as a binder, - content.src designates the directory of provided binders, - http content, if any, must be put in the subdirectory ***htdocs*** of the widget - -- ***application/vnd.agl.native***: - Native application with AGL service defined as a binder, - content.src designates the relative path of the binary, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - http content, if any, must be put in the subdirectory ***htdocs*** of the widget - -- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***: - QML application, - content.src designate the relative path of the QML root, - imports must be put in the subdirectory ***imports*** of the widget - -- ***application/vnd.agl.qml.hybrid***: - QML application with bindings, - content.src designate the relative path of the QML root, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - imports must be put in the subdirectory ***imports*** of the widget - -- ***application/vnd.agl.html.hybrid***: - HTML application, - content.src designates the home page of the application, - bindings, if any must be put in the subdirectory ***lib*** of the widget, - http content must be put in the subdirectory ***htdocs*** of the widget - ---- - -### AGL features - -The AGL framework uses the feature tag for specifying security and binding -requirement of the widget. - -The current version of AGL (up to 2.0.1, blowfish) has no fully implemented -features. - -The features planned to be implemented are described below. - -#### feature name="urn:AGL:required-binding" - -List of the bindings required by the widget. - -Each required binding must be explicited using a entry. - -##### param name=[required binding name] - -The value is either: - -- required: the binding is mandatorily needed except if the feature -isn't required (required="false") and in that case it is optional. -- optional: the binding is optional - -#### feature name="urn:AGL:required-permission" - -List of the permissions required by the widget. - -Each required permission must be explicited using a entry. - -##### param name=[required permission name] - -The value is either: - -- required: the permission is mandatorily needed except if the feature -isn't required (required="false") and in that case it is optional. -- optional: the permission is optional - -#### feature name="urn:AGL:provided-binding" - -Use this feature for each provided binding of the widget. -The parameters are: - -##### param name="name" - -REQUIRED - -The value is the string that must match the binding prefix. -It must be unique. - -##### param name="src" - -REQUIRED - -The value is the path of the shared library for the binding. - -##### param name="type" - -REQUIRED - -Currently it must be ***application/vnd.agl.binding.v1***. - - -##### param name="scope" - -REQUIRED - -The value indicate the availability of the binidng: - -- private: used only by the widget -- public: available to allowed clients as a remote service (requires permission+) -- inline: available to allowed clients inside their binding (unsafe, requires permission+++) - -##### param name="needed-binding" - -OPTIONAL - -The value is a space separated list of binding's names that the binding needs. - -#### feature name="urn:AGL:defined-permission" - -Each required permission must be explicited using a entry. - -##### param name=[defined permission name] - -The value is the level of the defined permission. -Standard levels are: - -- system -- platform -- partner -- public - -This level defines the level of accreditation required to get the given -permission. The accreditions are given by signatures of widgets. - - Tools for managing widgets -------------------------- -- cgit