COMMANDS

   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 file-system, 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     file-system 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 OPEN or
  44     SAVE commands are used. When the command succeeds, a status message is
  45     sent with the keyword CACHE.
  46
  47
  48 LIST [[!]element[<TAB>[!]element[...]]]
  49     If no element path is given then a list of root elements is returned with
  50     the data response code. If given, then the entire element tree for the
  51     specified element path is returned including elements with a "target"
  52     attribute. Each element in the path is prefixed with the literal '!'
  53     character when the element contains no "target" attribute.
  54
  55     If only a single element is specified and without the literal '!' prefix,
  56     both the literal element tree and the element target (if any) tree will be
  57     shown.
  58
  59
  60 REALPATH [!]element[<TAB>[!]element[...]]
  61     Resolves all "target" attributes of the specified element path and returns
  62     the result with a data response.
  63
  64
  65 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
  66     PWMD reads the element path from the client via the Assuan INQUIRE
  67     protocol response. The STORE command is sent by itself without arguments,
  68     then the server responds with INQUIRE. The client then sends the element
  69     path prefixed by a 'D<space>' client response. When finished, the client
  70     sends 'END' on an empty line. This is needed so an element path and value
  71     can be more than 1000 bytes long.
  72
  73     This command creates a new element tree or modifies the content of an
  74     existing element path. If only a single element is specified, a new
  75     element tree is created. Otherwise, elements are TAB delimited and the
  76     content will be set to the last TAB delimited argument. If no content is
  77     specified after the last TAB then the content for the last specified
  78     element will be removed or the content will be empty if creating a new
  79     element.
  80
  81     The only restriction of element names is that they not begin with a
  82     punctuation character (the literal '!' character is an exception) or digit
  83     and not contain any whitespace. There is no whitespace between the TAB
  84     delimited elements. It is recommended that the value be base 64 encoded to
  85     prevent libXML and pwmd parsing errors.
  86
  87
  88 DELETE [!]element[<TAB>[!]element[...]]
  89     Removes an element tree from the specified element path.
  90
  91
  92 GET [!]element[<TAB>[!]element[...]]
  93     Retrieves the content of the specified element path. The data is returned
  94     with the data response code.
  95
  96
  97 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
  98     ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
  99         Stores or updates an attribute value to an element path.
 100
 101     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
 102         Removes an attribute from an element path.
 103
 104     ATTR LIST [!]element[<TAB>[!]element[...]]
 105         Gets a list of attributes from an element path.
 106
 107     ATTR GET attribute [!]element[<TAB>[!]element[...]]
 108         Gets the value of an attribute from an element path.
 109
 110     The "name" attribute (case sensitive) cannot be ATTR DELETE'd if the
 111     element path is only a single element. Although it can be ATTR SET to
 112     change the root element name.
 113
 114     See THE TARGET ATTRIBUTE below.
 115
 116
 117 DUMP
 118     Shows the in memory XML document. Hard to read unless you use pwmc
 119     included with libpwmd: echo dump | pwmc <filename>
 120
 121
 122 GETCONFIG <parameter>
 123     Returns the value of a pwmd configuration variable with a data response.
 124     If no file is open then the default value will be returned. The 'key' and
 125     'key_file' variables are ignored.
 126
 127
 128 BYE
 129     Closes the connection. Use the SAVE command before this command as any
 130     changes will be lost.
 131
 132
 133 If a command fails then the ERR response is returned followed by a protocol
 134 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 135 error codes.
 136
 137
 138 THE TARGET ATTRIBUTE
 139 --------------------
 140 There is a special attribute "target" (case sensitive) that can be set with
 141 ATTR SET. The value of this attribute is an element path somewhere else in the
 142 document:
 143
 144 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 145                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 If the element path of the "target" attribute doesn't exist, it is created.
 148 This is the only time the ATTR command will create elements.
 149
 150 When a protocol command requests <arg1> as the element path, the remaining
 151 elements after the element with the "target" attribute will be appended to
 152 <arg2>. This is useful if you have elements that share the same data. If the
 153 target is modified, the other elements "pointing" to the target will have the
 154 same content. To get the real or literal element and ignore any "target"
 155 attributes, prefix an element with a '!' character. Here's an example:
 156
 157     C> STORE
 158     S> INQUIRE STORE
 159     C> D host1<TAB>username<TAB>original username
 160     C> END
 161     S> OK
 162     C> STORE
 163     S> INQUIRE STORE
 164     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 165     C> END
 166     S> OK
 167     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 168     S> OK
 169
 170 Now host1's "target" attribute will be used:
 171
 172     C> GET host1<TAB>username
 173     S> D someuser
 174     S> OK
 175
 176 If you want host1's username, prefix the element path of the GET (or other
 177 command) element path with a '!':
 178
 179     C> GET !host1<TAB>username
 180     S> D original username
 181     S> OK
 182
 183 The target value (<arg2>) element can also have a "target" attribute:
 184
 185     C> ATTR SET target new_account host1
 186     S> OK
 187     C> GET new_account<TAB>username
 188     S> D someuser
 189     S> OK
 190
 191 The value of the "target" attribute may also be prefixed with a '!' to set the
 192 target to the actual element path and not a target of the element path:
 193
 194     C> ATTR DELETE target !new_account
 195     S> OK
 196     C> ATTR SET target new_account<TAB>username !host1<TAB>username
 197     S> OK
 198     C> GET new_account<TAB>username
 199     S> D original username
 200     S> OK
 201
 202 If the target element has been renamed or deleted afterwards, the command will
 203 fail.
 204
 205 Client's should be careful of creating target loops (a target that references
 206 itself). There's no way to break out of it unless the client disconnects or
 207 until memory runs out.
 208
 209
 210 Questions, bugs or feature requests can be sent to Ben Kibbey
 211 <bjk@luxsci.net>.