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     ENABLE_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 ENABLE_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. If not found in the cache but exists on the filesystem,
  35     GPG_ERR_NOT_FOUND is returned. Otherwise a filesystem error is returned.
  36
  37
  38 CLEARCACHE [<filename>]
  39     Clears a file cache entry. This will forget the timeout and key for all or
  40     the specified file. Always returns an OK response.
  41
  42
  43 CACHETIMEOUT <filename> <seconds>
  44     Specify the number of seconds the specified file will be cached. -1 will
  45     keep the cache entry forever, 0 will require the key each time the OPEN or
  46     SAVE commands are used. Also see the "cache_timeout" configuration
  47     parameter. Returns ERR if the filename isn't cached or if the timeout is
  48     invalid. OK otherwise.
  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. 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 XML 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. The element path may extend
  82     multiple lines but each must be prefixed with the data "D " response. When
  83     finished, the client sends "END" on an empty line. This is needed so an
  84     element path and value can be more than 1000 bytes long, the Assuan
  85     protocol line limit.
  86
  87
  88 RENAME [!]element[<TAB>[!]element[...]] <value>
  89     Renames the specified element to the new value. If an element of the same
  90     name as the value exists then it will be overwritten.
  91
  92
  93 COPY [!]element[<TAB>[!]element[...]] [!]element[<TAB>[!]element[...]]
  94     Copies the entire element tree starting from the child node of the source
  95     element path, to the destination element path. If the destination element
  96     path doesn't exist then it is created; otherwise it is overwritten.
  97
  98     Note that attributes from the source element path are merged into the
  99     destination element path.
 100
 101
 102 DELETE [!]element[<TAB>[!]element[...]]
 103     Removes an element tree from the specified element path.
 104
 105
 106 GET [!]element[<TAB>[!]element[...]]
 107     Retrieves the content or text node of the specified element path. The data
 108     is returned with a data response.
 109
 110
 111 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
 112     ATTR SET attribute [!]element[<TAB>[!]element[...]] [attribute_value]
 113         Stores or updates an attribute name and optional value of an element
 114         path.
 115
 116     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
 117         Removes an attribute from an element path.
 118
 119     ATTR LIST [!]element[<TAB>[!]element[...]]
 120         Gets a list of attributes from an element path.
 121
 122     ATTR GET attribute [!]element[<TAB>[!]element[...]]
 123         Gets the value of an attribute from an element path.
 124
 125     The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
 126     if the element path is the root element. Although it can be SET to change
 127     the root element name but only if the destination element doesn't exist.
 128     Use the RENAME command for that instead.
 129
 130     Also see THE TARGET ATTRIBUTE below.
 131
 132
 133 XPATH <expression>[<TAB>[value]]
 134     Evaluates an XPath expression. If no value argument is specified, it is
 135     assumed the expression is a request to return a result. Otherwise, the
 136     result is set to the value argument and the document is updated. If there
 137     is no value after the <TAB> character, the value is assumed to be empty
 138     and the document is updated.
 139
 140
 141 XPATHATTR SET|DELETE <name> <expression>[<TAB>[<value>]]
 142     Like the XPATH command but operates on element attributes and won't return
 143     a result. For the SET operation the <value> is optional but the field is
 144     required in which case the value will be empty.
 145
 146
 147 IMPORT <content>[<TAB>[!]element[<TAB>[!]element[...]]]
 148     Like the STORE command (an INQUIRE), but the content argument is raw XML
 149     data. The content is created as a child of the specified element path. If
 150     an element of the element path does not exist then it is created. If no
 151     element path is specified then the content must begin with an pwmd DTD
 152     root element.
 153
 154     Note that the new content must begin with an element node. Also note that
 155     an existing child node of the same element name as the root node of the
 156     imported content will be overwritten.
 157
 158
 159 DUMP
 160     Shows the in memory XML document with indenting. To dump a specific
 161     element tree, use the XPATH command.
 162
 163
 164 LOCK
 165     Locks the mutex associated with the opened file. This prevents other
 166     clients from sending commands to the same opened file until the client
 167     that sent this command either disconnects or sends the UNLOCK command.
 168
 169
 170 UNLOCK
 171     Unlocks the mutex which was locked with the LOCK command.
 172
 173
 174 GETPID
 175     Retrieves the process id of the server.
 176
 177
 178 GETCONFIG [filename] <parameter>
 179     Returns the value of a pwmd configuration variable with a data response.
 180     If no file has been opened then the value for the specified file or the
 181     default from the "global" section will be returned. If a file has been
 182     opened and no filename is specified, the value previously set with the SET
 183     command, if any, will be returned.
 184
 185     If there is no such parameter defined, GPG_ERR_NO_VALUE is returned.
 186
 187
 188 VERSION
 189     Returns the server version number with a data response.
 190
 191
 192 SET <NAME>=<VALUE>
 193     Sets an option NAME to VALUE. See OPTIONS below for available options.
 194
 195
 196 UNSET <NAME>
 197     Resets option NAME to the value specified in the server configuration
 198     file. Some options have no default and will be reset to NULL or 0
 199     depending on the type.
 200
 201
 202 LS
 203     Lists the contents of the configured data_directory. The result is a
 204     newline separated list of filenames.
 205
 206
 207 BYE
 208     Closes the connection disconnecting the client. Unless the SAVE command
 209     had been sent, any changes to the document will be lost.
 210
 211
 212 OPTIONS
 213 -------
 214 Commands that require a key that is neither cached nor specified will use
 215 pinentry(1) to retrieve the key. Pinentry options can be set with the SET
 216 command followed by the option name and value. Below are the available pwmd
 217 options:
 218
 219     NAME             |VALUE     |Description
 220     -----------------|----------|----------------------------------------------
 221     ENABLE_PINENTRY   0|1        When 0, disable use of pinentry. The default
 222                                  is 1.
 223     PINENTRY_TIMEOUT  <integer>  The number of seconds before the pinentry
 224                                  process will terminate while waiting for a
 225                                  passphrase. The default is 20, 0 disables.
 226     PINENTRTY_PATH    <string>   Full path to the pinentry binary. The default
 227                                  is specified at compile time.
 228     TTYNAME           <string>   Same as the --ttyname option to pinentry(1).
 229     TTYTYPE           <string>   Same as the --ttytype option to pinentry(1).
 230     DISPLAY           <string>   Same as the --display option to pinentry(1).
 231     TITLE             <string>   Sets the title string of the pinentry dialog.
 232     PROMPT            <string>   Sets the prompt string of the pinentry dialog.
 233     DESC              <string>   Sets the error or description string of the
 234                                  pinentry dialog.
 235     LC_CTYPE          <string>   Same as the --lc-ctype option to pinentry(1).
 236     LC_MESSAGES       <string>   Same as the --lc-messages option to
 237                                  pinentry(1).
 238     ITERATIONS        <integer>  The number of encryption iterations to do
 239                                  when the SAVE command is sent. An opened file
 240                                  is needed when setting this option. The
 241                                  CONFIG status message is sent after receiving
 242                                  this command.
 243     NAME              <string>   Associates the thread ID of the connection
 244                                  with the specified textual representation.
 245                                  Useful for debugging log messages.
 246     CIPHER            <string>   The cipher to use for the next SAVE.
 247     LOCK_ON_OPEN      0|1        If enabled then the file mutex will be locked
 248                                  after a successful OPEN as if the LOCK
 249                                  command had been sent.
 250
 251 When pinentry is used with the SAVE command the passphrase will be asked for
 252 confirmation. If the confirmation fails, the process is started over again
 253 until either the passphrases match or until Cancel is selected. The OPEN
 254 command will only ask for the passphrase once without retrying on failure. It
 255 is up to the client to retry the OPEN command. Empty keys are allowed. To
 256 prevent pinentry asking for an (empty) passphrase, use SET ENABLE_PINENTRY=0.
 257
 258 To reset an option value string to its default, use the UNSET command.
 259
 260
 261 STATUS MESSAGES
 262 ---------------
 263 Some commands send a status message to the client when successful or as a
 264 progress indicator. Status messages begin with a KEYWORD (see below) followed
 265 by the status description. What messages are sent, when, and how often, depend
 266 on configuration settings:
 267
 268     COMMAND      | KEYWORD
 269     -------------|-------------
 270     <ALL>         LOCKED
 271
 272     OPEN          DECRYPT
 273                   DECOMPRESS
 274                   CACHE
 275
 276     SAVE          COMPRESS
 277                   ENCRYPT
 278                   CACHE
 279
 280     GET           XFER
 281
 282     LIST          XFER
 283
 284     DUMP          XFER
 285
 286     XPATH         XFER
 287
 288     CLEARCACHE    CACHE
 289
 290     CACHETIMEOUT  CACHE
 291
 292
 293     KEYWORD    |OUTPUT FORMAT
 294     -----------|--------------------
 295     CACHE       <slots used>
 296                 Sent to each client after the file cache changes.
 297     ENCRYPT     <iterations so far> <total iterations>
 298     DECRYPT     <iterations so far> <total iterations>
 299     COMPRESS    <bytes so far> <total bytes>
 300     DECOMPRESS  <bytes so far> <total bytes>
 301     XFER        <bytes so far> <total bytes>
 302     LOCKED      When another thread owns a mutex lock that the current thread
 303                 needs, this is status message is sent and the thread will
 304                 block until the lock can be obtained.
 305     KEEPALIVE   Sent to each client after every configured amount of
 306                 seconds. It is important that this status message be sent to
 307                 test for client connectivity.
 308     CONFIG      Sent to each client after the configuration file has
 309                 been reloaded or has had a value changed that may affect other
 310                 connected clients.
 311     CLIENTS     Sent to each client after a client connects or disconnects.
 312
 313
 314 THE TARGET ATTRIBUTE
 315 --------------------
 316 There is a special attribute "target" (case sensitive) that can be set with
 317 ATTR SET. The value of this attribute is an element path that is located
 318 somewhere else in the XML document and are alot like how XPath treats
 319 entities, but is needed do to how pwmd commands are implemented. The syntax
 320 is as follows:
 321
 322 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 323                 arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^
 324
 325 If the element path of where the "target" attribute (arg1) is to be stored
 326 doesn't exist then it will be created. This is the only time the ATTR command
 327 will create elements.
 328
 329 When a protocol command requests <arg1> as the element path then the path will
 330 be modified to use <arg2>. This is useful if you need elements to share the
 331 same data. If the target is modified, the other elements "pointing" to the
 332 target will have the same content. To get the real or literal element and
 333 ignore any "target" attributes, prefix the element with a '!' character.
 334 Another way to think of this attribute is that it's like a symbolic link in a
 335 filesystem. Here's an example XML document:
 336
 337     <pwmd>
 338         <root name="a">
 339             <element>value a</element>
 340         </root>
 341         <root name="b" target="a">
 342             <element_b>value b/element_b>
 343         </root>
 344         <root name="c" target="b"/>
 345         <root name="d" target="!b"/>
 346     </pwmd>
 347
 348 Example:
 349     C> LIST b
 350     S> b
 351     S> b !element
 352
 353 Notice that there is not an <element_b> listed. This is because of the
 354 "target" attribute. The target attribute is recursive too, meaning that it can
 355 point to other elements with a "target" attibute:
 356
 357     C> LIST c
 358     S> c
 359     S> c !element
 360
 361 To get the value of an element with a "target" attribute without resolving the
 362 target, prefix the element with the literal element character '!':
 363
 364     C> LIST !b
 365     S> !b
 366     S> !b !element_b
 367
 368 A "target" attribute value may also contain the literal element character:
 369
 370     C> LIST d
 371     S> d
 372     S> d !element_b
 373
 374 The value of the "target" attribute isn't limited to only one element. It can
 375 be a full element path with literal element characters placed where needed.
 376 Use the REALPATH command to resolve all "target" attributes.
 377
 378 The "target" attribute is considered for all commands that support an element
 379 path. If the target element has been renamed or deleted afterwards, the
 380 command will fail.
 381
 382 Clients should be careful of creating target loops or targets which resolve to
 383 themselves. See the "recursion_depth" configuration parameter for details.
 384
 385
 386 XML DOCUMENT STRUCTURE
 387 ----------------------
 388 When importing an XML data file with the -I command line option, the document
 389 should have the following DTD:
 390
 391     <?xml version="1.0"?>
 392     <!DOCTYPE pwmd [
 393     <!ELEMENT pwmd (root*)>
 394     <!ATTLIST root name CDATA #REQUIRED>
 395     ]>
 396
 397 The "pwmd" element is the document root node while the first element of an
 398 element path specified in protocol commands use the "root" element. So if you
 399 specify the command "LIST isp", "isp" is really a "root" element that has a
 400 "name" attribute with the value "isp". This is needed do to how the LIST
 401 command works. Any following elements are children of the "root" element:
 402
 403     <pwmd>
 404         <root name="isp">
 405             <username>bjk</username>
 406             [...]
 407         </root>
 408         <root name="email">
 409             <username>someusername</username>
 410             [...]
 411         </root>
 412     </pwmd>
 413
 414 The remaining <TAB> delimited elements (e.g., "LIST isp<TAB>SMTP") are regular
 415 elements and are not treated specially in the XML document.
 416
 417 The DUMP command might be useful to show the document structure.
 418
 419 Ben Kibbey <bjk@luxsci.net>
 420 http://bjk.sourceforge.net/pwmd/