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