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