COMMANDS

   1 The server uses a protocol provided by libassuan to communicate with a client.
   2 An OK response is returned when a command succeeds or ERR along with an error
   3 code and description, if not. When a command requests data for retrieval
   4 (e.g., GET) the output is prefixed with D then a single SPACE then the actual
   5 data followed by an OK response. Read the libassuan docs for more info about
   6 the protocol.
   7
   8 Protocol commands:
   9
  10 OPEN <filename> [<key>]
  11     Opens <filename> using <key>. If file is not found on the file-system, then
  12     a new document will be created. If the file is found, it is looked for in
  13     the file cache for an existing key. When found, the existing key will be
  14     used for decryption. If the cached key fails then the <key>, if specified,
  15     will be tried.
  16
  17
  18 SAVE [<key>]
  19     Writes the data to disk. The file written to is the file that was opened
  20     using the OPEN command. If <key> is not specified then the currently
  21     cached key will be used. If the file is a new file or the file isn't found
  22     in the file cache, <key> is required.
  23
  24
  25 ISCACHED <filename>
  26     An OK response is returned if the specified file is in the file cache.
  27
  28
  29 CLEARCACHE [<filename>]
  30     Clears a file cache entry. This will forget the timeout and key for all or
  31     the specified file. This command always succeeds.
  32
  33
  34 CACHETIMEOUT <seconds> <filename>
  35     Specify the number of seconds the specified file will be cached. -1 will
  36     keep the cache entry forever, 0 will require the key each time the OPEN or
  37     SAVE commands are used.
  38
  39
  40 LIST [[!]element[<TAB>[!]element[...]]]
  41     If no element path is given then a list of root elements is returned with
  42     the data response code. If given, then all reachable elements for the
  43     specified element path are returned Each element in the path is prefixed
  44     with the literal '!' character when the element contains no "target"
  45     attribute (See THE TARGET ATTRIBUTE below).
  46
  47     If only a single element is specified and without the literal '!' prefix,
  48     both the literal element tree and the element target (if any) tree will be
  49     shown.
  50
  51
  52 REALPATH [!]element[<TAB>[!]element[...]]
  53     Resolves all "target" attributes of the specified element path and returns
  54     the result with a data response.
  55
  56
  57 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
  58     Creates a new element tree or modifies the content of an existing element
  59     path. If only a single element is specified, a new root element is
  60     created. Otherwise, elements are TAB delimited and the content will be set
  61     to the last TAB delimited argument. If no content is specified after the
  62     last TAB then the content for the last specified element will be removed
  63     or the content will be empty when creating a new element.
  64
  65     The only restriction of element names is that they not begin with a
  66     punctuation character (the literal '!' character is an exception) or digit
  67     and not contain any whitespace. There is no whitespace between the TAB
  68     delimited elements. It is recommended that the value be base 64 encoded to
  69     prevent libXML and pwmd parsing errors.
  70
  71     PWMD reads the element path from the client via the Assuan INQUIRE
  72     protocol response. The STORE command is sent by itself without arguments,
  73     then the server responds with INQUIRE. The client then sends the element
  74     path prefixed by a "D " data response. When finished, the client
  75     sends "END" on an empty line. This is needed so an element path and value
  76     can be more than 1000 bytes long, the Assuan protocol line limit.
  77
  78
  79 DELETE [!]element[<TAB>[!]element[...]]
  80     Removes an element tree from the specified element path.
  81
  82
  83 GET [!]element[<TAB>[!]element[...]]
  84     Retrieves the content of the specified element path. The data is returned
  85     with a data response.
  86
  87
  88 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
  89     ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
  90         Stores or updates an attribute value to an element path.
  91
  92     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
  93         Removes an attribute from an element path.
  94
  95     ATTR LIST [!]element[<TAB>[!]element[...]]
  96         Gets a list of attributes from an element path.
  97
  98     ATTR GET attribute [!]element[<TAB>[!]element[...]]
  99         Gets the value of an attribute from an element path.
 100
 101     The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
 102     if the element path is only a root element. Although it can be SET
 103     to change the root element name.
 104
 105     See THE TARGET ATTRIBUTE below.
 106
 107
 108 DUMP
 109     Shows the in memory XML document with indenting.
 110
 111
 112 GETCONFIG <parameter>
 113     Returns the value of a pwmd configuration variable with a data response.
 114     If no file is open then the default value will be returned. The "key" and
 115     "key_file" variables are ignored.
 116
 117
 118 BYE
 119     Closes the connection. Use the SAVE command before this command as any
 120     changes will be lost.
 121
 122
 123 If a command fails then the ERR response is returned followed by a protocol
 124 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 125 error codes.
 126
 127
 128 STATUS MESSAGES
 129 ---------------
 130 Some commands send a status message to the client when successful. Status
 131 messages begin with a KEYWORD followed by the message. What messages are sent
 132 depends on what configuration options are enabled.
 133
 134     COMMAND             KEYWORD
 135     --------------------------------
 136     OPEN                DECRYPT
 137                         DECOMPRESS
 138                         CACHE
 139                         LOCKED
 140
 141     SAVE                COMPRESS
 142                         ENCRYPT
 143                         CACHE
 144                         LOCKED
 145
 146     CLEARCACHE          CACHE
 147                         LOCKED
 148
 149     CACHETIMEOUT        CACHE
 150                         LOCKED
 151
 152     ISCACHED            LOCKED
 153
 154
 155     KEYWORD             OUTPUT FORMAT
 156     ---------------------------------
 157     CACHE               <slots used> <slots available>
 158     ENCRYPT             <iterations so far>
 159     DECRYPT             <iterations so far>
 160     COMPRESS            <bytes so far> <total bytes>
 161     DECOMPRESS          <bytes so far> <total bytes>
 162     LOCKED              When another thread owns the file/key cache lock
 163                         this is sent once and the thread blocks until the
 164                         lock can be obtained and the command completes.
 165
 166
 167 THE TARGET ATTRIBUTE
 168 --------------------
 169 There is a special attribute "target" (case sensitive) that can be set with
 170 ATTR SET. The value of this attribute is an element path somewhere else in the
 171 XML document:
 172
 173 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 174                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
 175
 176 If the element path of the "target" attribute doesn't exist, it is created.
 177 This is the only time the ATTR command will create elements.
 178
 179 When a protocol command requests <arg1> as the element path, the remaining
 180 elements after the element with the "target" attribute will be appended to
 181 <arg2>. This is useful if you have elements that share the same data. If the
 182 target is modified, the other elements "pointing" to the target will have the
 183 same content. To get the real or literal element and ignore any "target"
 184 attributes, prefix an element with a '!' character. Here's an example:
 185
 186     C> STORE
 187     S> INQUIRE STORE
 188     C> D host1<TAB>username<TAB>original username
 189     C> END
 190     S> OK
 191     C> STORE
 192     S> INQUIRE STORE
 193     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 194     C> END
 195     S> OK
 196     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 197     S> OK
 198
 199 Now host1's "target" attribute will be used:
 200
 201     C> GET host1<TAB>username
 202     S> D someuser
 203     S> OK
 204
 205 If you want host1's username, prefix the element path of the GET (or other
 206 command) element path with a '!':
 207
 208     C> GET !host1<TAB>username
 209     S> D original username
 210     S> OK
 211
 212 The target value (<arg2>) element can also have a "target" attribute:
 213
 214     C> ATTR SET target new_account host1
 215     S> OK
 216     C> GET new_account<TAB>username
 217     S> D someuser
 218     S> OK
 219
 220 The value of the "target" attribute may also be prefixed with a '!' to set the
 221 target to the actual element path and not a target of the element path:
 222
 223     C> ATTR DELETE target !new_account
 224     S> OK
 225     C> ATTR SET target new_account<TAB>username !host1<TAB>username
 226     S> OK
 227     C> GET new_account<TAB>username
 228     S> D original username
 229     S> OK
 230
 231 If the target element has been renamed or deleted afterwards, the command will
 232 fail.
 233
 234 Client's should be careful of creating target loops (a target that references
 235 itself). There's no way to break out of it unless the client disconnects or
 236 until memory runs out.
 237
 238
 239 XML DOCUMENT STRUCTURE
 240 ----------------------
 241 When importing an XML data file with the -I command line option, the document
 242 should have the following DTD:
 243
 244     <?xml version="1.0"?>
 245     <!DOCTYPE accounts [
 246     <!ELEMENT accounts (account*)>
 247     <!ATTLIST account name CDATA #REQUIRED>
 248     ]>
 249
 250 "accounts" is the document root element while each root element mentioned
 251 in the above commands uses the "account" element. So if you have a root
 252 element shown with the LIST command that shows "isp", the document
 253 structure looks like this:
 254
 255     <accounts>
 256         <account name="isp">
 257         [...]
 258         </account>
 259     </accounts>
 260
 261 The DUMP command can be useful to show the current document structure.
 262
 263
 264 Questions, bugs or feature requests can be sent to Ben Kibbey
 265 <bjk@luxsci.net>.