1 The server uses a protocol provided by libassuan to communicate with the
2 client. An OK response is returned when a command succeeds or ERR along with
3 an error code and description, if not. When a command requests data for
4 retrieval (e.g., GET) the output is prefixed with D then a single SPACE then
5 the actual data followed by a response. Read the libassuan docs for more info
11 OPEN <filename> [<key>]
12 Opens <filename> using <key>. If file is not found on the file-system, then
13 a new document will be created. If the file is found, it is looked for in
14 the file cache for an existing key. When found, the existing key will be
15 used for decryption. When not found, pinentry(1) will be used to retrieve
16 the key (see OPTIONS below). You can also open a different file using the
17 same connection. When using an empty key and you want to avoid the
18 pinentry dialog, set PINENTRY to 0 (see OPTIONS below).
22 Writes the XML document to disk. The file written to is the file that was
23 opened using the OPEN command. If <key> is not specified then the
24 currently cached key will be used. If the file is a new file or the file
25 isn't found in the file cache, <key> may be used. If <key> is not
26 specified then pinentry(1) will be used to retrieve the key (see OPTIONS
27 below). When using an empty key and you want to avoid the pinentry dialog,
28 set PINENTRY to 0 (see OPTIONS below).
30 When the SAVE command is sent and a key is found in the file cache, the
31 cached key will be used. To reset the key to a new value, send the
32 CLEARCACHE command followed by the filename, then send the SAVE command to
37 An OK response is returned if the specified file is in the file cache.
40 CLEARCACHE [<filename>]
41 Clears a file cache entry. This will forget the timeout and key for all or
45 CACHETIMEOUT <seconds> <filename>
46 Specify the number of seconds the specified file will be cached. -1 will
47 keep the cache entry forever, 0 will require the key each time the OPEN or
48 SAVE commands are used. Also see the "cache_timeout" configuration option.
51 LIST [[!]element[<TAB>[!]element[...]]]
52 If no element path is given then a list of root elements is returned with
53 the data response code. If given, then all reachable elements for the
54 specified element path are returned. Each element in the path is prefixed
55 with the literal '!' character when the element contains no "target"
56 attribute (See THE TARGET ATTRIBUTE below).
59 REALPATH [!]element[<TAB>[!]element[...]]
60 Resolves all "target" attributes of the specified element path and returns
61 the result with a data response.
64 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
65 Creates a new element tree or modifies the content of an existing element
66 path. If only a single element is specified, a new root element is
67 created. Otherwise, elements are TAB delimited and the content will be set
68 to the last TAB delimited argument. If no content is specified after the
69 last TAB then the content for the last specified element will be removed
70 or empty if creating a new element.
72 The only restriction of element names is that they not begin with a
73 punctuation character (the literal '!' character is an exception) or digit
74 and not contain any whitespace. There is no whitespace between the TAB
75 delimited elements. It is recommended that the value be base 64 encoded to
76 prevent libXML and pwmd parsing errors.
78 PWMD reads the element path from the client via the Assuan INQUIRE
79 protocol response. The STORE command is sent by itself without arguments,
80 then the server responds with INQUIRE. The client then sends the element
81 path prefixed with a "D " data response. When finished, the client sends
82 "END" on an empty line. This is needed so an element path and value can be
83 more than 1000 bytes long, the Assuan protocol line limit.
86 DELETE [!]element[<TAB>[!]element[...]]
87 Removes an element tree from the specified element path.
90 GET [!]element[<TAB>[!]element[...]]
91 Retrieves the text content of the specified element path. The data is
92 returned with a data response.
95 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
96 ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
97 Stores or updates an attribute value of an element path.
99 ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
100 Removes an attribute from an element path.
102 ATTR LIST [!]element[<TAB>[!]element[...]]
103 Gets a list of attributes from an element path.
105 ATTR GET attribute [!]element[<TAB>[!]element[...]]
106 Gets the value of an attribute from an element path.
108 The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
109 if the element path is only a root element. Although it can be SET to
110 change the root element name.
112 Also see THE TARGET ATTRIBUTE below.
115 XPATH <expression>[<TAB>[value]]
116 Evaluates an XPath expression. If no value argument is specified, it is
117 assumed the expression is a request to return a result. Otherwise, the
118 result is set to the value argument and the document is updated. If there
119 is no value after the <TAB> character, the value is assumed to be empty
120 and the document is updated.
123 IMPORT [!]element[<TAB>[!]element[...]] <content>
124 Like the STORE command (an INQUIRE), but the content argument is raw XML
125 data. The content is created as a child of the specified element path. If
126 an element of the element path does not exist, it is created.
128 Note that the new content must begin with an element and not text. Also
129 note that an existing child node of the same element name as the root node
130 of the imported content will be overwritten.
134 Shows the in memory XML document with indenting. To dump a specific
135 element tree, use the XPATH command.
138 GETCONFIG <parameter>
139 Returns the value of a pwmd configuration variable with a data response.
140 If no file is open then the default value will be returned. The "key" and
141 "key_file" variables are ignored.
144 OPTION <NAME>=<VALUE>
145 Sets an option NAME to VALUE. See OPTIONS below.
149 Closes the connection. Use the SAVE command before this command as any
150 changes will be lost.
153 If a command fails then the ERR response is returned followed by a protocol
154 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
160 Commands that require a key that is neither cached nor specified will use
161 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
162 command followed by the option name and value. Below are the available
165 NAME VALUE Description
166 ---------|----------|----------------------------------------------------
167 PINENTRY 0|1 When 0, disable use of pinentry. The default is 1.
168 PATH <string> Full path to the pinentry binary. The default is
169 specified at compile time (/usr/bin/pinentry).
170 TTYNAME <string> Same as the --ttyname option to pinentry(1).
171 TTYTYPE <string> Same as the --ttytype option to pinentry(1).
172 DISPLAY <string> Same as the --display option to pinentry(1).
173 TITLE <string> Sets the title string of the dialog.
174 PROMPT <string> Sets the prompt string of the dialog.
175 DESC <string> Sets the error or description string of the dialog.
177 When pinentry is used with the SAVE command the key will be asked for
178 confirmation. If the confirmation fails, the process is started over again
179 until either the keys match or until Cancel is selected. The OPEN command will
180 only ask for the key once without retrying on failure. It is up to the client
181 to retry the OPEN command. Empty keys are allowed.
183 There is also a CLIENT option that contains other sub-options. The format is
184 OPTION CLIENT NAME=VALUE, where NAME is one of:
186 NAME VALUE Description
187 ---------|----------|----------------------------------------------------
188 NAME <string> Associates the thread ID of the connection with the
189 specified textual representation. Useful for
190 debugging log messages.
195 Some commands send a status message to the client when successful or as a
196 progress indicator. Status messages begin with a KEYWORD (see below) followed
197 by the status description. What messages are sent, and how often, depend on
198 configuration settings:
201 --------------------------------
221 KEYWORD OUTPUT FORMAT
222 ---------------------------------
223 CACHE <slots used> <slots available>
224 ENCRYPT <iterations so far>
225 DECRYPT <iterations so far>
226 COMPRESS <bytes so far> <total bytes>
227 DECOMPRESS <bytes so far> <total bytes>
228 LOCKED When another thread owns the file/key cache lock,
229 this is sent once and the thread blocks until the
230 lock can be obtained and the command completes.
231 KEEPALIVE Sent the after every configured amount of seconds.
232 This lets the client know that the connection is still
233 active for commands that take a while to complete.
238 There is a special attribute "target" (case sensitive) that can be set with
239 ATTR SET. The value of this attribute is an element path that is located
240 somewhere else in the XML document and are alot like how XPath treats
241 entities, but are needed do to how pwmd commands are implemented. The syntax
244 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
245 arg1^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^
247 If the element path of the "target" attribute (arg1) doesn't exist, it is
248 created. This is the only time the ATTR command will create elements.
250 When a protocol command requests <arg1> as the element path, the remaining
251 elements after the element with the "target" attribute will be appended to
252 <arg2>. This is useful if you have elements that share the same data. If the
253 target is modified, the other elements "pointing" to the target will have the
254 same content. To get the real or literal element and ignore any "target"
255 attributes, prefix an element with a '!' character. Here's an example:
259 C> D host1<TAB>username<TAB>original username
264 C> D host2<TAB>smtp<TAB>username<TAB>someuser
267 C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
270 Now host1's "target" attribute will be used:
272 C> GET host1<TAB>username
276 If you want host1's username, prefix the element of the "target" attribute
279 C> GET host1<TAB>!username
280 S> D original username
283 The target value (arg2) element can also have a "target" attribute:
285 C> ATTR SET target new_account host1
287 C> GET new_account<TAB>username
291 The value of the "target" attribute may also be prefixed with a '!' to set the
292 target to the actual element path and not a target of the element path:
294 C> ATTR DELETE target !new_account
296 C> ATTR SET target new_account<TAB>username host1<TAB>!username
298 C> GET new_account<TAB>username
299 S> D original username
302 The "target" attribute is considered for all commands that support an element
303 path. If the target element has been renamed or deleted afterwards, the
306 Clients should be careful of creating target loops. See the "recursion_depth"
307 configuration parameter for details.
310 XML DOCUMENT STRUCTURE
311 ----------------------
312 When importing an XML data file with the -I command line option, the document
313 should have the following DTD:
315 <?xml version="1.0"?>
317 <!ELEMENT accounts (account*)>
318 <!ATTLIST account name CDATA #REQUIRED>
321 "accounts" is the document root element while each root element mentioned in
322 the protocol commands use the "account" element. So if you have a root element
323 "isp" to be shown with the LIST command ("LIST isp"), the document structure
332 The DUMP command can be useful to show the current document structure.
337 The key cache is protected with a mutex and is locked with each access. Each
338 cache entry also contains a mutex for the opened file and a reference count
339 which is adjusted each time a client connects or disconnects. This allows
340 client A to issue commands that aren't related to the file opened by client B.
341 The refcount is needed to prevent the mutex being overwritten when the entry
342 needs to be reset (CACHETIMEOUT for example) and there are any clients
345 The client_thread() uses an event to wait for the client FD to become ready
346 for reading. When ready, it uses the libassuan assuan_process_next() function
347 to prevent blocking. This allows for the keepalive_thread() and any signals
348 send to client_thread() to continue to work and lets the Pth scheduler let
349 other (client) threads do their work too. It's completely asynchronous.
351 The cleanup_thread() is a loop that sleeps at some interval and is responsible
352 for freeing the resources of a client after client_thread() terminates or
353 exits. How it determines if the client exited is done with the
354 PTH_UNTIL_TID_DEAD event; it checks a list of recorded connections for that
357 When a key is required for the OPEN or SAVE commands, and OPTION PINENTRY=1,
358 pinentry(1) is used to retrieve the key. This is done by creating a pipe()
359 with the client_thread(), then pth_fork()'s the pinentry process which will
360 write the key or error to the pipe that client_thread() will read from. After
361 the read, the pinentry will have exited and client_thread() calls the
362 finalization function for the command that used pinentry.
364 ------------- ---------------
365 ----------[server_loop]-_-_-_-[accept_thread]
366 | ------------- ---------------
368 | --------------------- ---------------
369 | [adjust_timer_thread] [client_thread]<------------=====
370 | --------------------- --------------- | | | =
372 |---| : | | | | | | =
374 ---------------- : | | | | | | =
375 [cleanup_thread] ::::::::: | | | | | | =
376 ---------------- : | | --------- | | =
377 | pth_cancel() : | | [command] | | =
378 | ------------------ | | --------- | | = pipe()
379 |--------[keepalive_thread] | | | | | | =
380 ------------------ | | | --------- | =
384 | | |----[OPEN/SAVE] =
386 ------------------ : fork() =
387 [command finalize] ---------- =
388 ------------------ [pinentry]====
391 There is also a library libpwmd which makes it easy for applications to use
392 the server. It supports it's own key retrieval and asynchronous interaction
395 The latest version of both pwmd and libpwmd can be obtained from
396 http://bjk.sourceforge.net/pwmd/. Feel free to send me any questions, bug
397 reports or feature requests.
399 Ben Kibbey <bjk@luxsci.net>