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 the filename is not found on the
13 file-system, then a new document will be created. If the file is found, it
14 is looked for in the file cache for an existing key. When found and no key
15 was specified, the cached key will be used for decryption (if encrypted).
16 When not found, pinentry(1) will be used to retrieve the key (see OPTIONS
17 below). You can also open a different file using the same connection. When
18 using an empty or NULL key and you want to avoid the pinentry dialog, set
19 PINENTRY to 0 (see OPTIONS below).
23 Writes the XML document to disk. The file written to is the file that was
24 opened using the OPEN command. If <key> is not specified then the
25 currently cached key will be used. If the file is a new file or the file
26 isn't found in the file cache, <key> will be used. If <key> is not
27 specified then pinentry(1) will be used to retrieve the key (see OPTIONS
28 below). If you want to use and empty key and want to avoid the pinentry
29 dialog, set PINENTRY to 0 (see OPTIONS below).
33 An OK response is returned if the specified file is found in the file
37 CLEARCACHE [<filename>]
38 Clears a file cache entry. This will forget the timeout and key for all or
39 the specified file. Always returns an OK response.
42 CACHETIMEOUT <seconds> <filename>
43 Specify the number of seconds the specified file will be cached. -1 will
44 keep the cache entry forever, 0 will require the key each time the OPEN or
45 SAVE commands are used. Also see the "cache_timeout" configuration
46 parameter. Returns ERR if the filename isn't cached or if the timeout is
47 invalid. OK otherwise.
50 LIST [[!]element[<TAB>[!]element[...]]]
51 If no element path is given then a list of root elements is returned with
52 the data response. If given, then all reachable elements for the
53 specified element path are returned. Each element in the path is prefixed
54 with the literal '!' character when the element contains no "target"
55 attribute (See THE TARGET ATTRIBUTE below).
58 REALPATH [!]element[<TAB>[!]element[...]]
59 Resolves all "target" attributes of the specified element path and returns
60 the result with a data response.
63 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
64 Creates a new element tree or modifies the content of an existing element
65 path. If only a single element is specified, a new root element is
66 created. Otherwise, elements are TAB delimited and the content will be set
67 to the last TAB delimited argument. If no content is specified after the
68 last TAB then the content for the last specified element will be removed
69 or empty if creating a new element.
71 The only restriction of element names is that they not begin with a
72 punctuation character (the literal '!' character is an exception) or digit
73 and not contain any whitespace. There is no whitespace between the TAB
74 delimited elements. It is recommended that the value be base 64 encoded to
75 prevent XML and pwmd parsing errors.
77 PWMD reads the element path from the client via the Assuan INQUIRE
78 protocol response. The STORE command is sent by itself without arguments,
79 then the server responds with INQUIRE. The client then sends the element
80 path prefixed with a "D " data response. The element path may extend
81 multiple lines but each must be prefixed with the data "D " response. When
82 finished, the client sends "END" on an empty line. This is needed so an
83 element path and value can be more than 1000 bytes long, the Assuan
87 DELETE [!]element[<TAB>[!]element[...]]
88 Removes an element tree from the specified element path.
91 GET [!]element[<TAB>[!]element[...]]
92 Retrieves the content or text node of the specified element path. The data
93 is returned with a data response.
96 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
97 ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
98 Stores or updates an attribute value of an element path.
100 ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
101 Removes an attribute from an element path.
103 ATTR LIST [!]element[<TAB>[!]element[...]]
104 Gets a list of attributes from an element path.
106 ATTR GET attribute [!]element[<TAB>[!]element[...]]
107 Gets the value of an attribute from an element path.
109 The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
110 if the element path is the root element. Although it can be SET to change
111 the root element name.
113 Also see THE TARGET ATTRIBUTE below.
116 XPATH <expression>[<TAB>[value]]
117 Evaluates an XPath expression. If no value argument is specified, it is
118 assumed the expression is a request to return a result. Otherwise, the
119 result is set to the value argument and the document is updated. If there
120 is no value after the <TAB> character, the value is assumed to be empty
121 and the document is updated.
124 IMPORT [!]element[<TAB>[!]element[...]] <content>
125 Like the STORE command (an INQUIRE), but the content argument is raw XML
126 data. The content is created as a child of the specified element path. If
127 an element of the element path does not exist, it is created.
129 Note that the new content must begin with an element node. Also note that
130 an existing child node of the same element name as the root node of the
131 imported content will be overwritten.
135 Shows the in memory XML document with indenting. To dump a specific
136 element tree, use the XPATH command.
140 Locks the mutex associated with the opened file. This prevents other
141 clients from sending commands to the same opened file until the client
142 that sent this command either disconnects or sends the UNLOCK command.
146 Unlocks the mutex which was locked with the LOCK command.
150 Retrieves the process id of the server.
153 GETCONFIG [filename] <parameter>
154 Returns the value of a pwmd configuration variable with a data response.
155 If no file is open then the specified files value or the default ("global"
156 section) will be returned. If there is no such parameter defined,
157 GPG_ERR_NO_VALUE is returned.
161 Returns the server version number with a data response.
164 OPTION <NAME>=<VALUE>
165 Sets an option NAME to VALUE. See OPTIONS below for available options.
169 Closes the connection disconnecting the client. Unless the SAVE command
170 had been sent, any changes to the document will be lost.
175 Commands that require a key that is neither cached nor specified will use
176 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
177 command followed by the option name and value. Below are the available
180 NAME VALUE Description
181 ---------|----------|----------------------------------------------------
182 PINENTRY 0|1 When 0, disable use of pinentry. The default is 1.
183 TIMEOUT <integer> The number of seconds before the pinentry process
184 will terminate while waiting for a passphrase. The
185 default is 20, 0 disables.
186 PATH <string> Full path to the pinentry binary. The default is
187 specified at compile time.
188 TTYNAME <string> Same as the --ttyname option to pinentry(1).
189 TTYTYPE <string> Same as the --ttytype option to pinentry(1).
190 DISPLAY <string> Same as the --display option to pinentry(1).
191 TITLE <string> Sets the title string of the pinentry dialog.
192 PROMPT <string> Sets the prompt string of the pinentry dialog.
193 DESC <string> Sets the error or description string of the pinenry
194 LC_CTYPE <string> Same as the --lc-ctype option to pinentry(1).
195 LC_MESSAGES <string> Same as the --lc-messages option to pinentry(1).
196 ITERATIONS <integer> The number of encryption iterations to do when the
197 SAVE command is sent. When set, the configured
198 value will be updated to this value for the opened
199 file, or the "global" default if no file has been
200 opened yet. When setting this option before opening
201 a file, this option is reset to the data files
202 setting after opening. The CONFIG status message is
203 sent after receiving this command.
204 CLIENT <string> See below.
206 When pinentry is used with the SAVE command the passphrase will be asked for
207 confirmation. If the confirmation fails, the process is started over again
208 until either the passphrases match or until Cancel is selected. The OPEN
209 command will only ask for the passphrase once without retrying on failure. It
210 is up to the client to retry the OPEN command. Empty keys are allowed. To
211 prevent pinentry asking for an (empty) passphrase, set OPTION PINENTRY=0.
213 There is also a CLIENT option that contains other sub-options. The format is
214 OPTION CLIENT NAME=VALUE, where the option NAME is one of:
216 NAME VALUE Description
217 ---------|----------|----------------------------------------------------
218 NAME <string> Associates the thread ID of the connection with the
219 specified textual representation. Useful for
220 debugging log messages.
225 Some commands send a status message to the client when successful or as a
226 progress indicator. Status messages begin with a KEYWORD (see below) followed
227 by the status description. What messages are sent, when, and how often, depend
228 on configuration settings:
231 --------------------------------
247 KEYWORD OUTPUT FORMAT
248 ---------------------------------
250 Sent to each client after the file cache changes.
251 ENCRYPT <iterations so far> <total iterations>
252 DECRYPT <iterations so far> <total iterations>
253 COMPRESS <bytes so far> <total bytes>
254 DECOMPRESS <bytes so far> <total bytes>
255 LOCKED When another thread owns the file/key cache mutex
256 lock, this is sent at some interval and the thread
257 will block until the lock can be obtained.
258 KEEPALIVE Sent to each client after every configured amount of
259 seconds. This lets the client know that the connection
260 is still active for commands that take awhile to
262 CONFIG Sent to each client after the configuration file has
263 been reloaded or has had a value changed.
264 CLIENTS Sent to each client after a client connects or
270 There is a special attribute "target" (case sensitive) that can be set with
271 ATTR SET. The value of this attribute is an element path that is located
272 somewhere else in the XML document and are alot like how XPath treats
273 entities, but is needed do to how pwmd commands are implemented. The syntax
276 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
277 arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^
279 If the element path of the "target" attribute (arg1) doesn't exist, it is
280 created. This is the only time the ATTR command will create elements.
282 When a protocol command requests <arg1> as the element path, the remaining
283 elements after the element with the "target" attribute will be appended to
284 <arg2>. This is useful if you have elements that share the same data. If the
285 target is modified, the other elements "pointing" to the target will have the
286 same content. To get the real or literal element and ignore any "target"
287 attributes, prefix the element with a '!' character. Here's an example:
291 C> D host1<TAB>username<TAB>original username
296 C> D host2<TAB>smtp<TAB>username<TAB>someuser
299 C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
302 Now host1's "target" attribute will be used:
304 C> GET host1<TAB>username
308 If you want host1's username, prefix the element of the "target" attribute
311 C> GET host1<TAB>!username
312 S> D original username
315 The target value (arg2) element can also have a "target" attribute:
317 C> ATTR SET target new_account host1
319 C> GET new_account<TAB>username
323 The value of the "target" attribute may also be prefixed with a '!' to set the
324 target to the actual element path and not a target of the element path:
326 C> ATTR DELETE target !new_account
328 C> ATTR SET target new_account<TAB>username host1<TAB>!username
330 C> GET new_account<TAB>username
331 S> D original username
334 The "target" attribute is considered for all commands that support an element
335 path. If the target element has been renamed or deleted afterwards, the
338 Clients should be careful of creating target loops. See the "recursion_depth"
339 configuration parameter for details.
342 XML DOCUMENT STRUCTURE
343 ----------------------
344 When importing an XML data file with the -I command line option, the document
345 should have the following DTD:
347 <?xml version="1.0"?>
349 <!ELEMENT pwmd (root*)>
350 <!ATTLIST root name CDATA #REQUIRED>
353 The "pwmd" element is the document root node while the first element of an
354 element path specified in protocol commands use the "root" element. So if you
355 specify the command "LIST isp", "isp" is really a "root" element that has a
356 "name" attribute with the value "isp". Any following elements are children of
365 The remaining <TAB> delimited elements (e.g., "LIST isp<TAB>SMTP") are regular
366 elements and are not treated specially in the XML document.
368 The DUMP command might be useful to show the document structure.
373 The key cache is protected with a mutex and is locked with each access. Each
374 cache entry also contains a mutex for the opened file and a reference count
375 which is adjusted each time a client connects or disconnects. This allows
376 client A to issue commands that aren't related to the file opened by client B.
377 The refcount is needed to prevent the mutex being overwritten when the entry
378 needs to be reset (CACHETIMEOUT for example) and there are any clients
381 The client_thread() uses an event to wait for the client FD to become ready
382 for reading. When ready, it uses the libassuan external IO loop functions to
383 prevent blocking letting other threads do their work.
385 When a key is required for the OPEN or SAVE commands, and OPTION PINENTRY=1,
386 pinentry(1) is used to retrieve the key. This is done by creating a pipe()
387 with the client_thread(), then pth_fork()'s the pinentry process which will
388 write the key or error to the pipe that client_thread() will read from. After
389 the read, the pinentry will have exited and client_thread() calls the
390 finalization function for the original command.
392 ------------- ---------------
393 [server_loop]-_-_-_-[accept_thread]
394 ------------- ---------------
396 --------------------- ---------------
397 [adjust_timer_thread] |--[client_thread]<----------=====
398 --------------------- | --------------- | | | =
399 ---------------| | | --------- | | =
400 | ------------------ [command] | | =
401 | [command finalize] --------- | | = pipe()
402 | ------------------ | | | | =
403 ------------------- | --------- | =
404 |client_msg_thread| | [INQUIRE] | =
405 ------------------- | --------- | =
414 There is also a library libpwmd which makes it easy for applications to use
415 the server. It supports it's own key retrieval (for clients that need it) and
416 asynchronous interaction with pwmd. It also includes a command line client for
417 sending commands to pwmd.
419 The latest version of both pwmd and libpwmd can be obtained from
420 http://bjk.sourceforge.net/pwmd/. Feel free to send me any questions, bug
421 reports, patches or feature requests.
423 Ben Kibbey <bjk@luxsci.net>