summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorJose Bollo <jose.bollo@iot.bzh>2019-10-30 17:14:21 +0100
committerJose Bollo <jose.bollo@iot.bzh>2019-10-30 17:14:21 +0100
commit283c69816157ef11aa93d54ab454a3368f35919e (patch)
treeefb47b72d5c28d541468fc303942d0eaa708488c /README.md
parentbb6458a147fd4a6743daecf5e73b88af98aad37f (diff)
Improve documentation and licenses
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'README.md')
-rw-r--r--README.md72
1 files changed, 62 insertions, 10 deletions
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/