1 The data is stored in an AES-256-CBC encrypted XML file. A client connects to
2 the server and issues commands that manipulate the data. Through the use of
3 a file cache and shared memory passwords do not need to be issued for each
4 file each time a client connects.
6 The server uses a simple protocol to communicate with a client. All non-data
7 responses are prefixed by a server response code followed by a space followed
8 by an (optional) description followed by a newline character. There are three
9 non-data related response codes: NFO for informational messages, ERR for error
10 messages and OK if the command succeeded.
12 A data response is prefixed with a BEGIN response code followed by a space
13 then an integer specifying the number of following data bytes then a newline
14 character. After all of the bytes have been sent a newline character then an
15 OK response code then another newline will be sent.
19 OPEN <filename> [<key>]
20 Opens <filename> using <key>. If file is not found on the filesystem, then
21 a new file will be created. If the file is found, it is looked for in the
22 file cache for an existing key. If found, the existing key will be used
23 for decryption. If the cached key fails then the <key>, if specified, will
28 Encrypts and writes any changes to the file to disk. If <key> is not
29 specified then the currently cached key will be used. If the file is a new
30 file which hasn't yet been saved, <key> is required.
33 CACHE [ISCACHED <filename>] |
34 [RESETALL] | [RESET <filename] |
35 [CLEARALL] | [CLEAR <filename] |
36 [TIMEOUT <seconds> <filename>]
37 RESETALL - Removes all cached keys for all files.
39 RESET - Like RESETALL but only for the specified file.
41 CLEARALL - Clears the entire file cache. This forgets a file entirely;
44 CLEAR - Like CLEARALL but only for the specified file.
46 ISCACHED - A response code of OK will be returned if the specified file is
47 in the file cache. If not in the cache or the file doesn't
48 exist on the filesystem or has a size of 0, an ERR response is
51 TIMEOUT - Specify the number of seconds the specified file will be
52 cached. -1 will keep the cache entry forever, 0 will require
53 the key each time the file is OPEN'ed or SAVE'd.
55 A file doesn't need to be opened to use this command.
58 LIST [element[<TAB>element[...]]]
59 If no element path is given, then a list of accounts is returned with a
60 BEGIN repsonse code. If given, then the element tree for the specified
61 element path is returned. See the ATTR command and the VALUE attribute.
64 STORE account[<TAB>element[<TAB>element[...]]<TAB>value]
65 Stores an element tree into the existing <account>, creates a new
66 <account> tree or modifies the value for an existing element path. If no
67 elements are specifed an empty account is created. Otherwise, elements are
68 TAB deliminated and the value will be the last TAB deliminated argument.
69 The only restriction of element names is that they not contain any
70 whitespace. There is no whitespace between the TAB deliminated element
71 arguments. It is recommended that the value be base 64 encoded to prevent
72 libXML and pwmd parsing errors.
75 DELETE account[<TAB>element[...]]
76 Removes an element tree from <account> or the entire <account> if no
80 GET [!]<account><TAB>element[<TAB>element[...]]
81 Retrieves the value or content for the specified element tree. If the
82 account is prefixed with a '!' and an element in the element path contains
83 a "target" attribute the target attribute will not be followed and the
84 actual value of the element path will be returned. See the ATTR command
85 for details about the "target" attribute. The data is returned with the
89 ATTR SET|GET|DELETE|LIST [<attribute>] <arg1> [arg2]
90 ATTR SET attribute account[<TAB>element[...]] attribute_value
91 ATTR DELETE attribute account[<TAB>element[...]]
92 ATTR LIST account[<TAB>element[...]]
93 ATTR GET attribute account[<TAB>element[...]]
95 The "name" attribute cannot be DELETE'd if the element path is only the
96 account name. Although it can be SET to change the account name.
98 There is one other special attribute which is "target". This is like a
99 pointer that points to another element in the document:
101 ATTR SET target account[<TAB>element[...]] account[<TAB>element[...]]
103 Then the GET and LIST protocol commands for <arg1> would show the value of
104 <arg2>. Note that if <arg1> has both a target attribute and an element
105 value, then only the target attribute will be used in other protocol
106 commands unless the account is prefixed with a '!'. If the target has been
107 renamed or deleted afterwards then the GET protocol command will fail and
108 the LIST protocol command will silently ignore the element with the not
113 Shows protocol command help for <command> or shows available commands if
114 <command> is not specified. A file doesn't need to be opened to use this
119 Show the in memory document. Useful for pruning empty elements which
120 aren't shown with the LIST command.
124 Closes the connection. Use the SAVE command before this command as any
125 changes will be lost.
128 If a command fails then the ERR response is returned followed by a protocol
129 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
132 Ben Kibbey <bjk@luxsci.net>