1 The server uses a protocol provided by libassuan to communicate with a client.
2 An OK response is returned when a command succeeds or ERR along with an error
3 code and description, if not. When a command requests data for retrieval
4 (e.g., GET) the output is prefixed with D then a single SPACE then the actual
5 data followed by an OK response. Read the libassuan docs for more info about
12 OPEN <filename> [<key>]
13 Opens <filename> using <key>. If file is not found on the file-system, then
14 a new document will be created. If the file is found, it is looked for in
15 the file cache for an existing key. When found, the existing key will be
16 used for decryption. When not found, pinentry(1) will be used to retrieve
17 the key (see OPTIONS below). You can also open another file using the
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
31 An OK response is returned if the specified file is in the file cache.
34 CLEARCACHE [<filename>]
35 Clears a file cache entry. This will forget the timeout and key for all or
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 OPEN or
42 SAVE commands are used. Also see the "cache_timeout" configuration option.
45 LIST [[!]element[<TAB>[!]element[...]]]
46 If no element path is given then a list of root elements is returned with
47 the data response code. If given, then all reachable elements for the
48 specified element path are returned. Each element in the path is prefixed
49 with the literal '!' character when the element contains no "target"
50 attribute (See THE TARGET ATTRIBUTE below).
52 If only a single element is specified and without the literal '!' prefix,
53 both the literal element tree and the element target (if any) tree will be
57 REALPATH [!]element[<TAB>[!]element[...]]
58 Resolves all "target" attributes of the specified element path and returns
59 the result with a data response.
62 STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
63 Creates a new element tree or modifies the content of an existing element
64 path. If only a single element is specified, a new root element is
65 created. Otherwise, elements are TAB delimited and the content will be set
66 to the last TAB delimited argument. If no content is specified after the
67 last TAB then the content for the last specified element will be removed
68 or the content will be empty when creating a new element.
70 The only restriction of element names is that they not begin with a
71 punctuation character (the literal '!' character is an exception) or digit
72 and not contain any whitespace. There is no whitespace between the TAB
73 delimited elements. It is recommended that the value be base 64 encoded to
74 prevent libXML and pwmd parsing errors.
76 PWMD reads the element path from the client via the Assuan INQUIRE
77 protocol response. The STORE command is sent by itself without arguments,
78 then the server responds with INQUIRE. The client then sends the element
79 path prefixed by a "D " data response. When finished, the client
80 sends "END" on an empty line. This is needed so an element path and value
81 can be more than 1000 bytes long, the Assuan protocol line limit.
84 DELETE [!]element[<TAB>[!]element[...]]
85 Removes an element tree from the specified element path.
88 GET [!]element[<TAB>[!]element[...]]
89 Retrieves the content of the specified element path. The data is returned
93 ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
94 ATTR SET attribute [!]element[<TAB>[!]element[...]] attribute_value
95 Stores or updates an attribute value to an element path.
97 ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
98 Removes an attribute from an element path.
100 ATTR LIST [!]element[<TAB>[!]element[...]]
101 Gets a list of attributes from an element path.
103 ATTR GET attribute [!]element[<TAB>[!]element[...]]
104 Gets the value of an attribute from an element path.
106 The "name" attribute (case sensitive) cannot be removed with ATTR DELETE
107 if the element path is only a root element. Although it can be SET to
108 change the root element name.
110 Also see THE TARGET ATTRIBUTE below.
114 Shows the in memory XML document with indenting.
117 GETCONFIG <parameter>
118 Returns the value of a pwmd configuration variable with a data response.
119 If no file is open then the default value will be returned. The "key" and
120 "key_file" variables are ignored.
124 Sets an option NAME to VALUE. See OPTIONS below.
128 Closes the connection. Use the SAVE command before this command as any
129 changes will be lost.
132 If a command fails then the ERR response is returned followed by a protocol
133 error code and description. See src/pwmd_error.h or libpwmd/libpwmd.h for
139 Commands that require a key that is neither cached or specified will use
140 pinentry(1) to retrieve the key. Pinentry options can be set with the OPTION
141 command followed by the option name and value. Below are the available
144 NAME VALUE Description
145 ---------|----------|----------------------------------------------------
146 PINENTRY 0|1 When 0, disable use of pinentry. The default is 1.
147 PATH <string> Full path to the pinentry binary. The default is
148 specified at compile time (/usr/bin/pinentry).
149 TTYNAME <string> Same as the --ttyname option to pinentry(1).
150 TTYTYPE <string> Same as the --ttytype option to pinentry(1).
151 DISPLAY <string> Same as the --display option to pinentry(1).
152 TITLE <string> Sets the title string of the dialog.
153 PROMPT <string> Sets the prompt string of the dialog.
154 DESC <string> Sets the error or description string of the dialog.
155 TIMEOUT <N> Terminates pinentry(1) after the elapsed number of
158 There is also a CLIENT option that contains other sub-options. The format is
159 OPTION CLIENT NAME=VALUE, where NAME is one of:
161 NAME VALUE Description
162 ---------|----------|----------------------------------------------------
163 NAME <string> Associates the thread ID of the connection with the
164 specified textual representation. Useful for
165 debugging log messages.
170 Some commands send a status message to the client when successful or as a
171 progress indicator. Status messages begin with a KEYWORD (see below) followed
172 by the status description. What messages are sent, and how often, depend on
173 configuration settings:
176 --------------------------------
196 KEYWORD OUTPUT FORMAT
197 ---------------------------------
198 CACHE <slots used> <slots available>
199 ENCRYPT <iterations so far>
200 DECRYPT <iterations so far>
201 COMPRESS <bytes so far> <total bytes>
202 DECOMPRESS <bytes so far> <total bytes>
203 LOCKED When another thread owns the file/key cache lock,
204 this is sent once and the thread blocks until the
205 lock can be obtained and the command completes.
206 KEEPALIVE Sent the after every configured amount of seconds.
207 This lets the client know that the connection is still
208 active for commands that take a while to complete.
213 There is a special attribute "target" (case sensitive) that can be set with
214 ATTR SET. The value of this attribute is an element path somewhere else in the
217 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
218 arg1^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^
220 If the element path of the "target" attribute (arg1) doesn't exist, it is
221 created. This is the only time the ATTR command will create elements.
223 When a protocol command requests <arg1> as the element path, the remaining
224 elements after the element with the "target" attribute will be appended to
225 <arg2>. This is useful if you have elements that share the same data. If the
226 target is modified, the other elements "pointing" to the target will have the
227 same content. To get the real or literal element and ignore any "target"
228 attributes, prefix an element with a '!' character. Here's an example:
232 C> D host1<TAB>username<TAB>original username
237 C> D host2<TAB>smtp<TAB>username<TAB>someuser
240 C> ATTR SET target host1<TAB>username host2<TAB>smtp<TAB>username
243 Now host1's "target" attribute will be used:
245 C> GET host1<TAB>username
249 If you want host1's username, prefix the element of the "target" attribute
252 C> GET host1<TAB>!username
253 S> D original username
256 The target value (arg2) element can also have a "target" attribute:
258 C> ATTR SET target new_account host1
260 C> GET new_account<TAB>username
264 The value of the "target" attribute may also be prefixed with a '!' to set the
265 target to the actual element path and not a target of the element path:
267 C> ATTR DELETE target !new_account
269 C> ATTR SET target new_account<TAB>username host1<TAB>!username
271 C> GET new_account<TAB>username
272 S> D original username
275 The "target" attribute is considered for all commands that support an element
276 path. If the target element has been renamed or deleted afterwards, the
279 Clients should be careful of creating target loops. See the "recursion_depth"
280 configuration parameter for details.
283 XML DOCUMENT STRUCTURE
284 ----------------------
285 When importing an XML data file with the -I command line option, the document
286 should have the following DTD:
288 <?xml version="1.0"?>
290 <!ELEMENT accounts (account*)>
291 <!ATTLIST account name CDATA #REQUIRED>
294 "accounts" is the document root element while each root element mentioned in
295 the protocol commands use the "account" element. So if you have a root element
296 "isp" to be shown with the LIST command ("LIST isp"), the document structure
305 The DUMP command can be useful to show the current document structure.
308 Questions, bugs or feature requests can be sent to Ben Kibbey