From 283c69816157ef11aa93d54ab454a3368f35919e Mon Sep 17 00:00:00 2001 From: Jose Bollo Date: Wed, 30 Oct 2019 17:14:21 +0100 Subject: Improve documentation and licenses Signed-off-by: Jose Bollo --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 10 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8123745..56959a9 100644 --- a/README.md +++ b/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/ -- cgit 1.2.3-korg