From 3ab6b486ca043d237b89fe530cb10ca89b489344 Mon Sep 17 00:00:00 2001 From: Jose Bollo Date: Mon, 4 Nov 2019 12:02:03 +0100 Subject: Improvement of documentation Signed-off-by: Jose Bollo --- README.md | 19 +++- agent.md | 77 +++++++++++++++ protocol.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++ src/cynagora-protocol.txt | 184 ----------------------------------- 4 files changed, 336 insertions(+), 187 deletions(-) create mode 100644 agent.md create mode 100644 protocol.md delete mode 100644 src/cynagora-protocol.txt diff --git a/README.md b/README.md index 56959a9..e28eaaf 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,17 @@ value matches the string of the rule. That match is: - 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. +also be an agent item that will imply a request to an existing agent (see +file agent.md for details on agents). + +When more than one rule match the query, only one is selected to apply using +the following rules: + + 1. the rules that matched with the less STAR as possible are selected (it + means that selected rules must matche more precisely the request) + 2. then from the rules selected above the rule that matches more exactly + the keys in the following order of priority: session, user, client, + permission Cynagora implements handles differently the rules targeting any sessions and the rules targeting specific sessions. The rules that have SESSION equals @@ -60,14 +70,17 @@ 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)`. +Cynagora allows tiers programs to add features through the agent mechanism. +The file `agent.md` explains it more in detail. + ## API Overview CYNAGORA comes with 2 APIs: - a protocol API that can be easily implemented in most languages - (see src/cynagora-protocol.txt) + (see `protocol.md`) - - a client C library (see src/cynagora.h) + - a client C library (see `src/cynagora.h`) It also provide optionally for compatibility a subset of the C client libraries. diff --git a/agent.md b/agent.md new file mode 100644 index 0000000..4e19d45 --- /dev/null +++ b/agent.md @@ -0,0 +1,77 @@ +Agent of cynagora +================= + +Cynagora provide a mechanism called agent that allows to add logic of +autorization to cynagora. It can be used for example to query a user +to autorize or not a permission ponctually. + +Cynagora server implements a predefined agent named the `at` agent that +implements a simple redirection of a query. + +General principle +----------------- + +Rules of the database have a RESULT. That result is either `yes`, `no` or +an agent query. An agent query is of the form: + + NAME:VALUE + +where NAME is the name of the agent, VALUE is a value attached to the rule +and passed to the agent when querying it. + +The colon between the NAME and the VALUE is mandatory. + +The agent is queried to give a result with the following values: + + VALUE CLIENT SESSION USER PERMISSION + +Example of the agent AT +----------------------- + +The file `cynagora.initial` that provides a default initialisation file +has the following lines: + + * * @ADMIN * yes forever + * * 0 * @:%c:%s:@ADMIN:%p forever + +The first line defines a special user `@ADMIN` that always has the permission. +The special user can be seen as a group: the admin group. Remember that strings +of the database are conventionnal, that is that the meaning of the USER part +is conventionnal. A common convention is to use the decimal representation of +the UID of the unix account to check. That convention is used on the second +line. That second line defines that the user root (UID 0) is in the group +admin. To achieve that it uses the agent-AT mecanism. + +So if no other rule was selected for the user `0` then cynagora find at least +the rule that requires to query the predefined agent `@` (AT) with the value +`%c:%s:@ADMIN:%p`. + +The agent is asked with the following values: + + - `%c:%s:@ADMIN:%p` the value + - `CLIENT`, `SESSION`, `USER` and `PERMISSION`, the values of original request + +The AT-agent use the value `%c:%s:@ADMIN:%p` to compose a check query. +it interpret the value as a colon separated rule query of cynagora, in the +order: client, session, user, permission. Then it replaces any occurency of: + + - `%c` with value of `CLIENT` of original request + - `%s` with value of `SESSION` of original request + - `%u` with value of `USER` of original request + - `%p` with value of `PERMISSION` of original request + - `%%` with `%` + - `%:` with `:` + +So for the given value, the result at the end is the result of querying +cynagora for the result of: + + - client: %c that is substituted by CLIENT + - session: %s that is substituted by SESSION + - user: @ADMIN + - permission: %p that is substituted by PERMISSION + +The query to cynagora with CLIENT SESSION @ADMIN PERMMISSION must be done using +sub-query of agents. + + + diff --git a/protocol.md b/protocol.md new file mode 100644 index 0000000..502595b --- /dev/null +++ b/protocol.md @@ -0,0 +1,243 @@ +The cynagora protocol +===================== + +Introduction +------------ + +### Notations: + + - c->s: from client to cynagora server + - s->c: from cynagora server to client + - 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 +-------- + +### hello + +synopsis: + + c->s cynagora 1 + s->c done 1 CACHEID + +The client present itself with the version of the protocol it expects to +speak (today version 1 only). The server answer yes with the acknoledged +version it will use and the CACHEID that identify the cache (see note on +CACHEID) + +If hello is used, it must be the first message. If it is not used, the +protocol implicitely switch to the default version. + + +### invalidate cache + +synopsis: + + s->c clear CACHEID + +The server ask the client to clear its cache and to start the cache whose +identifier is CACHEID. + +This is the responsibility of the client to clear its cache. It is also a +decision of the client to implement or not a cache. If the client implements +a cache, it must clear that cache when it receives that message from the +server or otherwise its decisions would be wrong. + + +### test a permission + +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). + +This query ensure that the response is fast because agent are allowed to +delay requests before emitting the final status. But it doesn't ensure that +the answer is a final status. Receiving `ack` means that no final decision +can be decided. In that case the correct resolution is either to act as if +`no` were received or to ask for a check with not null probability that the +reply will take time. + + +### check a permission + +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. + +Agents are allowed to query user, remote server or any long time processing +that may delay a lot the reply. So don't forget when using check that the +reply might take time. + + +### enter critical (admin) + +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 (see FILTER). + + +### set (admin) + +synopsis: + + 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 [SEXPIRE] + s->c ... + s->c done + +List the rules matching the given filter (see 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. + +With an argument, it activates or deactivates logging. Without argument, +it does nothing. + +In all cases, returns the logging state afterward. + +Logging is a global feature. The protocol commands that the server sends or +receives are printed to the journal or not. + + +### register agent (agent) + +synopsis: + + c->s agent NAME + s->c done|error ... + +Register the agent of NAME (see AGENT-NAME). The name must be valid. The +name must not be already registered, it must be unique. + + +### ask agent (agent): + +synopsis: + + s->c ask ASKID NAME VALUE CLIENT SESSION USER PERMISSION + c->s reply ASKID (yes|no) [SEXPIRE] + +The server ask the agent of `NAME` to handle the request to the rule +CLIENT SESSION USER PERMISSION and the agent VALUE. + +The agent implementation must return its result with the given associated +ASKID. If the agent implementation has to check cynagora for replying to +an agent request, it must use sub-check requests. + + +### 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. Same as `check` but +in the context of the agent query ASKID. + + +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`). + +It can also be one of the predefined value: `*`, `forever` or `always`, all +meaning endless. + +Examples: + + - 15d 15 days + - 1h 1 hour + - 5m30s 5 minutes 30 seconds + + +### CACHEID + +The cacheid identify the current cache. It changes each time the database +changes. After a disconnection, clients can use HELLO to check whether their +version of cache is still valid. This is implemented by the default C library. + + +### FILTER + +The commands `drop` and `get` are taking rule's filters. A rule filter +is a rule that accept the special character `#` as a catch all match. + +For examples, the rule filter `# X # #` macthes the rules that have the +session `X` for any client, any user and any permission. + + +### AGENT-NAME + +Agent's name are valid if it only contains the following characters: + + - latin letters upper or lower case (distinguished): `a`..`z` or `A`..`Z` + - digits: `0`..`9` + - one of the characters `@`, `$`, `-`, `_` + +It can not be longer than 255 characters. + +The case count so the agent 'a' is not the agent 'A'. + diff --git a/src/cynagora-protocol.txt b/src/cynagora-protocol.txt deleted file mode 100644 index ea3c1c2..0000000 --- a/src/cynagora-protocol.txt +++ /dev/null @@ -1,184 +0,0 @@ -The cynagora protocol -===================== - -Introduction ------------- - -### Notations: - - - c->s: from client to cynagora server - - s->c: from cynagora server to client - - 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 --------- - -### hello - -synopsis: - - c->s cynagora 1 - s->c done 1 CACHEID - -The client present itself with the version of the protocol it expects to -speak (today version 1 only). The server answer yes with the acknoledged -version it will use and the CACHEID that identify the cache (see note on -CACHEID) - -If hello is used, it must be the first message. If it is not used, the -protocol implicitely switch to the default version. - - -### invalidate cache - -synopsis: - - s->c clear CACHEID - -The server ask the client to clear its cache and to start the cache whose -identifier is CACHEID - - -### test a permission - -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 - -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) - -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 [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 [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 -changes. After a disconnection, clients can use HELLO to check whether their -version of cache is still valid. This is implemented by the default C library. - -- cgit 1.2.3-korg