COMMANDS

   1 The server uses a protocol provided by libassuan to communicate with a client.
   2 An OK response is returned when a command succeeds or ERR along with an error
   3 code and description, if not. When a command requests data for retrieval
   4 (e.g., GET) the output is prefixed with D then a single SPACE then the actual
   5 data followed by an OK response. Read the libassuan docs for more info about
   6 the protocol.
   7
   8            -------------       ---------------
   9  ----------[server_loop]-_-_-_-[socket_thread]
  10  |         -------------       ---------------
  11  |     not joinable |                | accept()
  12  |  ---------------------     ---------------
  13  |  [adjust_cache_thread]     [client_thread]<------------|<===
  14  |  ---------------------     ---------------   |         |   =
  15  |                              |   | |    |    |         |   =
  16  |---|                          |   | |    |    |         |   =
  17      |                          |   | |    |    |         |   =
  18  ----------------               |   | |    |    |         |   =
  19  [cleanup_thread]       ---------   | |    |    |         |   =
  20  ----------------       |           | |   ---------       |   =
  21        x                |           | |   [command]       |   =
  22        x        ------------------  | |   ---------       |   = pipe()
  23        xxxxxxxx>[keepalive_thread]  | |       |           |   =
  24                 ------------------  | |   ---------       |   =
  25                                     | |   [inquire]--------   =
  26                                     | |   ---------           =
  27                                     | |         *             =
  28                             ------------------  * fork() ----------
  29                             [inquire finalize]  *********[pinentry]
  30                             ------------------           ----------
  31
  32
  33 PROTOCOL COMMANDS
  34 -----------------
  35
  36 OPEN <filename> [<key>]
  37     Opens <filename> using <key>. If file is not found on the file-system, then
  38     a new document will be created. If the file is found, it is looked for in
  39     the file cache for an existing key. When found, the existing key will be
  40     used for decryption. When not found, pinentry(1) will be used to retrieve
  41     the key (see OPTIONS below). You can also open another file using the
  42     same connection.
  43
  44
  45 SAVE [<key>]
  46     Writes the XML document to disk. The file written to is the file that was
  47     opened using the OPEN command. If <key> is not specified then the
  48     currently cached key will be used. If the file is a new file or the file
  49     isn't found in the file cache, <key> may be used. If <key> is not
  50     specified then pinentry(1) will be used to retrieve the key (see OPTIONS
  51     below).
  52
  53     When the SAVE command is sent and a key is found in the file cache, the
  54     cached key will be used. To reset the key to a new value, send the
  55     CLEARCACHE command followed by the filename, then send the SAVE command to
  56     enter a new key.
  57
  58
  59 ISCACHED <filename>
  60     An OK response is returned if the specified file is in the file cache.
  61
  62
  63 CLEARCACHE [<filename>]
  64     Clears a file cache entry. This will forget the timeout and key for all or
  65     the specified file.
  66
  67
  68 CACHETIMEOUT <seconds> <filename>
  69     Specify the number of seconds the specified file will be cached. -1 will
  70     keep the cache entry forever, 0 will require the key each time the OPEN or
  71     SAVE commands are used. Also see the "cache_timeout" configuration option.
  72
  73
  74 LIST [[!]element[<TAB>[!]element[...]]]
  75     If no element path is given then a list of root elements is returned with
  76     the data response code. If given, then all reachable elements for the
  77     specified element path are returned. Each element in the path is prefixed
  78     with the literal '!' character when the element contains no "target"
  79     attribute (See THE TARGET ATTRIBUTE below).
  80
  81     If only a single element is specified and without the literal '!' prefix,
  82     both the literal element tree and the element target (if any) tree will be
  83     shown.
  84
  85
  86 REALPATH [!]element[<TAB>[!]element[...]]
  87     Resolves all "target" attributes of the specified element path and returns
  88     the result with a data response.
  89
  90
  91 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
  92     Creates a new element tree or modifies the content of an existing element
  93     path. If only a single element is specified, a new root element is
  94     created. Otherwise, elements are TAB delimited and the content will be set
  95     to the last TAB delimited argument. If no content is specified after the
  96     last TAB then the content for the last specified element will be removed
  97     or the content will be empty when creating a new element.
  98
  99     The only restriction of element names is that they not begin with a
 100     punctuation character (the literal '!' character is an exception) or digit
 101     and not contain any whitespace. There is no whitespace between the TAB
 102     delimited elements. It is recommended that the value be base 64 encoded to
 103     prevent libXML and pwmd parsing errors.
 104
 105     PWMD reads the element path from the client via the Assuan INQUIRE
 106     protocol response. The STORE command is sent by itself without arguments,
 107     then the server responds with INQUIRE. The client then sends the element
 108     path prefixed by a "D " data response. When finished, the client
 109     sends "END" on an empty line. This is needed so an element path and value
 110     can be more than 1000 bytes long, the Assuan protocol line limit.
 111
 112
 113 DELETE [!]element[<TAB>[!]element[...]]
 114     Removes an element tree from the specified element path.
 115
 116
 117 GET [!]element[<TAB>[!]element[...]]
 118     Retrieves the content of the specified element path. The data is returned
 119     with a data response.
 120
 121
 122 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
 123     ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
 124         Stores or updates an attribute value to an element path.
 125
 126     ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
 127         Removes an attribute from an element path.
 128
 129     ATTR LIST [!]element[<TAB>[!]element[...]]
 130         Gets a list of attributes from an element path.
 131
 132     ATTR GET attribute [!]element[<TAB>[!]element[...]]
 133         Gets the value of an attribute from an element path.
 134
 135     The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
 136     if the element path is only a root element. Although it can be SET to
 137     change the root element name.
 138
 139     Also see THE TARGET ATTRIBUTE below.
 140
 141
 142 DUMP
 143     Shows the in memory XML document with indenting.
 144
 145
 146 GETCONFIG <parameter>
 147     Returns the value of a pwmd configuration variable with a data response.
 148     If no file is open then the default value will be returned. The "key" and
 149     "key_file" variables are ignored.
 150
 151
 152 OPTION NAME=VALUE
 153     Sets an option NAME to VALUE. See OPTIONS below.
 154
 155
 156 BYE
 157     Closes the connection. Use the SAVE command before this command as any
 158     changes will be lost.
 159
 160
 161 If a command fails then the ERR response is returned followed by a protocol
 162 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
 163 error codes.
 164
 165
 166 OPTIONS
 167 -------
 168 Commands that require a key that is neither cached or specified will use
 169 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
 170 command followed by the option name and value. Below are the available
 171 pinentry options:
 172
 173     NAME       VALUE      Description
 174     ---------|----------|----------------------------------------------------
 175     PINENTRY  0|1        When 0, disable use of pinentry. The default is 1.
 176     PATH      <string>   Full path to the pinentry binary. The default is
 177                          specified at compile time (/usr/bin/pinentry).
 178     TTYNAME   <string>   Same as the --ttyname option to pinentry(1).
 179     TTYTYPE   <string>   Same as the --ttytype option to pinentry(1).
 180     DISPLAY   <string>   Same as the --display option to pinentry(1).
 181     TITLE     <string>   Sets the title string of the dialog.
 182     PROMPT    <string>   Sets the prompt string of the dialog.
 183     DESC      <string>   Sets the error or description string of the dialog.
 184     TIMEOUT   <N>        Terminates pinentry(1) after the elapsed number of
 185                          seconds.
 186
 187 When pinentry is used with the SAVE command the key will be asked for
 188 confirmation. If the confirmation fails, the process is started over again
 189 until either the keys match or until Cancel is selected. The OPEN command will
 190 only ask for the key once without retrying on failure. It is up to the client
 191 to retry the OPEN command. Empty keys are allowed.
 192
 193 There is also a CLIENT option that contains other sub-options. The format is
 194 OPTION CLIENT NAME=VALUE, where NAME is one of:
 195
 196     NAME       VALUE      Description
 197     ---------|----------|----------------------------------------------------
 198     NAME      <string>   Associates the thread ID of the connection with the
 199                          specified textual representation. Useful for
 200                          debugging log messages.
 201
 202
 203 STATUS MESSAGES
 204 ---------------
 205 Some commands send a status message to the client when successful or as a
 206 progress indicator. Status messages begin with a KEYWORD (see below) followed
 207 by the status description. What messages are sent, and how often, depend on
 208 configuration settings:
 209
 210     COMMAND             KEYWORD
 211     --------------------------------
 212     OPEN                DECRYPT
 213                         DECOMPRESS
 214                         CACHE
 215                         LOCKED
 216
 217     SAVE                COMPRESS
 218                         ENCRYPT
 219                         CACHE
 220                         LOCKED
 221
 222     CLEARCACHE          CACHE
 223                         LOCKED
 224
 225     CACHETIMEOUT        CACHE
 226                         LOCKED
 227
 228     ISCACHED            LOCKED
 229
 230
 231     KEYWORD             OUTPUT FORMAT
 232     ---------------------------------
 233     CACHE               <slots used> <slots available>
 234     ENCRYPT             <iterations so far>
 235     DECRYPT             <iterations so far>
 236     COMPRESS            <bytes so far> <total bytes>
 237     DECOMPRESS          <bytes so far> <total bytes>
 238     LOCKED              When another thread owns the file/key cache lock,
 239                         this is sent once and the thread blocks until the
 240                         lock can be obtained and the command completes.
 241     KEEPALIVE           Sent the after every configured amount of seconds.
 242                         This lets the client know that the connection is still
 243                         active for commands that take a while to complete.
 244
 245
 246 THE TARGET ATTRIBUTE
 247 --------------------
 248 There is a special attribute "target" (case sensitive) that can be set with
 249 ATTR SET. The value of this attribute is an element path somewhere else in the
 250 XML document:
 251
 252 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 253                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
 254
 255 If the element path of the "target" attribute (arg1) doesn't exist, it is
 256 created. This is the only time the ATTR command will create elements.
 257
 258 When a protocol command requests <arg1> as the element path, the remaining
 259 elements after the element with the "target" attribute will be appended to
 260 <arg2>. This is useful if you have elements that share the same data. If the
 261 target is modified, the other elements "pointing" to the target will have the
 262 same content. To get the real or literal element and ignore any "target"
 263 attributes, prefix an element with a '!' character. Here's an example:
 264
 265     C> STORE
 266     S> INQUIRE STORE
 267     C> D host1<TAB>username<TAB>original username
 268     C> END
 269     S> OK
 270     C> STORE
 271     S> INQUIRE STORE
 272     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 273     C> END
 274     S> OK
 275     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 276     S> OK
 277
 278 Now host1's "target" attribute will be used:
 279
 280     C> GET host1<TAB>username
 281     S> D someuser
 282     S> OK
 283
 284 If you want host1's username, prefix the element of the "target" attribute
 285 with a '!':
 286
 287     C> GET host1<TAB>!username
 288     S> D original username
 289     S> OK
 290
 291 The target value (arg2) element can also have a "target" attribute:
 292
 293     C> ATTR SET target new_account host1
 294     S> OK
 295     C> GET new_account<TAB>username
 296     S> D someuser
 297     S> OK
 298
 299 The value of the "target" attribute may also be prefixed with a '!' to set the
 300 target to the actual element path and not a target of the element path:
 301
 302     C> ATTR DELETE target !new_account
 303     S> OK
 304     C> ATTR SET target new_account<TAB>username host1<TAB>!username
 305     S> OK
 306     C> GET new_account<TAB>username
 307     S> D original username
 308     S> OK
 309
 310 The "target" attribute is considered for all commands that support an element
 311 path. If the target element has been renamed or deleted afterwards, the
 312 command will fail.
 313
 314 Clients should be careful of creating target loops. See the "recursion_depth"
 315 configuration parameter for details.
 316
 317
 318 XML DOCUMENT STRUCTURE
 319 ----------------------
 320 When importing an XML data file with the -I command line option, the document
 321 should have the following DTD:
 322
 323     <?xml version="1.0"?>
 324     <!DOCTYPE accounts [
 325     <!ELEMENT accounts (account*)>
 326     <!ATTLIST account name CDATA #REQUIRED>
 327     ]>
 328
 329 "accounts" is the document root element while each root element mentioned in
 330 the protocol commands use the "account" element. So if you have a root element
 331 "isp" to be shown with the LIST command ("LIST isp"), the document structure
 332 looks like this:
 333
 334     <accounts>
 335         <account name="isp">
 336         [...]
 337         </account>
 338     </accounts>
 339
 340 The DUMP command can be useful to show the current document structure.
 341
 342
 343 Questions, bugs or feature requests can be sent to Ben Kibbey
 344 <bjk@luxsci.net>.