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