Added description of the protocol

diff --git a/PROTOCOL b/PROTOCOL
new file mode 100644 (file)
index 0000000..1abb7fa
--- /dev/null
+++ b/PROTOCOL
@@ -0,0 +1,143 @@
+Protocol between the server and the clients
+===========================================
+
+Messages are sent through a UNIX-domain sequential packet socket
+and authenticated by automatic passing of user credentials.
+For every request, a reply is sent through the same connection.
+Pipelining of requests is currently not supported.
+
+All requests and replies are serialized as JSON objects. Requests
+have always the "cmd" attribute set to the name of the command.
+Replies always have the "error" attribute set; it contains an error
+message or an empty string to indicate success.
+
+Some operations require root privileges. Other operations are
+unprivileged if no login name present, or if it matches the UID
+of the requesting user.
+
+# No operation (unprivileged)
+{
+       "cmd": "nop"
+}
+
+# Create an account (privileged)
+{
+       "cmd": "create-acct",
+       "login": "login name",
+       "zone": "auth zone"
+}
+
+# Delete an account (privileged)
+{
+       "cmd": "delete-acct",
+       "login": "login name",
+       "zone": "auth zone"             # "*" to delete accounts in all zones
+}
+
+# Create an authentication token
+{
+       "cmd": "create-token",
+       "login": "login name",
+       "zone": "auth zone",
+       "comment": "optional comment"
+}
+{
+       "error": "",
+       "token": "new token",
+       "ident": "token id"
+}
+
+# Delete an authentication token
+{
+       "cmd": "delete-token",
+       "login": "login name",
+       "zone": "auth zone",
+       "ident": "token id"                     # "*" for all tokens for the login+zone
+}
+
+# Change parameters of a token
+{
+       "cmd": "change-token"
+       "login": "login name",
+       "zone": "auth zone",
+       "ident": "token id",
+       "comment": "new comment"                # optional
+}
+
+# Set password for an account
+{
+       "cmd": "set-passwd",
+       "login": "login name",
+       "zone": "auth zone",
+       "passwd": "new password"
+}
+
+# Delete password for an account
+{
+       "cmd": "delete-passwd",
+       "login": "login name",
+       "zone": "auth zone"
+}
+
+# Create a temporary token
+{
+       "cmd": "create-temp",
+       "login": "login name",
+       "zone": "auth zone",
+       "validity": seconds             # Requested token validity
+}
+{
+       "error": "",
+       "token": "new token"
+}
+
+# Authenticate a user
+{
+       "cmd": "login",
+       "login": "login name",
+       "zone": "auth zone",
+       "passwd": "password or token"
+}
+
+# List user's accounts and tokens
+{
+       "cmd": "list-accts",
+       "login": "login name",
+}
+{
+       "error": "",
+       "login: "login name",
+       "accounts": [
+               {
+                       "zone": "auth zone",
+                       "tokens": [
+                               {
+                                       "type": "token type",   # passwd/token
+                                       "ident": "token id",
+                                       "lastmod": timestamp    # UNIX timestamp of last modification
+                               }
+                               ...
+                       ]
+               }
+               ...
+       ]
+}
+
+# List known authentication zones
+{
+       "cmd": "list-zones"
+}
+{
+       "error": "",
+       "zones": [
+               {
+                       "name": "auth zone",
+                       "desc": "human-readable description",
+                       "allow-passwd": boolean,                # Does the zone support passwords?
+                       "allow-tokens": boolean,                # Does the zone support auth tokens?
+                       "max-temp-validity": seconds            # Maximum validity of temp tokens
+                                                               # (if no temp tokens supported)
+               }
+               ...
+       ]
+}