doc/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 the filename is not found on the
  13     file-system, then a new document will be created. If the file is found, it
  14     is looked for in the file cache for an existing key. When found and no key
  15     was specified, the cached key will be used for decryption (if encrypted).
  16     When not found, pinentry(1) will be used to retrieve the key (see OPTIONS
  17     below). You can also open a different file using the same connection. When
  18     using an empty or NULL key and you want to avoid the pinentry dialog, set
  19     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> will be used. If <key> is not
  27     specified then pinentry(1) will be used to retrieve the key (see OPTIONS
  28     below). If you want to use and empty key and want to avoid the pinentry
  29     dialog, set PINENTRY to 0 (see OPTIONS below).
  30
  31
  32 ISCACHED <filename>
  33     An OK response is returned if the specified file is found in the file
  34     cache or ERR if not.
  35
  36
  37 CLEARCACHE [<filename>]
  38     Clears a file cache entry. This will forget the timeout and key for all or
  39     the specified file. Always returns an OK response.
  40
  41
  42 CACHETIMEOUT <seconds> <filename>
  43     Specify the number of seconds the specified file will be cached. -1 will
  44     keep the cache entry forever, 0 will require the key each time the OPEN or
  45     SAVE commands are used. Also see the "cache_timeout" configuration
  46     parameter. Returns ERR if the filename isn't cached or if the timeout is
  47     invalid. OK otherwise.
  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. 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
  58 REALPATH [!]element[<TAB>[!]element[...]]
  59     Resolves all "target" attributes of the specified element path and returns
  60     the result with a data response.
  61
  62
  63 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
  64     Creates a new element tree or modifies the content of an existing element
  65     path. If only a single element is specified, a new root element is
  66     created. Otherwise, elements are TAB delimited and the content will be set
  67     to the last TAB delimited argument. If no content is specified after the
  68     last TAB then the content for the last specified element will be removed
  69     or empty if creating a new element.
  70
  71     The only restriction of element names is that they not begin with a
  72     punctuation character (the literal '!' character is an exception) or digit
  73     and not contain any whitespace. There is no whitespace between the TAB
  74     delimited elements. It is recommended that the value be base 64 encoded to
  75     prevent XML and pwmd parsing errors.
  76
  77     PWMD reads the element path from the client via the Assuan INQUIRE
  78     protocol response. The STORE command is sent by itself without arguments,
  79     then the server responds with INQUIRE. The client then sends the element
  80     path prefixed with a "D " data response. The element path may extend
  81     multiple lines but each must be prefixed with the data "D " response. When
  82     finished, the client sends "END" on an empty line. This is needed so an
  83     element path and value can be more than 1000 bytes long, the Assuan
  84     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 or text node of the specified element path. The data
  93     is returned 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 of 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 the root element. Although it can be SET to change
 111     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 raw XML
 126     data. The content is created as a child of the specified element path. If
 127     an element of the element path does not exist, it is created.
 128
 129     Note that the new content must begin with an element node. Also note that
 130     an existing child node of the same element name as the root node of the
 131     imported content will be overwritten.
 132
 133
 134 DUMP
 135     Shows the in memory XML document with indenting. To dump a specific
 136     element tree, use the XPATH command.
 137
 138
 139 LOCK
 140     Locks the mutex associated with the opened file. This prevents other
 141     clients from sending commands to the same opened file until the client
 142     that sent this command either disconnects or sends the UNLOCK command.
 143
 144
 145 UNLOCK
 146     Unlocks the mutex which was locked with the LOCK command.
 147
 148
 149 GETPID
 150     Retrieves the process id of the server.
 151
 152
 153 GETCONFIG [filename] <parameter>
 154     Returns the value of a pwmd configuration variable with a data response.
 155     If no file is open then the specified files value or the default ("global"
 156     section) will be returned. If there is no such parameter defined,
 157     GPG_ERR_NO_VALUE is returned.
 158
 159
 160 VERSION
 161     Returns the server version number with a data response.
 162
 163
 164 OPTION <NAME>=<VALUE>
 165     Sets an option NAME to VALUE. See OPTIONS below for available options.
 166
 167
 168 BYE
 169     Closes the connection disconnecting the client. Unless the SAVE command
 170     had been sent, any changes to the document will be lost.
 171
 172
 173 OPTIONS
 174 -------
 175 Commands that require a key that is neither cached nor specified will use
 176 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
 177 command followed by the option name and value. Below are the available
 178 pwmd options:
 179
 180     NAME       VALUE      Description
 181     ---------|----------|----------------------------------------------------
 182     PINENTRY   0|1        When 0, disable use of pinentry. The default is 1.
 183     TIMEOUT    <integer>  The number of seconds before the pinentry process
 184                           will terminate while waiting for a passphrase. The
 185                           default is 20, 0 disables.
 186     PATH       <string>   Full path to the pinentry binary. The default is
 187                           specified at compile time.
 188     TTYNAME    <string>   Same as the --ttyname option to pinentry(1).
 189     TTYTYPE    <string>   Same as the --ttytype option to pinentry(1).
 190     DISPLAY    <string>   Same as the --display option to pinentry(1).
 191     TITLE      <string>   Sets the title string of the pinentry dialog.
 192     PROMPT     <string>   Sets the prompt string of the pinentry dialog.
 193     DESC       <string>   Sets the error or description string of the pinenry
 194     LC_CTYPE   <string>   Same as the --lc-ctype option to pinentry(1).
 195     LC_MESSAGES <string>  Same as the --lc-messages option to pinentry(1).
 196     ITERATIONS <integer>  The number of encryption iterations to do when the
 197                           SAVE command is sent. When set, the configured
 198                           value will be updated to this value for the opened
 199                           file, or the "global" default if no file has been
 200                           opened yet. When setting this option before opening
 201                           a file, this option is reset to the data files
 202                           setting after opening. The CONFIG status message is
 203                           sent after receiving this command.
 204     CLIENT     <string>   See below.
 205
 206 To reset an option value string to its default, set the value to NULL.
 207
 208 When pinentry is used with the SAVE command the passphrase will be asked for
 209 confirmation. If the confirmation fails, the process is started over again
 210 until either the passphrases match or until Cancel is selected. The OPEN
 211 command will only ask for the passphrase once without retrying on failure. It
 212 is up to the client to retry the OPEN command. Empty keys are allowed. To
 213 prevent pinentry asking for an (empty) passphrase, set OPTION PINENTRY=0.
 214
 215 There is also a CLIENT option that contains other sub-options. The format is
 216 OPTION CLIENT NAME=VALUE, where the option NAME is one of:
 217
 218     NAME       VALUE      Description
 219     ---------|----------|----------------------------------------------------
 220     NAME      <string>   Associates the thread ID of the connection with the
 221                          specified textual representation. Useful for
 222                          debugging log messages.
 223
 224
 225 STATUS MESSAGES
 226 ---------------
 227 Some commands send a status message to the client when successful or as a
 228 progress indicator. Status messages begin with a KEYWORD (see below) followed
 229 by the status description. What messages are sent, when, and how often, depend
 230 on configuration settings:
 231
 232     COMMAND             KEYWORD
 233     --------------------------------
 234     <ALL>               LOCKED
 235
 236     OPEN                DECRYPT
 237                         DECOMPRESS
 238                         CACHE
 239
 240     SAVE                COMPRESS
 241                         ENCRYPT
 242                         CACHE
 243
 244     GET                 XFER
 245
 246     LIST                XFER
 247
 248     DUMP                XFER
 249
 250     XPATH               XFER
 251
 252     CLEARCACHE          CACHE
 253
 254     CACHETIMEOUT        CACHE
 255
 256
 257     KEYWORD             OUTPUT FORMAT
 258     ---------------------------------
 259     CACHE               <slots used>
 260                         Sent to each client after the file cache changes.
 261     ENCRYPT             <iterations so far> <total iterations>
 262     DECRYPT             <iterations so far> <total iterations>
 263     COMPRESS            <bytes so far> <total bytes>
 264     DECOMPRESS          <bytes so far> <total bytes>
 265     LOCKED              When another thread owns the file/key cache mutex
 266                         lock, this is sent at some interval and the thread
 267                         will block until the lock can be obtained.
 268     KEEPALIVE           Sent to each client after every configured amount of
 269                         seconds. This lets the client know that the connection
 270                         is still active for commands that take awhile to
 271                         complete.
 272     CONFIG              Sent to each client after the configuration file has
 273                         been reloaded or has had a value changed.
 274     CLIENTS             Sent to each client after a client connects or
 275                         disconnects.
 276     XFER                <bytes so far> <total bytes>
 277
 278
 279 THE TARGET ATTRIBUTE
 280 --------------------
 281 There is a special attribute "target" (case sensitive) that can be set with
 282 ATTR SET. The value of this attribute is an element path that is located
 283 somewhere else in the XML document and are alot like how XPath treats
 284 entities, but is needed do to how pwmd commands are implemented. The syntax
 285 is as follows:
 286
 287 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 288                 arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^
 289
 290 If the element path of the "target" attribute (arg1) doesn't exist, it is
 291 created. This is the only time the ATTR command will create elements.
 292
 293 When a protocol command requests <arg1> as the element path, the remaining
 294 elements after the element with the "target" attribute will be appended to
 295 <arg2>. This is useful if you have elements that share the same data. If the
 296 target is modified, the other elements "pointing" to the target will have the
 297 same content. To get the real or literal element and ignore any "target"
 298 attributes, prefix the element with a '!' character. Here's an example:
 299
 300     C> STORE
 301     S> INQUIRE STORE
 302     C> D host1<TAB>username<TAB>original username
 303     C> END
 304     S> OK
 305     C> STORE
 306     S> INQUIRE STORE
 307     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 308     C> END
 309     S> OK
 310     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 311     S> OK
 312
 313 Now host1's "target" attribute will be used:
 314
 315     C> GET host1<TAB>username
 316     S> D someuser
 317     S> OK
 318
 319 If you want host1's username, prefix the element of the "target" attribute
 320 with a '!':
 321
 322     C> GET host1<TAB>!username
 323     S> D original username
 324     S> OK
 325
 326 The target value (arg2) element can also have a "target" attribute:
 327
 328     C> ATTR SET target new_account host1
 329     S> OK
 330     C> GET new_account<TAB>username
 331     S> D someuser
 332     S> OK
 333
 334 The value of the "target" attribute may also be prefixed with a '!' to set the
 335 target to the actual element path and not a target of the element path:
 336
 337     C> ATTR DELETE target !new_account
 338     S> OK
 339     C> ATTR SET target new_account<TAB>username host1<TAB>!username
 340     S> OK
 341     C> GET new_account<TAB>username
 342     S> D original username
 343     S> OK
 344
 345 The "target" attribute is considered for all commands that support an element
 346 path. If the target element has been renamed or deleted afterwards, the
 347 command will fail.
 348
 349 Clients should be careful of creating target loops. See the "recursion_depth"
 350 configuration parameter for details.
 351
 352
 353 XML DOCUMENT STRUCTURE
 354 ----------------------
 355 When importing an XML data file with the -I command line option, the document
 356 should have the following DTD:
 357
 358     <?xml version="1.0"?>
 359     <!DOCTYPE pwmd [
 360     <!ELEMENT pwmd (root*)>
 361     <!ATTLIST root name CDATA #REQUIRED>
 362     ]>
 363
 364 The "pwmd" element is the document root node while the first element of an
 365 element path specified in protocol commands use the "root" element. So if you
 366 specify the command "LIST isp", "isp" is really a "root" element that has a
 367 "name" attribute with the value "isp". Any following elements are children of
 368 the "root" element:
 369
 370     <pwmd>
 371         <root name="isp">
 372         [...]
 373         </root>
 374     </pwmd>
 375
 376 The remaining <TAB> delimited elements (e.g., "LIST isp<TAB>SMTP") are regular
 377 elements and are not treated specially in the XML document.
 378
 379 The DUMP command might be useful to show the document structure.
 380
 381
 382 DESIGN
 383 ------
 384 The key cache is protected with a mutex and is locked with each access. Each
 385 cache entry also contains a mutex for the opened file and a reference count
 386 which is adjusted each time a client connects or disconnects. This allows
 387 client A to issue commands that aren't related to the file opened by client B.
 388 The refcount is needed to prevent the mutex being overwritten when the entry
 389 needs to be reset (CACHETIMEOUT for example) and there are any clients
 390 connected.
 391
 392 The client_thread() uses an event to wait for the client FD to become ready
 393 for reading. When ready, it uses the libassuan external IO loop functions to
 394 prevent blocking letting other threads do their work.
 395
 396 When a key is required for the OPEN or SAVE commands, and OPTION PINENTRY=1,
 397 pinentry(1) is used to retrieve the key. This is done by creating a pipe()
 398 with the client_thread(), then pth_fork()'s the pinentry process which will
 399 write the key or error to the pipe that client_thread() will read from. After
 400 the read, the pinentry will have exited and client_thread() calls the
 401 finalization function for the original command.
 402
 403            -------------       ---------------
 404            [server_loop]-_-_-_-[accept_thread]
 405            -------------       ---------------
 406        not joinable :                |
 407     ---------------------     ---------------
 408     [adjust_timer_thread]  |--[client_thread]<----------=====
 409     ---------------------  |  --------------- |   |    |    =
 410             ---------------|   | |     ---------  |    |    =
 411             |      ------------------  [command]  |    |    =
 412             |      [command finalize]  ---------  |    |    = pipe()
 413             |      ------------------    |   |    |    |    =
 414   -------------------                    |  ---------  |    =
 415   |client_msg_thread|                    |  [INQUIRE]  |    =
 416   -------------------                    |  ---------  |    =
 417                                          |    -----------   =
 418                                          |----[OPEN/SAVE]   =
 419                                               -----------   =
 420                                                    : fork() =
 421                                                ----------   =
 422                                                [pinentry]====
 423                                                ----------
 424
 425 There is also a library libpwmd which makes it easy for applications to use
 426 the server. It supports it's own key retrieval (for clients that need it) and
 427 asynchronous interaction with pwmd. It also includes a command line client for
 428 sending commands to pwmd.
 429
 430 The latest version of both pwmd and libpwmd can be obtained from
 431 http://bjk.sourceforge.net/pwmd/. Feel free to send me any questions, bug
 432 reports, patches or feature requests.
 433
 434 Ben Kibbey <bjk@luxsci.net>