diff options
| -rw-r--r-- | README.md | 19 | ||||
| -rw-r--r-- | agent.md | 77 | ||||
| -rw-r--r-- | protocol.md (renamed from src/cynagora-protocol.txt) | 83 |
3 files changed, 164 insertions, 15 deletions
@@ -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/src/cynagora-protocol.txt b/protocol.md index ea3c1c2..502595b 100644 --- a/src/cynagora-protocol.txt +++ b/protocol.md @@ -11,8 +11,8 @@ Introduction - 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 + 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 @@ -44,8 +44,13 @@ synopsis: s->c clear CACHEID The server ask the client to clear its cache and to start the cache whose -identifier is CACHEID - +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 @@ -57,6 +62,13 @@ synopsis: 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 @@ -68,6 +80,10 @@ synopsis: 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) @@ -96,7 +112,7 @@ synopsis: c->s drop CLIENT SESSION USER PERMISSION s->c done|error ... -Drop the rule matching the given filter. +Drop the rule matching the given filter (see FILTER). ### set (admin) @@ -118,7 +134,7 @@ synopsis: s->c ... s->c done -List the rules matching the given filter. +List the rules matching the given filter (see FILTER). ### logging set/get (admin) @@ -130,6 +146,14 @@ synopsis: 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) @@ -138,7 +162,8 @@ synopsis: c->s agent NAME s->c done|error ... -Register the agent of NAME +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): @@ -146,9 +171,14 @@ Register the agent of NAME synopsis: s->c ask ASKID NAME VALUE CLIENT SESSION USER PERMISSION - c->s reply ASKID ([yes|no] [always|session|one-time|EXPIRE]) + 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. -Receive an agent resolution request. +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): @@ -158,7 +188,8 @@ 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. +Make a check in the context of an agent resolution. Same as `check` but +in the context of the agent query ASKID. Notes @@ -166,14 +197,20 @@ Notes ### TIMESPEC -The TIMESPEC describe a number of seconds in the futur relative to now. +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 + - 15d 15 days + - 1h 1 hour + - 5m30s 5 minutes 30 seconds ### CACHEID @@ -182,3 +219,25 @@ 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'. + |