PROTOCOL

   1 The data is stored in an AES-128-ECB encrypted XML file. A client connects to
   2 the server and issues commands that manipulate the data. Through the use of
   3 a file cache and shared memory passwords do not need to be issued for each
   4 file each time a client connects.
   5
   6 The server uses a simple protocol to communicate with a client. All non-data
   7 responses are prefixed by a server response code followed by a space followed
   8 by an (optional) description followed by a newline character. There are three
   9 non-data related response codes: NFO for informational messages, ERR for error
  10 messages and OK if the command succeeded.
  11
  12 A data response is prefixed with a BEGIN response code followed by a space
  13 then an integer specifying the number of following data bytes then a newline
  14 character. After all of the bytes have been sent a newline character then an
  15 OK response code then another newline will be sent.
  16
  17 Protocol commands:
  18
  19 OPEN <filename> [<key>]
  20     Opens <filename> using <key>. If file is not found on the filesystem, then
  21     a new file is created. If the file is found, it is looked for in the file
  22     cache for an existing key. If found, the existing key will be used for
  23     decryption. If the cached key fails then the <key>, if specified, will be
  24     tried. Note that <key> should be base64 encoded.
  25
  26
  27 SAVE [<key>]
  28     Encrypts and writes any changes to the file to disk. If <key> is not
  29     specified then the currently cached key will be used. If the file is a new
  30     file which hasn't yet been saved, <key> is required. Note that <key>
  31     should be base64 encoded.
  32
  33
  34 CACHE CLEARALL | CLEAR <filename> | ISCACHED <filename>
  35     CLEARALL - Remove all files from the cache. This will require a key for
  36                the next OPEN or SAVE command for existing files.
  37
  38     CLEAR    - Like CLEARALL but only for the specified file.
  39
  40     ISCACHED - A response code of OK will be returned if the specified file is
  41                in the file cache. If not in the cache or the file doesn't
  42                exist on the filesystem and ERR response is returned.
  43
  44     A file doesn't need to be opened to use this command.
  45
  46
  47 LIST [<account>]
  48     If no account is given, then a list of accounts is returned with a BEGIN
  49     repsonse code. If given, then the element tree for the account is
  50     returned. See the ATTR command and the VALUE attribute.
  51
  52
  53 STORE <account> [TAB <element> [TAB <element> ...] TAB <value>]
  54     Stores an element tree into the existing <account>, creates a new
  55     <account> tree or modifies the existing element path. If no elements are
  56     specifed an empty account is created. Otherwise, elements are TAB
  57     deliminated and the value will be the last TAB argument deliminated. The
  58     only restriction of element names is that they not contain any whitespace.
  59     There is no whitespace between the TAB deliminated element arguments.
  60
  61
  62 DELETE <account> [TAB <element> [TAB <element> ...]]
  63     Removes an element tree from <account> or the entire <account> if no
  64     elements are given.
  65
  66
  67 GET <account> TAB <element> [TAB <element> ...]
  68     Retrieves the base64 encoded value from <account> and the specified
  69     element tree. See the ATTR command and VALUE attribute. The data is
  70     returned with the BEGIN response code.
  71
  72
  73 ATTR SET | DELETE | LIST [<attribute>] <arg1> [arg2]
  74     ATTR SET attribute account[<TAB>element[...]] attribute_value
  75     ATTR DELETE attribute account[<TAB>element[...]]
  76     ATTR LIST account[<TAB>element[...]]
  77
  78     The NAME attribute cannot be DELETE'd if the element path is only the
  79     account name. Although it can be SET to change the account name.
  80
  81     There is one other special attribute which is TARGET. This is like a
  82     "pointer" that points to another element in the document:
  83
  84     ATTR SET TARGET account[<TAB>element[...]] account[<TAB>element[...]]
  85
  86     Then the GET and LIST commands for <arg1> would show the value of <arg2>.
  87     Note that if <arg1> has both a TARGET attribute and an element value, then
  88     only the TARGET attribute will be used in other commands. If the target
  89     has been renamed or deleted afterwards then the GET command will fail and
  90     the LIST command will silently ignore the target.
  91
  92
  93 HELP [<command>]
  94     Shows protocol command help for <command> or shows available commands if
  95     <command> is not specified. A file doesn't need to be opened to use this
  96     comand.
  97
  98
  99 DUMP
 100     Show the in memory document. Useful for pruning empty elements which
 101     aren't shown with the LIST command.
 102
 103
 104 QUIT
 105     Closes the connection. Use the SAVE command before this command as any
 106     changes will be lost.
 107
 108
 109 If a command fails then the ERR response is returned followed by a protocol
 110 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 111 error codes.
 112
 113 Ben Kibbey <bjk@luxsci.net>