More documentation and cache access control

Change-Id: Id040ad44f862c212057a854ebaf5798da5b064b9
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>

1 files changed, 73 insertions, 26 deletions

diff --git a/README.md b/README.md
index 9c04044..8123745 100644
--- a/README.md
+++ b/README.md
@@ -11,42 +11,89 @@
 
 [Cynagora][1] is fast, simple and safe permission database
 service.
-Functions of Cynagora are:
-* checking access for certain permission
-* holding permission database
-* simple, single function API - for checking permissions
-* thin client library - to make access control even more simple
-* ability to use external agent
-(in case of policies that can't be full processed in cynagora and plugins)
+Functions of *cynagora* are:
+ * checking access for certain permission
+ * holding permission database
+ * simple, single function API - for checking permissions
+ * ability to use external agent (in case of policies that can't be full
+   processed in *cynagora* and plugins)
+
+## Basics
+
+*Cynagora* delivers permissions based on 4 keys: CLIENT, SESSION, USER,
+PERMISSION.
+
+The original principle is that a server ask cynagora if a permission
+(the key PERMISSION) is granted for a client identified by:
+
+ - its Smack label (the key CLIENT)
+ - its user identifier, uid (the key USER)
+ - its process identifier, pid (the key SESSION)
+
+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 
+
+Cynagora implements handles differently the rules targeting any sessions
+and the rules targeting specific sessions. 
 
 ## API Overview
 
-Please refer to a wiki page on [Cynagora's API][2].
+CYNAGORA comes with 2 APIs:
+
+ - a protocol API that can be easily implemented in most languages
+   (see src/cynagora-protocol.txt)
+
+ - a client C library (see src/cynagora.h)
+
+It also provide optionally for compatibility a subset of the C client libraries.
+
+## History
+
+Cynagora is a refit of [cynara][2] that allows inclusion of expirations.
+It implements the same permission database by principle but the details
+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
+case it requires _lisystemd_.
+
+Example for compiling and installing cynagora:
+
+	mkdir build
+	cd build
+	cmake ..
+	make install
+
+Options to pass to cmake:
+
+ - *WITH_SYSTEMD*: flag for generating systemd compatible units (default ON)
 
-## Documentation
+ - *WITH_CYNARA_COMPAT*: flag for producing cynara compatibility artifacts
+   (default OFF)
 
-Documentation is kept on [wiki][1].
+ - *DEFAULT_DB_DIR*: path of the directory for the database (default
+   ${CMAKE_INSTALL_FULL_LOCALSTATEDIR}/lib/cynagora)
 
-## Repositories
+ - *DEFAULT_SOCKET_DIR*: directory path of the sockets (default 
+   ${CMAKE_INSTALL_FULL_RUNSTATEDIR}/cynagora)
 
-Cynagora repositories are available on:
-* GitHub - [samsung/Cynagora][3] repository
-* tizen.org - [platform/core/security/cynagora][4] repository - requires account on tizen.org
+ - *DEFAULT_INIT_FILE*: path to the initialization file to use (default 
+   ${CMAKE_INSTALL_FULL_SYSCONFDIR}/security/cynagora.initial)
 
-## Contact information
+Example:
 
-|         Name         |              E-mail              |  Function  |
-|----------------------|----------------------------------|------------|
-| Łukasz Wojciechowski | l.wojciechow@partner.samsung.com | Maintainer |
-| Aleksander Zdyb      | a.zdyb@samsung.com               | Integrator |
+	cmake -DCMAKE_INSTALL_PREFIX=~/.local -DWITH_SYSTEMD=OFF ..
 
-## License
+# License
 
 Cynagora is licensed under a Apache License Version 2.0, January 2004.
-Available on Apache [website][5] or in LICENSE file.
+Available on Apache [website][3] or in LICENSE file.
 
-[1]: https://wiki.tizen.org/wiki/Security:Cynagora
-[2]: https://wiki.tizen.org/wiki/Security:Cynagora:API
-[3]: https://github.com/Samsung/cynagora
-[4]: https://review.tizen.org/gerrit/#/admin/projects/platform/core/security/cynagora
-[5]: https://www.apache.org/licenses/
+[1]: https://git.automotivelinux.org/src/cynagora/
+[2]: https://wiki.tizen.org/wiki/Security:Cynara
+[3]: https://www.apache.org/licenses/LICENSE-2.0