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 if successful. Read the libassuan docs for
   6 more info about the protocol.
   7
   8
   9 PROTOCOL COMMANDS
  10 -----------------
  11
  12 OPEN <filename> [<key>]
  13     Opens <filename> using <key>. If file is not found on the file-system, then
  14     a new document will be created. If the file is found, it is looked for in
  15     the file cache for an existing key. When found, the existing key will be
  16     used for decryption. When not found, pinentry(1) will be used to retrieve
  17     the key (see OPTIONS below). You can also open another file using the
  18     same connection. When using an empty key and you want to avoid the
  19     pinentry dialog, set PINENTRY to 0 (see OPTIONS below).
  20
  21
  22 SAVE [<key>]
  23     Writes the XML document to disk. The file written to is the file that was
  24     opened using the OPEN command. If <key> is not specified then the
  25     currently cached key will be used. If the file is a new file or the file
  26     isn't found in the file cache, <key> may be used. If <key> is not
  27     specified then pinentry(1) will be used to retrieve the key (see OPTIONS
  28     below). When using an empty key and you want to avoid the pinentry dialog,
  29     set PINENTRY to 0 (see OPTIONS below).
  30
  31     When the SAVE command is sent and a key is found in the file cache, the
  32     cached key will be used. To reset the key to a new value, send the
  33     CLEARCACHE command followed by the filename, then send the SAVE command to
  34     enter a new key.
  35
  36
  37 ISCACHED <filename>
  38     An OK response is returned if the specified file is in the file cache.
  39
  40
  41 CLEARCACHE [<filename>]
  42     Clears a file cache entry. This will forget the timeout and key for all or
  43     the specified file.
  44
  45
  46 CACHETIMEOUT <seconds> <filename>
  47     Specify the number of seconds the specified file will be cached. -1 will
  48     keep the cache entry forever, 0 will require the key each time the OPEN or
  49     SAVE commands are used. Also see the "cache_timeout" configuration option.
  50
  51
  52 LIST [[!]element[<TAB>[!]element[...]]]
  53     If no element path is given then a list of root elements is returned with
  54     the data response code. If given, then all reachable elements for the
  55     specified element path are returned. Each element in the path is prefixed
  56     with the literal '!' character when the element contains no "target"
  57     attribute (See THE TARGET ATTRIBUTE below).
  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     Creates a new element tree or modifies the content of an existing element
  67     path. If only a single element is specified, a new root element is
  68     created. Otherwise, elements are TAB delimited and the content will be set
  69     to the last TAB delimited argument. If no content is specified after the
  70     last TAB then the content for the last specified element will be removed
  71     or the content will be empty when creating a new element.
  72
  73     The only restriction of element names is that they not begin with a
  74     punctuation character (the literal '!' character is an exception) or digit
  75     and not contain any whitespace. There is no whitespace between the TAB
  76     delimited elements. It is recommended that the value be base 64 encoded to
  77     prevent libXML and pwmd parsing errors.
  78
  79     PWMD reads the element path from the client via the Assuan INQUIRE
  80     protocol response. The STORE command is sent by itself without arguments,
  81     then the server responds with INQUIRE. The client then sends the element
  82     path prefixed by a "D " data response. When finished, the client
  83     sends "END" on an empty line. This is needed so an element path and value
  84     can be more than 1000 bytes long, the Assuan protocol line limit.
  85
  86
  87 DELETE [!]element[<TAB>[!]element[...]]
  88     Removes an element tree from the specified element path.
  89
  90
  91 GET [!]element[<TAB>[!]element[...]]
  92     Retrieves the content of the specified element path. The data is returned
  93     with a data response.
  94
  95
  96 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
  97     ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
  98         Stores or updates an attribute value to an element path.
  99
 100     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
 101         Removes an attribute from an element path.
 102
 103     ATTR LIST [!]element[<TAB>[!]element[...]]
 104         Gets a list of attributes from an element path.
 105
 106     ATTR GET attribute [!]element[<TAB>[!]element[...]]
 107         Gets the value of an attribute from an element path.
 108
 109     The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
 110     if the element path is only a root element. Although it can be SET to
 111     change the root element name.
 112
 113     Also see THE TARGET ATTRIBUTE below.
 114
 115
 116 XPATH <expression>[<TAB>value]
 117     Evaluates an XPath expression. If no value argument is specified, it is
 118     assumed the expression is a request to return a result. Otherwise, the
 119     result is set to the value argument and the document is updated. If there
 120     is no value after the <TAB> character, the value is assumed to be empty
 121     and the document is updated.
 122
 123
 124 IMPORT [!]element[<TAB>[!]element[...]] <content>
 125     Like the STORE command (an INQUIRE), but the content argument is real XML
 126     data. The content is created as a child of the specified element path. If
 127     an element of the element path doesn't exist, it is created.
 128
 129
 130 DUMP
 131     Shows the in memory XML document with indenting.
 132
 133
 134 GETCONFIG <parameter>
 135     Returns the value of a pwmd configuration variable with a data response.
 136     If no file is open then the default value will be returned. The "key" and
 137     "key_file" variables are ignored.
 138
 139
 140 OPTION NAME=VALUE
 141     Sets an option NAME to VALUE. See OPTIONS below.
 142
 143
 144 BYE
 145     Closes the connection. Use the SAVE command before this command as any
 146     changes will be lost.
 147
 148
 149 If a command fails then the ERR response is returned followed by a protocol
 150 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 151 error codes.
 152
 153
 154 OPTIONS
 155 -------
 156 Commands that require a key that is neither cached or specified will use
 157 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
 158 command followed by the option name and value. Below are the available
 159 pinentry options:
 160
 161     NAME       VALUE      Description
 162     ---------|----------|----------------------------------------------------
 163     PINENTRY  0|1        When 0, disable use of pinentry. The default is 1.
 164     PATH      <string>   Full path to the pinentry binary. The default is
 165                          specified at compile time (/usr/bin/pinentry).
 166     TTYNAME   <string>   Same as the --ttyname option to pinentry(1).
 167     TTYTYPE   <string>   Same as the --ttytype option to pinentry(1).
 168     DISPLAY   <string>   Same as the --display option to pinentry(1).
 169     TITLE     <string>   Sets the title string of the dialog.
 170     PROMPT    <string>   Sets the prompt string of the dialog.
 171     DESC      <string>   Sets the error or description string of the dialog.
 172
 173 When pinentry is used with the SAVE command the key will be asked for
 174 confirmation. If the confirmation fails, the process is started over again
 175 until either the keys match or until Cancel is selected. The OPEN command will
 176 only ask for the key once without retrying on failure. It is up to the client
 177 to retry the OPEN command. Empty keys are allowed.
 178
 179 There is also a CLIENT option that contains other sub-options. The format is
 180 OPTION CLIENT NAME=VALUE, where NAME is one of:
 181
 182     NAME       VALUE      Description
 183     ---------|----------|----------------------------------------------------
 184     NAME      <string>   Associates the thread ID of the connection with the
 185                          specified textual representation. Useful for
 186                          debugging log messages.
 187
 188
 189 STATUS MESSAGES
 190 ---------------
 191 Some commands send a status message to the client when successful or as a
 192 progress indicator. Status messages begin with a KEYWORD (see below) followed
 193 by the status description. What messages are sent, and how often, depend on
 194 configuration settings:
 195
 196     COMMAND             KEYWORD
 197     --------------------------------
 198     OPEN                DECRYPT
 199                         DECOMPRESS
 200                         CACHE
 201                         LOCKED
 202
 203     SAVE                COMPRESS
 204                         ENCRYPT
 205                         CACHE
 206                         LOCKED
 207
 208     CLEARCACHE          CACHE
 209                         LOCKED
 210
 211     CACHETIMEOUT        CACHE
 212                         LOCKED
 213
 214     ISCACHED            LOCKED
 215
 216
 217     KEYWORD             OUTPUT FORMAT
 218     ---------------------------------
 219     CACHE               <slots used> <slots available>
 220     ENCRYPT             <iterations so far>
 221     DECRYPT             <iterations so far>
 222     COMPRESS            <bytes so far> <total bytes>
 223     DECOMPRESS          <bytes so far> <total bytes>
 224     LOCKED              When another thread owns the file/key cache lock,
 225                         this is sent once and the thread blocks until the
 226                         lock can be obtained and the command completes.
 227     KEEPALIVE           Sent the after every configured amount of seconds.
 228                         This lets the client know that the connection is still
 229                         active for commands that take a while to complete.
 230
 231
 232 THE TARGET ATTRIBUTE
 233 --------------------
 234 There is a special attribute "target" (case sensitive) that can be set with
 235 ATTR SET. The value of this attribute is an element path somewhere else in the
 236 XML document:
 237
 238 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 239                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
 240
 241 If the element path of the "target" attribute (arg1) doesn't exist, it is
 242 created. This is the only time the ATTR command will create elements.
 243
 244 When a protocol command requests <arg1> as the element path, the remaining
 245 elements after the element with the "target" attribute will be appended to
 246 <arg2>. This is useful if you have elements that share the same data. If the
 247 target is modified, the other elements "pointing" to the target will have the
 248 same content. To get the real or literal element and ignore any "target"
 249 attributes, prefix an element with a '!' character. Here's an example:
 250
 251     C> STORE
 252     S> INQUIRE STORE
 253     C> D host1<TAB>username<TAB>original username
 254     C> END
 255     S> OK
 256     C> STORE
 257     S> INQUIRE STORE
 258     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 259     C> END
 260     S> OK
 261     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 262     S> OK
 263
 264 Now host1's "target" attribute will be used:
 265
 266     C> GET host1<TAB>username
 267     S> D someuser
 268     S> OK
 269
 270 If you want host1's username, prefix the element of the "target" attribute
 271 with a '!':
 272
 273     C> GET host1<TAB>!username
 274     S> D original username
 275     S> OK
 276
 277 The target value (arg2) element can also have a "target" attribute:
 278
 279     C> ATTR SET target new_account host1
 280     S> OK
 281     C> GET new_account<TAB>username
 282     S> D someuser
 283     S> OK
 284
 285 The value of the "target" attribute may also be prefixed with a '!' to set the
 286 target to the actual element path and not a target of the element path:
 287
 288     C> ATTR DELETE target !new_account
 289     S> OK
 290     C> ATTR SET target new_account<TAB>username host1<TAB>!username
 291     S> OK
 292     C> GET new_account<TAB>username
 293     S> D original username
 294     S> OK
 295
 296 The "target" attribute is considered for all commands that support an element
 297 path. If the target element has been renamed or deleted afterwards, the
 298 command will fail.
 299
 300 Clients should be careful of creating target loops. See the "recursion_depth"
 301 configuration parameter for details.
 302
 303
 304 XML DOCUMENT STRUCTURE
 305 ----------------------
 306 When importing an XML data file with the -I command line option, the document
 307 should have the following DTD:
 308
 309     <?xml version="1.0"?>
 310     <!DOCTYPE accounts [
 311     <!ELEMENT accounts (account*)>
 312     <!ATTLIST account name CDATA #REQUIRED>
 313     ]>
 314
 315 "accounts" is the document root element while each root element mentioned in
 316 the protocol commands use the "account" element. So if you have a root element
 317 "isp" to be shown with the LIST command ("LIST isp"), the document structure
 318 looks like this:
 319
 320     <accounts>
 321         <account name="isp">
 322         [...]
 323         </account>
 324     </accounts>
 325
 326 The DUMP command can be useful to show the current document structure.
 327
 328
 329 DESIGN
 330 ------
 331 The key cache is protected with a mutex and is locked with each access. Each
 332 cache entry also contains a mutex for the opened file and a reference count
 333 which is adjusted each time a client connects or disconnects. This allows
 334 client A to issue commands that aren't related to the file opened by client B.
 335 The refcount is needed to prevent the mutex being overwritten when the entry
 336 needs to be reset (CACHETIMEOUT for example) and there are any client
 337 connected.
 338
 339 The client_thread() uses an event to wait for the client FD to become ready
 340 for reading. When ready, it uses the libassuan assuan_process_next() function
 341 to prevent blocking. This allows for the keepalive_thread() and any signals
 342 send to client_thread() to continue to work and lets the Pth scheduler let
 343 other (client) threads do their work too.
 344
 345 The cleanup_thread() is a loop that sleeps at some interval and is responsible
 346 for freeing the resources of the client after the associated client_thread()
 347 terminates or exits. How it determines if the client exited is done with the
 348 PTH_UNTIL_TID_DEAD event; it checks a list of recorded connections for that
 349 event.
 350
 351 When a key is required for the OPEN or SAVE commands, and OPTION PINENTRY=1,
 352 pinentry(1) is used to retrieve the key. This is done by creating a pipe()
 353 with the client_thread(), then pth_fork()'s the pinentry process which will
 354 write the key or error to the pipe that client_thread() will read from. After
 355 the read, the pinentry should have exited and client_thread() calls the
 356 finalization function for the command that used pinentry.
 357
 358
 359            -------------       ---------------
 360  ----------[server_loop]-_-_-_-[accept_thread]
 361  |         -------------       ---------------
 362  |     not joinable :                |
 363  |  ---------------------     ---------------
 364  |  [adjust_timer_thread]     [client_thread]<------------=====
 365  |  ---------------------     ---------------   |   |    |    =
 366  |                              :   | |    |    |   |    |    =
 367  |---|                          :   | |    |    |   |    |    =
 368      |                          :   | |    |    |   |    |    =
 369  ----------------               :   | |    |    |   |    |    =
 370  [cleanup_thread]       :::::::::   | |    |    |   |    |    =
 371  ----------------       :           | |  ---------  |    |    =
 372        | pth_cancel()   :           | |  [command]  |    |    =
 373        |        ------------------  | |  ---------  |    |    = pipe()
 374        |--------[keepalive_thread]  | |    |   |    |    |    =
 375                 ------------------  | |    |  ---------  |    =
 376                                     | |    |  [inquire]  |    =
 377                                     | |    |  ---------  |    =
 378                                     | |    |    -----------   =
 379                                     | |    |----[OPEN/SAVE]   =
 380                                     | |         -----------   =
 381                           --------------------       : fork() =
 382                           [ command finalize ]   ----------   =
 383                           --------------------   [pinentry]====
 384                                                  ----------
 385
 386
 387 Questions, bugs or feature requests can be sent to
 388 Ben Kibbey <bjk@luxsci.net>.