From: Martin Mares <mj@ucw.cz>
Date: Sun, 19 Nov 2017 12:47:06 +0000 (+0100)
Subject: Added description of the protocol
X-Git-Tag: v0.9~11
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=8e22251a037850ad5aceaf06637f90b70b24afdd;p=subauth.git

Added description of the protocol
---

diff --git a/PROTOCOL b/PROTOCOL
new file mode 100644
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)
+		}
+		...
+	]
+}