doc/COMMANDS

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