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 it matches the UID
  16 of the requesting user.
  17
  18 # No operation (unprivileged)
  19 {
  20         "cmd": "nop"
  21 }
  22
  23 # Create an account (privileged)
  24 {
  25         "cmd": "create-acct",
  26         "login": "login name",
  27         "zone": "auth zone"
  28 }
  29
  30 # Delete an account (privileged)
  31 {
  32         "cmd": "delete-acct",
  33         "login": "login name",
  34         "zone": "auth zone"             # "*" to delete accounts in all zones
  35 }
  36
  37 # Create an authentication token
  38 {
  39         "cmd": "create-token",
  40         "login": "login name",
  41         "zone": "auth zone",
  42         "comment": "optional comment"
  43 }
  44 {
  45         "error": "",
  46         "token": "new token",
  47         "ident": "token id"
  48 }
  49
  50 # Delete an authentication token
  51 {
  52         "cmd": "delete-token",
  53         "login": "login name",
  54         "zone": "auth zone",
  55         "ident": "token id"                     # "*" for all tokens for the login+zone
  56 }
  57
  58 # Change parameters of a token
  59 {
  60         "cmd": "change-token"
  61         "login": "login name",
  62         "zone": "auth zone",
  63         "ident": "token id",
  64         "comment": "new comment"                # optional
  65 }
  66
  67 # Set password for an account
  68 {
  69         "cmd": "set-passwd",
  70         "login": "login name",
  71         "zone": "auth zone",
  72         "passwd": "new password"
  73 }
  74
  75 # Delete password for an account
  76 {
  77         "cmd": "delete-passwd",
  78         "login": "login name",
  79         "zone": "auth zone"
  80 }
  81
  82 # Create a temporary token
  83 {
  84         "cmd": "create-temp",
  85         "login": "login name",
  86         "zone": "auth zone",
  87         "validity": seconds             # Requested token validity
  88 }
  89 {
  90         "error": "",
  91         "token": "new token"
  92 }
  93
  94 # Authenticate a user
  95 {
  96         "cmd": "login",
  97         "login": "login name",
  98         "zone": "auth zone",
  99         "passwd": "password or token"
 100 }
 101
 102 # List user's accounts and tokens
 103 {
 104         "cmd": "list-accts",
 105         "login": "login name",
 106 }
 107 {
 108         "error": "",
 109         "login: "login name",
 110         "accounts": [
 111                 {
 112                         "zone": "auth zone",
 113                         "tokens": [
 114                                 {
 115                                         "type": "token type",   # passwd/token
 116                                         "ident": "token id",
 117                                         "lastmod": timestamp    # UNIX timestamp of last modification
 118                                 }
 119                                 ...
 120                         ]
 121                 }
 122                 ...
 123         ]
 124 }
 125
 126 # List known authentication zones
 127 {
 128         "cmd": "list-zones"
 129 }
 130 {
 131         "error": "",
 132         "zones": [
 133                 {
 134                         "name": "auth zone",
 135                         "desc": "human-readable description",
 136                         "allow-passwd": boolean,                # Does the zone support passwords?
 137                         "allow-tokens": boolean,                # Does the zone support auth tokens?
 138                         "max-temp-validity": seconds            # Maximum validity of temp tokens
 139                                                                 # (if no temp tokens supported)
 140                 }
 141                 ...
 142         ]
 143 }