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 ENABLE_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 ENABLE_PINENTRY to 0 (see OPTIONS below).
33 An OK response is returned if the specified file is found in the file
34 cache. If not found in the cache but exists on the filesystem,
35 GPG_ERR_NOT_FOUND is returned. Otherwise a filesystem error is returned.
38 CLEARCACHE [<filename>]
39 Clears a file cache entry. This will forget the timeout and key for all or
40 the specified file. Always returns an OK response.
43 CACHETIMEOUT <filename> <seconds>
44 Specify the number of seconds the specified file will be cached. -1 will
45 keep the cache entry forever, 0 will require the key each time the OPEN or
46 SAVE commands are used. Also see the "cache_timeout" configuration
47 parameter. Returns ERR if the filename isn't cached or if the timeout is
48 invalid. OK otherwise.
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. 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 XML 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. The element path may extend
82 multiple lines but each must be prefixed with the data "D " response. When
83 finished, the client sends "END" on an empty line. This is needed so an
84 element path and value can be more than 1000 bytes long, the Assuan
88 RENAME [!]element[<TAB>[!]element[...]] <value>
89 Renames the specified element to the new value. If an element of the same
90 name as the value exists then it will be overwritten.
93 COPY [!]element[<TAB>[!]element[...]] [!]element[<TAB>[!]element[...]]
94 Copies the entire element tree starting from the child node of the source
95 element path, to the destination element path. If the destination element
96 path doesn't exist then it is created; otherwise it is overwritten.
98 Note that attributes from the source element path are merged into the
99 destination element path.
102 DELETE [!]element[<TAB>[!]element[...]]
103 Removes an element tree from the specified element path.
106 GET [!]element[<TAB>[!]element[...]]
107 Retrieves the content or text node of the specified element path. The data
108 is returned with a data response.
111 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
112 ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
113 Stores or updates an attribute value of an element path.
115 ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
116 Removes an attribute from an element path.
118 ATTR LIST [!]element[<TAB>[!]element[...]]
119 Gets a list of attributes from an element path.
121 ATTR GET attribute [!]element[<TAB>[!]element[...]]
122 Gets the value of an attribute from an element path.
124 The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
125 if the element path is the root element. Although it can be SET to change
126 the root element name but only if the destination element doesn't exist.
127 Use the RENAME command for that instead.
129 Also see THE TARGET ATTRIBUTE below.
132 XPATH <expression>[<TAB>[value]]
133 Evaluates an XPath expression. If no value argument is specified, it is
134 assumed the expression is a request to return a result. Otherwise, the
135 result is set to the value argument and the document is updated. If there
136 is no value after the <TAB> character, the value is assumed to be empty
137 and the document is updated.
140 IMPORT <content>[<TAB>[!]element[<TAB>[!]element[...]]]
141 Like the STORE command (an INQUIRE), but the content argument is raw XML
142 data. The content is created as a child of the specified element path. If
143 an element of the element path does not exist then it is created. If no
144 element path is specified then the content must begin with an pwmd DTD
147 Note that the new content must begin with an element node. Also note that
148 an existing child node of the same element name as the root node of the
149 imported content will be overwritten.
153 Shows the in memory XML document with indenting. To dump a specific
154 element tree, use the XPATH command.
158 Locks the mutex associated with the opened file. This prevents other
159 clients from sending commands to the same opened file until the client
160 that sent this command either disconnects or sends the UNLOCK command.
164 Unlocks the mutex which was locked with the LOCK command.
168 Retrieves the process id of the server.
171 GETCONFIG [filename] <parameter>
172 Returns the value of a pwmd configuration variable with a data response.
173 If no file has been opened then the value for the specified file or the
174 default from the "global" section will be returned. If a file has been
175 opened and no filename is specified, the value previously set with the SET
176 command, if any, will be returned.
178 If there is no such parameter defined, GPG_ERR_NO_VALUE is returned.
182 Returns the server version number with a data response.
186 Sets an option NAME to VALUE. See OPTIONS below for available options.
190 Resets option NAME to the value specified in the server configuration
191 file. Some options have no default and will be reset to NULL or 0
192 depending on the type.
196 Closes the connection disconnecting the client. Unless the SAVE command
197 had been sent, any changes to the document will be lost.
202 Commands that require a key that is neither cached nor specified will use
203 pinentry(1) to retrieve the key. Pinentry options can be set with the SET
204 command followed by the option name and value. Below are the available pwmd
207 NAME |VALUE |Description
208 -----------------|----------|----------------------------------------------
209 ENABLE_PINENTRY 0|1 When 0, disable use of pinentry. The default
211 PINENTRY_TIMEOUT <integer> The number of seconds before the pinentry
212 process will terminate while waiting for a
213 passphrase. The default is 20, 0 disables.
214 PINENTRTY_PATH <string> Full path to the pinentry binary. The default
215 is specified at compile time.
216 TTYNAME <string> Same as the --ttyname option to pinentry(1).
217 TTYTYPE <string> Same as the --ttytype option to pinentry(1).
218 DISPLAY <string> Same as the --display option to pinentry(1).
219 TITLE <string> Sets the title string of the pinentry dialog.
220 PROMPT <string> Sets the prompt string of the pinentry dialog.
221 DESC <string> Sets the error or description string of the
223 LC_CTYPE <string> Same as the --lc-ctype option to pinentry(1).
224 LC_MESSAGES <string> Same as the --lc-messages option to
226 ITERATIONS <integer> The number of encryption iterations to do
227 when the SAVE command is sent. An opened file
228 is needed when setting this option. The
229 CONFIG status message is sent after receiving
231 NAME <string> Associates the thread ID of the connection
232 with the specified textual representation.
233 Useful for debugging log messages.
234 CIPHER <string> The cipher to use for the next SAVE.
236 When pinentry is used with the SAVE command the passphrase will be asked for
237 confirmation. If the confirmation fails, the process is started over again
238 until either the passphrases match or until Cancel is selected. The OPEN
239 command will only ask for the passphrase once without retrying on failure. It
240 is up to the client to retry the OPEN command. Empty keys are allowed. To
241 prevent pinentry asking for an (empty) passphrase, use SET ENABLE_PINENTRY=0.
243 To reset an option value string to its default, use the UNSET command.
248 Some commands send a status message to the client when successful or as a
249 progress indicator. Status messages begin with a KEYWORD (see below) followed
250 by the status description. What messages are sent, when, and how often, depend
251 on configuration settings:
254 -------------|-------------
278 KEYWORD |OUTPUT FORMAT
279 -----------|--------------------
281 Sent to each client after the file cache changes.
282 ENCRYPT <iterations so far> <total iterations>
283 DECRYPT <iterations so far> <total iterations>
284 COMPRESS <bytes so far> <total bytes>
285 DECOMPRESS <bytes so far> <total bytes>
286 XFER <bytes so far> <total bytes>
287 LOCKED When another thread owns a mutex lock that the current thread
288 needs, this is status message is sent and the thread will
289 block until the lock can be obtained.
290 KEEPALIVE Sent to each client after every configured amount of
291 seconds. It is important that this status message be sent to
292 test for client connectivity.
293 CONFIG Sent to each client after the configuration file has
294 been reloaded or has had a value changed that may affect other
296 CLIENTS Sent to each client after a client connects or disconnects.
301 There is a special attribute "target" (case sensitive) that can be set with
302 ATTR SET. The value of this attribute is an element path that is located
303 somewhere else in the XML document and are alot like how XPath treats
304 entities, but is needed do to how pwmd commands are implemented. The syntax
307 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
308 arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^
310 If the element path of where the "target" attribute (arg1) is to be stored
311 doesn't exist then it will be created. This is the only time the ATTR command
312 will create elements.
314 When a protocol command requests <arg1> as the element path then the path will
315 be modified to use <arg2>. This is useful if you need elements to share the
316 same data. If the target is modified, the other elements "pointing" to the
317 target will have the same content. To get the real or literal element and
318 ignore any "target" attributes, prefix the element with a '!' character.
319 Another way to think of this attribute is that it's like a symbolic link in a
320 filesystem. Here's an example XML document:
324 <element>value a</element>
326 <root name="b" target="a">
327 <element_b>value b/element_b>
329 <root name="c" target="b"/>
330 <root name="d" target="!b"/>
338 Notice that there is not an <element_b> listed. This is because of the
339 "target" attribute. The target attribute is recursive too, meaning that it can
340 point to other elements with a "target" attibute:
346 To get the value of an element with a "target" attribute without resolving the
347 target, prefix the element with the literal element character '!':
353 A "target" attribute value may also contain the literal element character:
359 The value of the "target" attribute isn't limited to only one element. It can
360 be a full element path with literal element characters placed where needed.
361 Use the REALPATH command to resolve all "target" attributes.
363 The "target" attribute is considered for all commands that support an element
364 path. If the target element has been renamed or deleted afterwards, the
367 Clients should be careful of creating target loops or targets which resolve to
368 themselves. See the "recursion_depth" configuration parameter for details.
371 XML DOCUMENT STRUCTURE
372 ----------------------
373 When importing an XML data file with the -I command line option, the document
374 should have the following DTD:
376 <?xml version="1.0"?>
378 <!ELEMENT pwmd (root*)>
379 <!ATTLIST root name CDATA #REQUIRED>
382 The "pwmd" element is the document root node while the first element of an
383 element path specified in protocol commands use the "root" element. So if you
384 specify the command "LIST isp", "isp" is really a "root" element that has a
385 "name" attribute with the value "isp". This is needed do to how the LIST
386 command works. Any following elements are children of the "root" element:
390 <username>bjk</username>
394 <username>someusername</username>
399 The remaining <TAB> delimited elements (e.g., "LIST isp<TAB>SMTP") are regular
400 elements and are not treated specially in the XML document.
402 The DUMP command might be useful to show the document structure.
404 Ben Kibbey <bjk@luxsci.net>
405 http://bjk.sourceforge.net/pwmd/