Improve documentation and licenses

Signed-off-by: Jose Bollo <[email protected]>

CREDITS.md

@@ -1,9 +1,3 @@
-Thanks to Manassas for the logo (see below)
+Thanks to Samsung Poland R&D team for the concepts of cynara.
+Thanks to "Manassas" of wikipedia (a pseudo?) for the logo (see LICENSE)
 
-LOGO
-----
-
-The logo is derived from the blason of Nancy (France) as created by Manassas:
-  "Manassas Image created for the Blazon Project of the French Wikipedia.
-     [CC BY-SA 3.0 (https://creativecommons.org/licenses/by-sa/3.0)]"
-So the logo is also available using the same license.

LICENSES.md

@@ -0,0 +1,23 @@
+The work found here is distributed under the terms of the license Apache-2.0
+with the exception of the logo that is disctibuted under the terms of the
+license CC-BY-SA-3.0 (see below).
+
+The license Apache-2.0 can be found on web at URL
+  http://www.apache.org/licenses/LICENSE-2.0
+A copy is provided here file `Apache-2.0`
+
+LOGO
+----
+
+The logo is derived from the blason of Nancy (France) as created by Manassas:
+  `Manassas Image created for the Blazon Project of the French Wikipedia.
+     [CC BY-SA 3.0 (https://creativecommons.org/licenses/by-sa/3.0)]`
+See https://commons.wikimedia.org/wiki/File:Blason_Nancy_54.svg.
+
+So the logo files used for cynagora are also available using the same license:
+     https://creativecommons.org/licenses/by/3.0/legalcode
+A copy can be found here, file `CC-BY-SA-3.0`
+
+Files covered by this license are: `logo-cynagora.png`, `logo-cynagora-small.png`
+and `logo-cynagora.svg`.
+

README.md

@@ -34,10 +34,31 @@ In facts, the keys can be used with other values that the one primarily
 designed. For example, using the pid for the session is not safe. So it
 can be replaced with a string really identifying a session.
 
-The database of *cynagora* is made of rules that set permissions 
+The database of *cynagora* is made of rules. Each cynagora rule is
+a tuple of five strings and one integer:
+
+    (CLIENT, SESSION, USER, PERMISSION, RESULT, EXPIRE).
+
+The strings `CLIENT`, `SESSION`, `USER`, `PERMISSION` are arbitrary.
+They can also have the special value `*` (STAR) that means that the rule
+matches any value. Otherwise, the rule matches a query only if the
+value matches the string of the rule. That match is:
+
+  - case sensitive for CLIENT, SESSION, USER
+  - case insensitive for PERMISSION
+
+The string RESULT has basically one of the two values `yes` or `no`. It can
+also be an agent item that will imply a request to an existing agent.
 
 Cynagora implements handles differently the rules targeting any sessions
-and the rules targeting specific sessions. 
+and the rules targeting specific sessions. The rules that have SESSION equals
+to `*` are stored persistentely in the filesystem. That rule whose SESSION
+is not STAR are volatile and only reside in memory.
+
+Expiration is a 64 bits signed integer that express the date of expiration
+of the rule in epoch (number of seconds since 1 January 1970). The special
+value 0 means no expiration, permanent rule. The negative values are used
+to avoid caching, their expiration value is given by the formula `-(1 + x)`.
 
 ## API Overview
 
@@ -56,12 +77,24 @@ Cynagora is a refit of [cynara][2] that allows inclusion of expirations.
 It implements the same permission database by principle but the details
 changes.
 
+As a possible replacement, cynagora can supply a simple compatibility
+library that offers light legacy API of cynara. This would allow to run
+simple cynara clients (admin/check/async-check but not agents) without
+changes.
+
 # Compiling
 
-The compilation use the build system *cmake*. Cynagora has no dependencies.
-However, it can be built for using it with systemd activation. In that
+Cynagora is written in language C.
+
+Cynagora only depends of _libcap_ that is used by the cynagora server.
+
+The server can be built for using systemd socket activation. In that
 case it requires _lisystemd_.
 
+## Compiling with cmake and make
+
+The compilation use the build system *cmake*. 
+
 Example for compiling and installing cynagora:
 
 	mkdir build
@@ -73,9 +106,6 @@ Options to pass to cmake:
 
  - *WITH_SYSTEMD*: flag for generating systemd compatible units (default ON)
 
- - *WITH_CYNARA_COMPAT*: flag for producing cynara compatibility artifacts
-   (default OFF)
-
  - *DEFAULT_DB_DIR*: path of the directory for the database (default
    ${CMAKE_INSTALL_FULL_LOCALSTATEDIR}/lib/cynagora)
 
@@ -85,15 +115,37 @@ Options to pass to cmake:
  - *DEFAULT_INIT_FILE*: path to the initialization file to use (default 
    ${CMAKE_INSTALL_FULL_SYSCONFDIR}/security/cynagora.initial)
 
+ - *WITH_CYNARA_COMPAT*: flag for producing cynara compatibility artifacts
+   (default OFF)
+
+ - *DIRECT_CYNARA_COMPAT*: if true, dont use the shared client library to
+   access cynara server but use the static library instead, avoid a dependency
+   to the shared library.
+
 Example:
 
 	cmake -DCMAKE_INSTALL_PREFIX=~/.local -DWITH_SYSTEMD=OFF ..
+	make install
+
+## Compiling with meson and ninja
+
+You can compile using meson. Example:
+
+	meson --prefix ~/.local -Dwith-systemd=false setup build
+	ninja -C build install
+
+Option are the same that above except that they are in lower case with dash:
+*with-systemd*, *with-cynara-compat*, *direct-cynara-compat*.
+
+# Licenses
 
-# License
+Cynagora is licensed under a Apache License Version 2.0, January 2004,
+available on [Apache website][3] or in Apache-2.0 file.
 
-Cynagora is licensed under a Apache License Version 2.0, January 2004.
-Available on Apache [website][3] or in LICENSE file.
+Logo is licensed under Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0),
+avaliable on [creative commons website][4] or in CC-BY-SA-3.0 file.
 
 [1]: https://git.automotivelinux.org/src/cynagora/
 [2]: https://wiki.tizen.org/wiki/Security:Cynara
 [3]: https://www.apache.org/licenses/LICENSE-2.0
+[4]: https://creativecommons.org/licenses/by-sa/3.0/

src/cynagora-protocol.txt

@@ -8,10 +8,15 @@ Introduction
 
  - c->s:    from client to cynagora server
  - s->c:    from cynagora server to client
- - EXPIRE:  if missing, means forever
-            if positive, a number of second since EPOCH, invalid after it
  - CACHEID: a 32 bits positive integer
  - ID:      a string
+ - EXPIRE:  if missing, means: can cache forever
+            if '-', means: don't cache
+            if TIMESPEC (see below), means: valid until given relative time
+ - SEXPIRE: Same as EXPIRE but also allows TIMESPEC prefixed with '-', meaning
+            valid until given relative time and don't cache
+
+For TIMESPEC see notes.
 
 Messages
 --------
@@ -49,6 +54,8 @@ synopsis:
 	c->s test ID CLIENT SESSION USER PERMISSION
 	s->c (ack|yes|no) ID [EXPIRE]
 
+Check whether the permission is granted (yes) or not granted (no)
+or undecidable without querying an agent (ack).
 
 
 ### check a permission
@@ -58,6 +65,8 @@ synopsis:
 	c->s check ID CLIENT SESSION USER PERMISSION
 	s->c (yes|no) ID [EXPIRE]
 
+Check whether the permission is granted (yes) or not granted (no) and invoke
+agent if needed.
 
 
 ### enter critical (admin)
@@ -67,67 +76,106 @@ synopsis:
 	c->s enter
 	s->c done
 
+Start modifications (prior to set or drop).
+
+
 ### leave critical (admin)
 
 synopsis:
 
 	c->s leave [commit|rollback]
 	s->c done|error ...
 
+Terminate modifications and commit it (commit) or cancel it (rollback).
+
+
 ### erase (admin)
 
 synopsis:
 
 	c->s drop CLIENT SESSION USER PERMISSION
 	s->c done|error ...
 
+Drop the rule matching the given filter.
+
+
 ### set (admin)
 
 synopsis:
 
-	c->s set CLIENT SESSION USER PERMISSION VALUE [EXPIRE]
+	c->s set CLIENT SESSION USER PERMISSION VALUE [SEXPIRE]
 	s->c done|error ...
 
+Create the rule as given.
+
+
 ### list permissions (admin):
 
 synopsis:
 
 	c->s get CLIENT SESSION USER PERMISSION
-	s->c item CLIENT SESSION USER PERMISSION VALUE [EXPIRE]
+	s->c item CLIENT SESSION USER PERMISSION VALUE [SEXPIRE]
 	s->c ...
 	s->c done
 
+List the rules matching the given filter.
+
+
 ### logging set/get (admin)
 
 synopsis:
 
 	c->s log [on|off]
 	s->c done (on|off)
 
+Tell to log or not the queries or query the current state.
+
+
 ### register agent (agent)
 
 synopsis:
 
 	c->s agent NAME
 	s->c done|error ...
 
+Register the agent of NAME
+
+
 ### ask agent (agent):
 
 synopsis:
 
 	s->c ask ASKID NAME VALUE CLIENT SESSION USER PERMISSION
 	c->s reply ASKID ([yes|no] [always|session|one-time|EXPIRE])
 
+Receive an agent resolution request.
+
+
 ### sub check (agent):
 
 synopsis:
 
 	c->s sub ASKID ID CLIENT SESSION USER PERMISSION
 	s->c (yes|no) ID [EXPIRE]
 
+Make a check in the context of an agent resolution.
+
+
 Notes
 -----
 
+### TIMESPEC
+
+The TIMESPEC describe a number of seconds in the futur relative to now.
+It can be a simple decimal integer. I can also use letters to designate
+year (letter `y`), week (letter `w`), day (letter `d`), hour (letter `h`),
+minute (letter `m`), second (letter `s`).
+
+Examples:
+
+	- 15d
+
+
 ### CACHEID
 
 The cacheid identify the current cache. It changes each time the database