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