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