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 THE TARGET ATTRIBUTE
 129 --------------------
 130 There is a special attribute "target" (case sensitive) that can be set with
 131 ATTR SET. The value of this attribute is an element path somewhere else in the
 132 XML document:
 133
 134 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
 135                    arg1^^^^^^^^^^^^^^^^^^^^^^^^    arg2^^^^^^^^^^^^^^^^^^^^^^^^
 136
 137 If the element path of the "target" attribute doesn't exist, it is created.
 138 This is the only time the ATTR command will create elements.
 139
 140 When a protocol command requests <arg1> as the element path, the remaining
 141 elements after the element with the "target" attribute will be appended to
 142 <arg2>. This is useful if you have elements that share the same data. If the
 143 target is modified, the other elements "pointing" to the target will have the
 144 same content. To get the real or literal element and ignore any "target"
 145 attributes, prefix an element with a '!' character. Here's an example:
 146
 147     C> STORE
 148     S> INQUIRE STORE
 149     C> D host1<TAB>username<TAB>original username
 150     C> END
 151     S> OK
 152     C> STORE
 153     S> INQUIRE STORE
 154     C> D host2<TAB>smtp<TAB>username<TAB>someuser
 155     C> END
 156     S> OK
 157     C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
 158     S> OK
 159
 160 Now host1's "target" attribute will be used:
 161
 162     C> GET host1<TAB>username
 163     S> D someuser
 164     S> OK
 165
 166 If you want host1's username, prefix the element path of the GET (or other
 167 command) element path with a '!':
 168
 169     C> GET !host1<TAB>username
 170     S> D original username
 171     S> OK
 172
 173 The target value (<arg2>) element can also have a "target" attribute:
 174
 175     C> ATTR SET target new_account host1
 176     S> OK
 177     C> GET new_account<TAB>username
 178     S> D someuser
 179     S> OK
 180
 181 The value of the "target" attribute may also be prefixed with a '!' to set the
 182 target to the actual element path and not a target of the element path:
 183
 184     C> ATTR DELETE target !new_account
 185     S> OK
 186     C> ATTR SET target new_account<TAB>username !host1<TAB>username
 187     S> OK
 188     C> GET new_account<TAB>username
 189     S> D original username
 190     S> OK
 191
 192 If the target element has been renamed or deleted afterwards, the command will
 193 fail.
 194
 195 Client's should be careful of creating target loops (a target that references
 196 itself). There's no way to break out of it unless the client disconnects or
 197 until memory runs out.
 198
 199
 200 XML DOCUMENT STRUCTURE
 201 ----------------------
 202 When importing an XML data file with the -I command line option, the document
 203 should have the following DTD:
 204
 205     <?xml version="1.0"?>
 206     <!DOCTYPE accounts [
 207     <!ELEMENT accounts (account*)>
 208     <!ATTLIST account name CDATA #REQUIRED>
 209     ]>
 210
 211 "accounts" is the document root element while each root element mentioned
 212 in the above commands uses the "account" element. So if you have a root
 213 element shown with the LIST command that shows "isp", the document
 214 structure looks like this:
 215
 216     <accounts>
 217         <account name="isp">
 218         [...]
 219         </account>
 220     </accounts>
 221
 222 The DUMP command can be useful to show the current document structure.
 223
 224
 225 Questions, bugs or feature requests can be sent to Ben Kibbey
 226 <bjk@luxsci.net>.