X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fpermissions.md;h=0c18180116bfa03f72c1509fceb9c0bb89911494;hb=2c566e2dc9df934fb3884f9d4a9ad7ffc73a4aab;hp=407fdc228a4b1af5fdcaaeb04e58e66b28956aa7;hpb=116ebba8f5b747fc8cd65e2b8aeb7f6c1566c9ee;p=src%2Fapp-framework-main.git

diff --git a/docs/permissions.md b/docs/permissions.md
index 407fdc2..0c18180 100644
--- a/docs/permissions.md
+++ b/docs/permissions.md
@@ -14,15 +14,15 @@ framework to keep installed permissions in a database.
 
 The permission names are [URN][URN] of the form:
 
-  urn:AGL:permission:<api>:<level>:<hierarchical-name>
+	urn:AGL:permission:<api>:<level>:<hierarchical-name>
 
 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 <api> and <level> and the remaining
-fields are grouped to form the <hierarchical-name>.
+fields. The 2 first fields are `<api>` and `<level>` and the remaining
+fields are grouped to form the `<hierarchical-name>`.
 
 	<api> ::= [ <pname> ]
 
@@ -32,29 +32,110 @@ fields are grouped to form the <hierarchical-name>.
 
 	<extra> ::= "-" | "." | "_" | "@"
 
-The field <api> can be made of any valid character for NSS except
+The field `<api>` can be made of any valid character for NSS except
 the characters colon and star (:*). This field designates the api
 providing the permission. This scheme is used to deduce binding requirements
-from permission requirements. The field <api> can be the empty
+from permission requirements. The field `<api>` can be the empty
 string when the permission is defined by the AGL system itself.
-The field <api> if starting with the character "@" represents
+
+[PROPOSAL 1] The field `<api>` if starting with the character "@" represents
 a transversal/cross permission not bound to any binding.
 
+[PROPOSAL 2]The field `<api>` if starting with the 2 characters "@@"
+in addition to a permission not bound to any binding, represents a
+permission that must be set at installation and that can not be
+revoked later.
+
 	<level> ::= 1*<lower>
 
-The field <level> is made only of letters in lower case.
-The field <level> can only take some predefined values:
-"system", "platform", "partner", "tiers", "owner", "public".
+The field `<level>` is made only of letters in lower case.
+The field `<level>` can only take some predefined values:
+
+ - system
+ - platform
+ - partner
+ - tiers
+ - owner
+ - public
+
+The field `<hierarchical-name>` is made of `<pname>` separated
+by colons.
 
 	<hierarchical-name> ::= <pname> 0*(":" <pname>)
 
-The field <hierarchical-name> is made <pname> separated by
-colons. The names at left are hierarchically grouping the
+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
-------------------
+
+Permission value
+----------------
+
+In some case, it could be worth to add a value to a permission.
+
+Currently, the framework allows it for permissions linked to
+systemd. But this not currently used.
+
+Conversely, permissions linked to cynara can't carry data
+except in their name.
+
+Thus to have a simple and cleaner model, it is better to forbid
+attachement of value to permission.
+
+
+Example of permissions
+----------------------
+
+Here is a list of some possible permissions. These
+permissions are available the 17th of March 2017. 
+
+ - urn:AGL:permission::platform:no-oom
+
+   Set OOMScoreAdjust=-500 to keep the out-of-memory
+   killer away.
+
+ - urn:AGL:permission::partner:real-time
+
+   Set IOSchedulingClass=realtime to give to the process
+   realtime scheduling.
+
+   Conversely, not having this permission set RestrictRealtime=on
+   to forbid realtime features.
+
+ - urn:AGL:permission::public:display
+
+   Adds the group "display" to the list of supplementary groups
+   of the process.
+
+ - urn:AGL:permission::public:syscall:clock
+
+   Without this permission SystemCallFilter=~@clock is set to
+   forfid call to clock.
+
+ - urn:AGL:permission::public:no-htdocs
+
+   The http directory served is not "htdocs" but "."
+
+ - urn:AGL:permission::public:applications:read
+
+   Allows to read data of installed applications (and to
+   access icons).
+
+ - urn:AGL:permission::partner:service:no-ws
+
+   Forbids services to provide its API through websocket.
+
+ - urn:AGL:permission::partner:service:no-dbus
+
+   Forbids services to provide its API through D-Bus.
+
+ - urn:AGL:permission::system:run-by-default
+
+   Starts automatically the application. Example: home-screen.
+
+ - http://tizen.org/privilege/internal/dbus
+
+   Permission to use D-Bus.
 
 
 [URN]: https://tools.ietf.org/rfc/rfc2141.txt "RFC 2141: URN Syntax"