COMMANDS

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