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