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