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