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 shared memory a file cache is created so passwords do not need to be issued
4 for each file each time a client connects.
6 The server uses a protocol provided by libassuan to communicate with a client.
7 An OK response is returned if a command succeeded or ERR along with an error
8 code, if not. When a command requests data for retrieval (i.e., GET) the
9 output is prefixed with D then a SPACE then the actual data followed by an OK
10 response. Read the libassuan docs for more info.
14 OPEN <filename> [<key>]
15 Opens <filename> using <key>. If file is not found on the filesystem, then
16 a new document will be created. If the file is found, it is looked for in the
17 file cache for an existing key. When found, the existing key will be used
18 for decryption. If the cached key fails then the <key>, if specified, will
23 Encrypts and writes any changes to the file to disk. If <key> is not
24 specified then the currently cached key will be used. If the file is a new
25 file or the file isn't found in the file cache, <key> is required.
29 A response code of OK will be returned if the specified file is in the
30 file cache. If not in the cache or the file doesn't exist on the
31 filesystem or has a size of 0, an ERR response is returned.
34 CLEARCACHE [<filename>]
35 Clears a file cache entry. This will forget the timeout and key for
36 all or the specified file.
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 file is
45 LIST [element[<TAB>element[...]]]
46 If no element path is given, then a list of accounts is returned with the
47 data repsonse code. If given, then the element tree for the specified
48 element path is returned. The "target" attribute is ignored for this
49 command at the moment.
52 REALPATH account[<TAB>element[...]]
53 Resolves all "target" attributes of the specified element path and returns
54 the result with a data response.
57 STORE [!]account[<TAB>element[<TAB>element[...]]<TAB>value]
58 PWMD reads the element path from the client via the assuan INQUIRE
59 protocol response. The STORE command is sent by itself without arguments,
60 then the server responds with INQUIRE. The client then sends the element
61 path prefixed by a 'D<space>' client response. When finished, the client
62 sends 'END' on an empty line. This is needed so an element path and value
63 can be more than 1000 bytes long.
65 This command stores an element tree into the existing <account>, creates a
66 new <account> tree or modifies the content of an existing element path. If
67 no elements are specifed an empty account is created. Otherwise, elements
68 are TAB deliminated and the content will be set to the last TAB
69 deliminated argument. The only restriction of element names is that they
70 not contain any whitespace. There is no whitespace between the TAB
71 deliminated element arguments. It is recommended that the value be base 64
72 encoded to prevent 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 content of the specified element tree. If the account is
82 prefixed with a '!' and an element in the element path contains a "target"
83 attribute, the target attribute will not be followed and the actual
84 content of the element path will be returned. See the ATTR command for
85 details about the "target" attribute. The data is returned with the data
89 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
90 ATTR SET attribute account[<TAB>element[...]] attribute_value
91 Stores or updates an attribute and value in the element path.
93 ATTR DELETE attribute account[<TAB>element[...]]
94 Removes the specified attribute from the element path.
96 ATTR LIST account[<TAB>element[...]]
97 Gets a list of attributes in the element path.
99 ATTR GET attribute account[<TAB>element[...]]
100 Gets the value of an attribute in the element path.
102 The "name" attribute (case sensitive) cannot be ATTR DELETE'd if the
103 element path is only an account name without any elements. Although it can
104 be ATTR SET to change the account name.
106 See THE TARGET ATTRIBUTE below.
110 Shows the in memory XML document. Hard to read unless you use pwmc
111 included with libpwmd: echo dump | pwmc <filename>
115 Closes the connection. Use the SAVE command before this command as any
116 changes will be lost.
119 If a command fails then the ERR response is returned followed by a protocol
120 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
126 There is a special attribute "target" (case sensitive)i that can be set with
127 ATTR SET. The value of this attribute is an element path somewhere else in the
130 ATTR SET target [!]account[<TAB>element[...]] [!]account[<TAB>element[...]]
133 If the element path of the "target" attribute doesn't exist, it is created.
134 This is the only time the ATTR command will create elements.
136 When a protocol command requests <arg1> as the element path, the remaining
137 elements after the element with the "target" attribute will be appended to
138 <arg2>. This is useful if you have elements that share the same data. If
139 the target is modified, the other elements will have the same value.
140 Here's an example. C> is the client input, S> is the server response:
144 C> D host1<TAB>username<TAB>original username
149 C> D host2<TAB>smtp<TAB>username<TAB>someuser
152 C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
155 Now host1's "target" attribute will be used:
157 C> GET host1<TAB>username
161 If you want host1's username, prefix the element path of the GET (or other
162 command) element path with a '!':
164 C> GET !host1<TAB>username
165 S> D original username
168 The target value (<arg2>) element can also have a "target" attribute:
170 C> ATTR SET target new_account host1
172 C> GET new_account<TAB>username
176 The value of the "target" attribute may also be prefixed with a '!' to set
177 the target to the actual element path and not a target of the element
180 C> ATTR DELETE target !new_account
182 C> ATTR SET target new_account<TAB>username !host1<TAB>username
184 C> GET new_account<TAB>username
185 S> D original username
188 If the target element has been renamed or deleted afterwards, the command
191 Client's should be careful of creating target loops (a target that
192 references itself). There's no way to break out of it unless the client
193 disconnects or until memory runs out.
196 Questions, bugs or feature requests can be sent to Ben Kibbey