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