PROTOCOL

   1 The data is stored in an AES-256-CBC encrypted XML file. A client connects to
   2 the server and issues commands that manipulate the data. Through the use of
   3 shared memory a file cache is created so passwords do not need to be issued
   4 for each file each time a client connects.
   5
   6 The server uses a protocol provided by libassuan to communicate with a client.
   7 An OK response is returned if a command succeeded or ERR along with an error
   8 code, if not. When a command requests data for retrieval (i.e., GET) the
   9 output is prefixed with D then a SPACE then the actual data followed by an OK
  10 response. Read the libassuan docs for more info.
  11
  12 Protocol commands:
  13
  14 OPEN <filename> [<key>]
  15     Opens <filename> using <key>. If file is not found on the filesystem, then
  16     a new document will be created. If the file is found, it is looked for in
  17     the file cache for an existing key. When found, the existing key will be
  18     used for decryption. If the cached key fails then the <key>, if specified,
  19     will be tried. When the command succeeds, a status message is sent with
  20     the keyword CACHE.
  21
  22
  23 SAVE [<key>]
  24     Encrypts and writes any changes to the file to disk. If <key> is not
  25     specified then the currently cached key will be used. If the file is a new
  26     file or the file isn't found in the file cache, <key> is required.
  27
  28
  29 ISCACHED <filename>
  30     A response code of OK will be returned if the specified file is in the
  31     file cache. If not in the cache or the file doesn't exist on the
  32     filesystem or has a size of 0, an ERR response is returned.
  33
  34
  35 CLEARCACHE [<filename>]
  36     Clears a file cache entry. This will forget the timeout and key for all or
  37     the specified file. When the command succeeds, a status message is sent
  38     with the keyword CACHE.
  39
  40
  41 CACHETIMEOUT <seconds> <filename>
  42     Specify the number of seconds the specified file will be cached. -1 will
  43     keep the cache entry forever, 0 will require the key each time the file is
  44     OPEN'ed or SAVE'd. When the command succeeds, a status message is sent
  45     with the keyword CACHE.
  46
  47
  48 LIST [element[<TAB>element[...]]]
  49     If no element path is given, then a list of accounts is returned with the
  50     data repsonse code. If given, then the element tree for the specified
  51     element path is returned. The "target" attribute is ignored for this
  52     command at the moment.
  53
  54
  55 REALPATH account[<TAB>element[...]]
  56     Resolves all "target" attributes of the specified element path and returns
  57     the result with a data response.
  58
  59
  60 STORE [!]account[<TAB>element[<TAB>element[...]]<TAB>value]
  61     PWMD reads the element path from the client via the assuan INQUIRE
  62     protocol response. The STORE command is sent by itself without arguments,
  63     then the server responds with INQUIRE. The client then sends the element
  64     path prefixed by a 'D<space>' client response. When finished, the client
  65     sends 'END' on an empty line. This is needed so an element path and value
  66     can be more than 1000 bytes long.
  67
  68     This command stores an element tree into the existing <account>, creates a
  69     new <account> tree or modifies the content of an existing element path. If
  70     no elements are specifed an empty account is created. Otherwise, elements
  71     are TAB deliminated and the content will be set to the last TAB
  72     deliminated argument. The only restriction of element names is that they
  73     not contain any whitespace. There is no whitespace between the TAB
  74     deliminated element arguments. It is recommended that the value be base 64
  75     encoded to prevent libXML and pwmd parsing errors.
  76
  77
  78 DELETE [!]account[<TAB>element[...]]
  79     Removes an element tree from <account> or the entire <account> if no
  80     elements are given.
  81
  82
  83 GET [!]<account><TAB>element[<TAB>element[...]]
  84     Retrieves the content of the specified element tree. If the account is
  85     prefixed with a '!' and an element in the element path contains a "target"
  86     attribute, the target attribute will not be followed and the actual
  87     content of the element path will be returned. See the ATTR command for
  88     details about the "target" attribute. The data is returned with the data
  89     response code.
  90
  91
  92 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
  93     ATTR SET attribute account[<TAB>element[...]] attribute_value
  94         Stores or updates an attribute and value in the element path.
  95
  96     ATTR DELETE attribute account[<TAB>element[...]]
  97         Removes the specified attribute from the element path.
  98
  99     ATTR LIST account[<TAB>element[...]]
 100         Gets a list of attributes in the element path.
 101
 102     ATTR GET attribute account[<TAB>element[...]]
 103         Gets the value of an attribute in the element path.
 104
 105     The "name" attribute (case sensitive) cannot be ATTR DELETE'd if the
 106     element path is only an account name without any elements. Although it can
 107     be ATTR SET to change the account name.
 108
 109     See THE TARGET ATTRIBUTE below.
 110
 111
 112 DUMP
 113     Shows the in memory XML document. Hard to read unless you use pwmc
 114     included with libpwmd: echo dump | pwmc <filename>
 115
 116
 117 BYE
 118     Closes the connection. Use the SAVE command before this command as any
 119     changes will be lost.
 120
 121
 122 If a command fails then the ERR response is returned followed by a protocol
 123 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 124 error codes.
 125
 126
 127 THE TARGET ATTRIBUTE
 128 --------------------
 129 There is a special attribute "target" (case sensitive)i that can be set with
 130 ATTR SET. The value of this attribute is an element path somewhere else in the
 131 document:
 132
 133 ATTR SET target [!]account[<TAB>element[...]] [!]account[<TAB>element[...]]
 134                    ^^^arg1                       ^^^arg2
 135
 136 If the element path of the "target" attribute doesn't exist, it is created.
 137 This is the only time the ATTR command will create elements.
 138
 139 When a protocol command requests <arg1> as the element path, the remaining
 140 elements after the element with the "target" attribute will be appended to
 141 <arg2>. This is useful if you have elements that share the same data. If the
 142 target is modified, the other elements will have the same value. Here's an
 143 example. C> is the client input, S> is the server response:
 144
 145     C> STORE
 146     S> INQUIRE STORE
 147     C> D host1<TAB>username<TAB>original username
 148     C> END
 149     S> OK
 150     C> STORE
 151     S> INQUIRE STORE
 152     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 153     C> END
 154     S> OK
 155     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 156     S> OK
 157
 158 Now host1's "target" attribute will be used:
 159
 160     C> GET host1<TAB>username
 161     S> D someuser
 162     S> OK
 163
 164 If you want host1's username, prefix the element path of the GET (or other
 165 command) element path with a '!':
 166
 167     C> GET !host1<TAB>username
 168     S> D original username
 169     S> OK
 170
 171 The target value (<arg2>) element can also have a "target" attribute:
 172
 173     C> ATTR SET target new_account host1
 174     S> OK
 175     C> GET new_account<TAB>username
 176     S> D someuser
 177     S> OK
 178
 179 The value of the "target" attribute may also be prefixed with a '!' to set the
 180 target to the actual element path and not a target of the element path:
 181
 182     C> ATTR DELETE target !new_account
 183     S> OK
 184     C> ATTR SET target new_account<TAB>username !host1<TAB>username
 185     S> OK
 186     C> GET new_account<TAB>username
 187     S> D original username
 188     S> OK
 189
 190 If the target element has been renamed or deleted afterwards, the command will
 191 fail.
 192
 193 Client's should be careful of creating target loops (a target that references
 194 itself). There's no way to break out of it unless the client disconnects or
 195 until memory runs out.
 196
 197
 198 Questions, bugs or feature requests can be sent to Ben Kibbey
 199 <bjk@luxsci.net>.