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