PROTOCOL

   1 Protocol between the server and the clients
   2 ===========================================
   3
   4 Messages are sent through a UNIX-domain sequential packet socket
   5 and authenticated by automatic passing of user credentials.
   6 For every request, a reply is sent through the same connection.
   7 Pipelining of requests is currently not supported.
   8
   9 All requests and replies are serialized as JSON objects. Requests
  10 have always the "cmd" attribute set to the name of the command.
  11 Replies always have the "error" attribute set; it contains an error
  12 message or an empty string to indicate success.
  13
  14 Some operations require root privileges. Other operations are
  15 unprivileged if no login name present, or if the correct "auth-passwd"
  16 is provided and target user has allowed administration of their
  17 account using a password authentication. Only regular password can be
  18 used for such authentication, tokens are not accepted.
  19
  20 # No operation (unprivileged)
  21 {
  22         "cmd": "nop"
  23 }
  24
  25 # Create an account (privileged)
  26 {
  27         "cmd": "create-acct",
  28         "login": "login name",
  29         "zone": "auth zone"
  30 }
  31
  32 # Delete an account (privileged)
  33 {
  34         "cmd": "delete-acct",
  35         "login": "login name",
  36         "zone": "auth zone"             # "*" to delete accounts in all zones
  37 }
  38
  39 # Create an authentication token
  40 {
  41         "cmd": "create-token",
  42         "login": "login name",
  43         "auth-passwd": "current password",
  44         "zone": "auth zone",
  45         "comment": "optional comment"
  46 }
  47 {
  48         "error": "",
  49         "token": "new token",
  50         "ident": "token id"
  51 }
  52
  53 # Delete an authentication token
  54 {
  55         "cmd": "delete-token",
  56         "login": "login name",
  57         "auth-passwd": "current password",
  58         "zone": "auth zone",
  59         "ident": "token id"                     # "*" for all tokens for the login+zone
  60 }
  61
  62 # Change parameters of a token
  63 {
  64         "cmd": "change-token"
  65         "login": "login name",
  66         "auth-passwd": "current password",
  67         "zone": "auth zone",
  68         "ident": "token id",
  69         "comment": "new comment"                # optional
  70 }
  71
  72 # Set password for an account
  73 {
  74         "cmd": "set-passwd",
  75         "login": "login name",
  76         "auth-passwd": "current password",
  77         "zone": "auth zone",
  78         "passwd": "new password"
  79 }
  80
  81 # Delete password for an account
  82 {
  83         "cmd": "delete-passwd",
  84         "login": "login name",
  85         "auth-passwd": "current password",
  86         "zone": "auth zone"
  87 }
  88
  89 # Create a temporary token
  90 {
  91         "cmd": "create-temp",
  92         "login": "login name",
  93         "auth-passwd": "current password",
  94         "zone": "auth zone",
  95         "validity": seconds             # Requested token validity
  96 }
  97 {
  98         "error": "",
  99         "token": "new token"
 100 }
 101
 102 # Authenticate a user
 103 {
 104         "cmd": "login",
 105         "login": "login name",
 106         "zone": "auth zone",
 107         "passwd": "password or token"
 108 }
 109
 110 # Allow/disallow management of selected account using password
 111 {
 112         "cmd": "allow-passwd-auth",
 113         "login": "login name",
 114         "auth-passwd": "current password",
 115         "zone": "auth zone",
 116         "allow": integer
 117 }
 118
 119 # List user's accounts and tokens
 120 {
 121         "cmd": "list-accts",
 122         "login": "login name",
 123 }
 124 {
 125         "error": "",
 126         "login: "login name",
 127         "accounts": [
 128                 {
 129                         "zone": "auth zone",
 130                         "allow-passwd-auth": integer,           # Can anybody manage this account using its password?
 131                         "tokens": [
 132                                 {
 133                                         "type": "token type",   # passwd/token
 134                                         "ident": "token id",
 135                                         "lastmod": timestamp    # UNIX timestamp of last modification
 136                                 }
 137                                 ...
 138                         ]
 139                 }
 140                 ...
 141         ]
 142 }
 143
 144 # List known authentication zones
 145 {
 146         "cmd": "list-zones"
 147 }
 148 {
 149         "error": "",
 150         "zones": [
 151                 {
 152                         "name": "auth zone",
 153                         "desc": "human-readable description",
 154                         "allow-passwd": integer,                # Does the zone support passwords?
 155                         "allow-tokens": integer,                # Does the zone support auth tokens?
 156                         "allow-passwd-auth": integer,           # Does the zone support password authentication for account management?
 157                         "max-temp-validity": seconds            # Maximum validity of temp tokens
 158                                                                 # (if no temp tokens supported)
 159                 }
 160                 ...
 161         ]
 162 }