Be sure doc/pwmd.1 is generated during 'make dist'.
[pwmd.git] / doc / pwmd.html
blobc25ab1cb603b82b3e66e189d6f49e01e609d471e
1 <html lang="en">
2 <head>
3 <title>PWMD Manual</title>
4 <meta http-equiv="Content-Type" content="text/html">
5 <meta name="description" content="PWMD Manual">
6 <meta name="generator" content="makeinfo 4.13">
7 <link title="Top" rel="top" href="#Top">
8 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9 <meta http-equiv="Content-Style-Type" content="text/css">
10 <style type="text/css"><!--
11 pre.display { font-family:inherit }
12 pre.format { font-family:inherit }
13 pre.smalldisplay { font-family:inherit; font-size:smaller }
14 pre.smallformat { font-family:inherit; font-size:smaller }
15 pre.smallexample { font-size:smaller }
16 pre.smalllisp { font-size:smaller }
17 span.sc { font-variant:small-caps }
18 span.roman { font-family:serif; font-weight:normal; }
19 span.sansserif { font-family:sans-serif; font-weight:normal; }
20 --></style>
21 </head>
22 <body>
23 <h1 class="settitle">PWMD Manual</h1>
24 <div class="node">
25 <a name="Top"></a>
26 <p><hr>
27 Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
29 </div>
31 <ul class="menu">
32 <li><a accesskey="1" href="#Introduction">Introduction</a>: Overview of pwmd.
33 <li><a accesskey="2" href="#Invoking">Invoking</a>: Command line options.
34 <li><a accesskey="3" href="#Configuration">Configuration</a>: Configuration file options.
35 <li><a accesskey="4" href="#Commands">Commands</a>: Protocol commands.
36 <li><a accesskey="5" href="#Status-Messages">Status Messages</a>: Status lines and their meaning.
37 <li><a accesskey="6" href="#Target-Attribute">Target Attribute</a>: A kind of symbolic link.
38 <li><a accesskey="7" href="#Signals">Signals</a>: Signals known to pwmd.
39 <li><a accesskey="8" href="#Concept-Index">Concept Index</a>: Index of concepts.
40 </ul>
42 <!-- Node, Next, Previous, Up -->
43 <div class="node">
44 <a name="Introduction"></a>
45 <p><hr>
46 Next:&nbsp;<a rel="next" accesskey="n" href="#Invoking">Invoking</a>,
47 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
49 </div>
51 <h2 class="chapter">1 Overview of <samp><span class="command">pwmd</span></samp></h2>
53 <p><samp><span class="command">pwmd</span></samp> or <dfn>Password Manager Daemon</dfn> is a server that
54 applications connect to and send commands to store and retrieve data
55 that is saved in an encrypted <abbr>XML</abbr> document.
57 <p>The server uses the Assuan protocol (see <a href="assuan.html#Implementation">Implementation</a>) which
58 is the same used by <samp><span class="command">gpg-agent</span></samp>, <samp><span class="command">pinentry</span></samp> and
59 <samp><span class="command">scdaemon</span></samp>. It also uses <cite>libgpg-error</cite> for error reporting with
60 the error source set as <var>GPG_ERR_SOURCE_USER_1</var>.
62 <p>The <abbr>XML</abbr> document uses the following <abbr>DTD</abbr>:
64 <pre class="example"> &lt;?xml version="1.0"?&gt;
65 &lt;!DOCTYPE pwmd [
66 &lt;!ELEMENT pwmd (element*)&gt;
67 &lt;!ATTLIST element _name CDATA #REQUIRED&gt;
68 ]&gt;
69 </pre>
70 <p>The <code>pwmd</code> element is the document root node while all other elements
71 of the document have the name <code>element</code> with an attribute <code>_name</code>
72 whose value uniquely identifies the element at the current element tree depth.
73 It is done this way to avoid <abbr>XML</abbr> parsing errors for commonly used
74 characters. A <abbr>URL</abbr> for example would be an invalid <abbr>XML</abbr> element
75 since the <abbr>URI</abbr> contains a &lsquo;<samp><span class="samp">:</span></samp>&rsquo; which is also the <abbr>XML</abbr>
76 namespace separator.
78 <p>As mentioned, an element name must be unique for the current element tree
79 depth. You cannot have two elements containing the same <code>_name</code> attribute
80 value. <samp><span class="command">pwmd</span></samp> will stop searching for an element of an <em>element
81 path</em> at the first match then continue searching for the next element of the
82 element path beginning at the child node of the matched element.
84 <p>An <em>element path</em> is a &lt;TAB&gt; delimited character string where each
85 &lt;TAB&gt; separates each element in the path. For example, the element path
86 <code>a&lt;TAB&gt;b&lt;TAB&gt;c</code> has the following <abbr>XML</abbr> document structure:
88 <pre class="example"> &lt;pwmd&gt;
89 &lt;element _name="a"&gt;
90 &lt;element _name="b"&gt;
91 &lt;element _name="c"&gt;
92 [... element value or content ...]
93 &lt;/element&gt;
94 &lt;/element&gt;
95 &lt;/element&gt;
96 &lt;/pwmd&gt;
97 </pre>
98 <p>The only restriction of an element name is that it contain no whitespace
99 characters. It also cannot begin with a &lsquo;<samp><span class="samp">!</span></samp>&rsquo; since this character is
100 reserved for the <code>target</code> attribute. See <a href="#Target-Attribute">Target Attribute</a>.
102 <!-- Node, Next, Previous, Up -->
103 <div class="node">
104 <a name="Invoking"></a>
105 <p><hr>
106 Next:&nbsp;<a rel="next" accesskey="n" href="#Configuration">Configuration</a>,
107 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
108 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
110 </div>
112 <h2 class="chapter">2 Invoking <samp><span class="command">pwmd</span></samp></h2>
114 <p>When <samp><span class="command">pwmd</span></samp> is started with the <samp><span class="option">--use-agent</span></samp> command
115 line option then <samp><span class="command">pwmd</span></samp> will use <samp><span class="command">gpg-agent</span></samp> for key
116 generation, decryption, signing and caching of passphrases as the
117 default rather than symmetrically encrypted data files.
118 <samp><span class="command">gpg-agent</span></samp> must be running prior to <samp><span class="command">pwmd</span></samp> startup when
119 this option is enabled. The <samp><span class="env">GPG_AGENT_INFO</span></samp> environment variable is
120 set by <samp><span class="command">gpg-agent</span></samp> and <samp><span class="command">pwmd</span></samp> uses this variable to
121 determine where the <samp><span class="command">gpg-agent</span></samp> socket is listening for
122 connections.
124 <p>It is recommended to pass the <samp><span class="option">--allow-preset-passphrase</span></samp>
125 command line option to <samp><span class="command">gpg-agent</span></samp>. Doing so allows <samp><span class="command">pwmd</span></samp>
126 cache pushing on startup. It is also recommended to pass the
127 <samp><span class="option">--allow-loopback-pinentry</span></samp> to <samp><span class="command">gpg-agent</span></samp>. This option allows
128 a passphrase to be inquired from <samp><span class="command">pwmd</span></samp> when a <samp><span class="command">pinentry</span></samp> is
129 unavailable to the client.
131 <p><a name="index-Running-_0040command_007bpwmd_007d-1"></a><samp><span class="command">pwmd</span></samp> is executed as follows:
133 <pre class="example"> pwmd <var>options</var> [ file1 ] [ ... ]
134 </pre>
135 <p>Non-option arguments are data files to cache on startup. When the data file
136 requires a passphrase for decryption a <samp><span class="command">pinentry</span></samp> will prompt either
137 on the current <abbr>TTY</abbr> or from an X11 window when the <samp><span class="env">DISPLAY</span></samp>
138 environment variable is set.
140 <p><a name="index-Options-2"></a><a name="index-Arguments-3"></a>The following command line options are supported:
142 <p><a name="index-Getting-help-4"></a>
143 <dl>
144 <dt>&lsquo;<samp><span class="samp">--homedir directory</span></samp>&rsquo;<dd>The root directory where pwmd will store its data and temporary files. The
145 default is <samp><span class="file">~/.pwmd</span></samp>.
147 <br><dt>&lsquo;<samp><span class="samp">--rcfile, -f rcfile</span></samp>&rsquo;<dd>Specify an alternate configuration file. The default is
148 <samp><span class="file">~/.pwmd/config</span></samp>.
150 <br><dt>&lsquo;<samp><span class="samp">--use-agent</span></samp>&rsquo;<dd>Enable the use of <samp><span class="command">gpg-agent</span></samp> and add support for data files
151 encrypted with a keypair. Files previously handled by
152 <samp><span class="command">gpg-agent</span></samp> when this option is not specified will no longer be
153 able to be opened and new data files are symmetrically or conventionally
154 encrypted and without a public and private key. If
155 specified, both data file types are supported.
157 <br><dt>&lsquo;<samp><span class="samp">--import, -I filename</span></samp>&rsquo;<dd>Imports an <abbr>XML</abbr> file. The <abbr>XML</abbr> file should be in conformance to
158 the <samp><span class="command">pwmd</span></samp> <abbr>DTD</abbr> (see <a href="#Introduction">Introduction</a>). You
159 will be prompted for a passphrase to encrypt with. The output is written to
160 the filename specified with <samp><span class="option">--outfile</span></samp>. To make use of the imported
161 data, place the output file in <samp><span class="file">~/.pwmd/data</span></samp>.
163 <br><dt>&lsquo;<samp><span class="samp">--keyparam S-expression</span></samp>&rsquo;<dd>The key parameters to use when generating a new key pair while importing an
164 <abbr>XML</abbr> file or when converting a <em>version 2</em> data file. The argument
165 must be a valid S-expression (see <a href="gcrypt.html#S_002dexpressions">S-expressions</a>).
167 <br><dt>&lsquo;<samp><span class="samp">--keygrip hexstring</span></samp>&rsquo;<dd>Specifies the hexadecimal encoded public key-grip to use for encryption when
168 importing or converting. When not specified a new key-pair will be created.
170 <br><dt>&lsquo;<samp><span class="samp">--sign-keygrip hexstring</span></samp>&rsquo;<dd>Specifies the hexadecimal encoded public key-grip to use for signing of the
171 data file when importing or converting. When not specified the generated
172 public key or the key specified with the <samp><span class="option">--keygrip</span></samp> option will be
173 used.
175 <br><dt>&lsquo;<samp><span class="samp">--passphrase-file, -k filename"</span></samp>&rsquo;<dd>Obtain the passphrase from the specified filename.
177 <br><dt>&lsquo;<samp><span class="samp">--s2k-count iterations</span></samp>&rsquo;<dd>The number of times to hash the passphrase when importing or converting. The
178 default is the gpg-agent calibrated value of the machine. When less than
179 &lsquo;<samp><span class="samp">65536</span></samp>&rsquo; the default will be used.
181 <br><dt>&lsquo;<samp><span class="samp">--cipher-iterations iterations</span></samp>&rsquo;<dd>The number of symmetric encryption iterations. The value is actually N+1. The
182 default is 0+1.
184 <br><dt>&lsquo;<samp><span class="samp">--cipher algo</span></samp>&rsquo;<dd>When importing, the cipher to use for data encryption. See the <var>cipher</var>
185 configuration parameter (see <a href="#Configuration">Configuration</a>) for available ciphers. The
186 default is &lsquo;<samp><span class="samp">aes256</span></samp>&rsquo;.
188 <br><dt>&lsquo;<samp><span class="samp">--convert, -C filename</span></samp>&rsquo;<dd>Converts a <samp><span class="command">pwmd</span></samp> <em>version 2</em> data file to a <em>version 3</em>
189 data file. If encrypted, you will be prompted for a passphrase to use for
190 decryption unless <samp><span class="option">--passphrase-file</span></samp> was specified. The converted data
191 file will be saved to the filename specified with <samp><span class="option">--outfile</span></samp>. All
192 <samp><span class="option">--import</span></samp> related options may also be used when converting.
194 <br><dt>&lsquo;<samp><span class="samp">--disable-dump, -D</span></samp>&rsquo;<dd>Disable the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and <code>DUMP</code>
195 protocol commands (see <a href="#Commands">Commands</a>). This overrides any
196 <var>disable_list_and_dump</var> configuration parameter (see <a href="#Configuration">Configuration</a>).
198 <br><dt>&lsquo;<samp><span class="samp">--no-fork, -n</span></samp>&rsquo;<dd>Run as a foreground process and do not fork into the background.
200 <br><dt>&lsquo;<samp><span class="samp">--ignore</span></samp>&rsquo;<dd>Ignore cache pushing failures on startup. By default, <samp><span class="command">pwmd</span></samp> will exit
201 if an error occurred do to an invalid passphrase or other error.
203 <br><dt>&lsquo;<samp><span class="samp">--debug-level keyword,keyword,...</span></samp>&rsquo;<dd>Output libassuan see <a href="assuan.html#Top">Top</a> protocol IO with the comma
204 separated list of output keywords. Valid keywords are: <code>init</code>,
205 <code>ctx</code>, <code>engine</code>, <code>data</code>, <code>sysio</code> and <code>control</code>.
207 <br><dt>&lsquo;<samp><span class="samp">--version</span></samp>&rsquo;<dd>Show the version, copyright and compile time features and exit.
209 <br><dt>&lsquo;<samp><span class="samp">--help</span></samp>&rsquo;<dd>Print a summary of options.
210 </dl>
212 <!-- Node, Next, Previous, Up -->
213 <div class="node">
214 <a name="Configuration"></a>
215 <p><hr>
216 Next:&nbsp;<a rel="next" accesskey="n" href="#TLS">TLS</a>,
217 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Invoking">Invoking</a>,
218 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
220 </div>
222 <h2 class="chapter">3 <samp><span class="command">pwmd</span></samp> configuration file options</h2>
224 <p>If no configuration file is specified with the <samp><span class="command">pwmd</span></samp> <samp><span class="option">-f</span></samp>
225 command line option, <samp><span class="command">pwmd</span></samp> will read <samp><span class="file">~/.pwmd/config</span></samp> if it
226 exists, and if not, will use defaults. Blank lines and lines beginning with
227 &lsquo;<samp><span class="samp">#</span></samp>&rsquo; are ignored. Some parameters may have data file specific settings by
228 placing them in a file section. A file section is declared by surrounding the
229 filename with braces (i.e., &lsquo;<samp><span class="samp">[filename]</span></samp>&rsquo;). Global options may be
230 specified in a &lsquo;<samp><span class="samp">[global]</span></samp>&rsquo; section and are the default options for new or
231 unspecified files.
233 <p>A tilde &lt;~&gt; will be expanded to the home directory of the invoking user
234 when contained in a parameter whose value is a filename.
236 <p><a name="index-Reloading-the-configuration-file-5"></a>The configuration file can be reloaded by sending the <em>SIGHUP</em> signal to
237 a <samp><span class="command">pwmd</span></samp> process.
239 <p><a name="index-Global-configuration-options-6"></a>The following options are only for use in the &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section:
241 <dl>
242 <dt>&lsquo;<samp><span class="samp">socket_path = /path/to/socket</span></samp>&rsquo;<dd>Listen on the specified socket. The default is <samp><span class="file">~/.pwmd/socket</span></samp>.
244 <br><dt>&lsquo;<samp><span class="samp">socket_perms = octal_mode</span></samp>&rsquo;<dd>Permissions to set after creating the socket. This will override any
245 <cite>umask(2)</cite> setting.
247 <br><dt>&lsquo;<samp><span class="samp">allowed = user,@group,...</span></samp>&rsquo;<dd>A comma separated list of local user names or group names allowed to connect
248 to the socket. Groups should be prefixed with a &lsquo;<samp><span class="samp">@</span></samp>&rsquo;. When not specified
249 only the invoking user may connect.
251 <br><dt>&lsquo;<samp><span class="samp">disable_mlockall = boolean</span></samp>&rsquo;<dd>When set to <var>false</var>, <cite>mlockall(2)</cite> will be called on startup. This
252 will use more physical memory but may also be more secure since no swapping to
253 disk will occur. The default is <var>true</var>.
255 <br><dt>&lsquo;<samp><span class="samp">log_path = /path/to/logfile</span></samp>&rsquo;<dd>Logs informational messages to the specified file. The default is
256 <samp><span class="file">~/.pwmd/log</span></samp>.
258 <br><dt>&lsquo;<samp><span class="samp">enable_logging = boolean</span></samp>&rsquo;<dd>Enable or disable logging to <var>log_path</var>. The default is <code>false</code>.
260 <br><dt>&lsquo;<samp><span class="samp">syslog = boolean</span></samp>&rsquo;<dd>Enable logging to <cite>syslog(8)</cite> with facility <em>LOG_DAEMON</em> and priority
261 <em>LOG_INFO</em>. The default is <code>false</code>.
263 <br><dt>&lsquo;<samp><span class="samp">log_level = level</span></samp>&rsquo;<dd>When <code>0</code>, only connections and errors are logged. When <code>1</code>, client
264 commands are also logged. When <code>2</code>, the command arguments are also logged.
265 The default is <code>0</code>.
267 <br><dt>&lsquo;<samp><span class="samp">use_agent = boolean</span></samp>&rsquo;<dd>When true, enable <samp><span class="command">gpg-agent</span></samp> support (see <a href="#Invoking">Invoking</a>).
269 <br><dt>&lsquo;<samp><span class="samp">agent_env_file = filename</span></samp>&rsquo;<dd>A file containing the <samp><span class="env">GPG_AGENT_INFO</span></samp> environment variable and value as
270 output by the <samp><span class="command">gpg-agent</span></samp> <samp><span class="option">--write-env-file</span></samp> command line
271 option.
273 <br><dt>&lsquo;<samp><span class="samp">kill_scd = boolean</span></samp>&rsquo;<dd>Kill <samp><span class="command">scdaemon</span></samp> after each <code>OPEN</code> (see <a href="#OPEN">OPEN</a>) or <code>SAVE</code>
274 (see <a href="#SAVE">SAVE</a>) command.
276 <br><dt>&lsquo;<samp><span class="samp">require_save_key = boolean</span></samp>&rsquo;<dd>Require the passphrase needed to open a data file before writing changes
277 of the documment to disk reguardless of the key cache status.
279 <br><dt>&lsquo;<samp><span class="samp">disable_list_and_dump = boolean</span></samp>&rsquo;<dd>When <code>true</code>, the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and
280 <code>DUMP</code> protocol commands (see <a href="#Commands">Commands</a>) will be disabled.
282 <br><dt>&lsquo;<samp><span class="samp">cache_push = file1,file2</span></samp>&rsquo;<dd>A comma separated list of filenames that will be pushed into the file cache
283 upon startup. <samp><span class="command">pwmd</span></samp> will prompt for the passphrase for each file unless
284 specified with the <var>passphrase</var> or <var>passphrase_file</var> parameters in a
285 matching file section.
287 <br><dt>&lsquo;<samp><span class="samp">priority = integer</span></samp>&rsquo;<dd>The priority, or niceness, of the server. The default is inherited from the
288 parent process.
290 <br><dt>&lsquo;<samp><span class="samp">cipher = algorithm</span></samp>&rsquo;<dd>The default cipher to use for data encryption. The algorithm must be one of:
291 <code>aes128</code>, <code>aes192</code>, <code>aes256</code>, <code>serpent128</code>,
292 <code>serpent192</code>, <code>serpent256</code>, <code>camellia128</code>,
293 <code>camellia192</code>, <code>camellia256</code>, <code>3des</code>, <code>cast5</code>,
294 <code>blowfish</code>, <code>twofish128</code> or <code>twofish256</code>. The default is
295 <code>aes256</code>.
297 <br><dt>&lsquo;<samp><span class="samp">cipher_iterations = integer</span></samp>&rsquo;<dd>The number of times to encrypt the XML data. This differs from the
298 <var>s2k_count</var> parameter which specifies the number of times to hash the
299 passphrase used to encrypt the data. The default is 0 although 1 iteration is
300 still done.
302 <br><dt>&lsquo;<samp><span class="samp">cipher_progress = integer</span></samp>&rsquo;<dd>Send a progress message to the client after the specified amount of encryption
303 or decryption iterations have been done. The default is 2000.
305 <br><dt>&lsquo;<samp><span class="samp">keyparam = s-expression</span></samp>&rsquo;<dd>The default key paramaters to use when generating a new key-pair. The
306 default is RSA with 2048 bits. Note that only RSA as the encryption
307 algorithm is supported at the moment. Both RSA and DSA keys may be used
308 for signing.
310 <br><dt>&lsquo;<samp><span class="samp">pinentry_path = /path/to/pinentry</span></samp>&rsquo;<dd>The location of the <samp><span class="command">pinentry</span></samp> binary. This program is used to
311 prompt for a passphrase when not using <samp><span class="command">gpg-agent</span></samp>. The default
312 is specified at compile time.
314 <br><dt>&lsquo;<samp><span class="samp">pinentry_timeout = seconds</span></samp>&rsquo;<dd>The number of seconds to wait for a pinentry before giving up and
315 returning an error. This timeout value is used for both waiting for
316 another pinentry to complete and for the pinentry waiting for user input.
317 </dl>
319 <p><a name="index-Data-file-configuration-options-7"></a>The following options are defaults for new files when specified in the
320 &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section. When placed in a data file section they are options
321 specific to that data file only.
323 <dl>
324 <dt>&lsquo;<samp><span class="samp">backup = boolean</span></samp>&rsquo;<dd>Whether to create a backup of the data file when saving. The backup filename
325 has the <samp><span class="file">.backup</span></samp> extension appended to the opened file. The default is
326 <code>true</code>.
328 <br><dt>&lsquo;<samp><span class="samp">cache_timeout = seconds</span></samp>&rsquo;<dd>The number of seconds to keep the cache entry for this file. If <code>-1</code>, the
329 cache entry is kept forever. If <code>0</code>, each time an encrypted file is
330 <code>OPEN</code>ed (see <a href="#OPEN">OPEN</a>) a passphrase will be required. The default
331 is <code>-1</code>.
333 <br><dt>&lsquo;<samp><span class="samp">xfer_progress = bytes</span></samp>&rsquo;<dd>Commands that send data lines to the client will also send the <code>XFER</code>
334 status message (see <a href="#Status-Messages">Status Messages</a>) after the specified number of bytes
335 have been sent. The number of bytes is rounded to <var>ASSUAN_LINELENGTH</var> or
336 <code>1002</code> bytes. The default is <code>8196</code>.
338 <br><dt>&lsquo;<samp><span class="samp">passphrase = string</span></samp>&rsquo;<dd>The passphrase to use for this file. If specified in the &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section
339 then &lsquo;<samp><span class="samp">global</span></samp>&rsquo; is treated as a data filename and not a default for other
340 files. Note that if a client changes the passphrase for this data file then
341 this value is not modified and will need to be updated.
343 <br><dt>&lsquo;<samp><span class="samp">passphrase_file = /path/to/file</span></samp>&rsquo;<dd>Same as the <var>passphrase</var> parameter above but obtains the passphrase from
344 the specified filename.
346 <br><dt>&lsquo;<samp><span class="samp">recursion_depth = integer</span></samp>&rsquo;<dd>The maximum number of times to resolve a <code>target</code> attribute for an
347 element in an element path (see <a href="#Target-Attribute">Target Attribute</a>). An error is returned
348 when this value is exceeded. The default is <code>100</code> but can be disabled by
349 setting to <code>0</code> (<em>not recommended</em>).
351 </dl>
353 <ul class="menu">
354 <li><a accesskey="1" href="#TLS">TLS</a>: Remote connections over TLS.
355 <li><a accesskey="2" href="#Pinentry">Pinentry</a>: Configuration file and defaults.
356 </ul>
358 <div class="node">
359 <a name="TLS"></a>
360 <p><hr>
361 Next:&nbsp;<a rel="next" accesskey="n" href="#Pinentry">Pinentry</a>,
362 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Configuration">Configuration</a>,
363 Up:&nbsp;<a rel="up" accesskey="u" href="#Configuration">Configuration</a>
365 </div>
367 <h2 class="chapter">4 Configuring remote connections over TLS.</h2>
369 <p>Remote connections can also be made to <samp><span class="command">pwmd</span></samp> over <abbr>TLS</abbr>.
370 Authentication is done by using X509 client certificates that are signed with
371 the same Certificate Authority (<abbr>CA</abbr>) as the server certificate.
373 <p>The <abbr>CA</abbr> certificate is expected to be found in
374 <samp><span class="file">~/.pwmd/ca-cert.pem</span></samp> while the <samp><span class="command">pwmd</span></samp> server certificate and key
375 file should be put in <samp><span class="file">~/.pwmd/server-cert.pem</span></samp> and
376 <samp><span class="file">~/.pwmd/server-key.pem</span></samp>, respectively.
378 <p>See the documentation of <samp><span class="command">certtool</span></samp> or <samp><span class="command">openssl</span></samp> for details
379 on creating self-signed certificates.
381 <p>The following TLS configuration options are available:
383 <dl>
384 <dt>&lsquo;<samp><span class="samp">enable_tcp = boolean</span></samp>&rsquo;<dd>Whether to enable TCP/TLS server support. If enabled, both TCP and the local
385 unix domain socket will listen for connections. The default is
386 <code>false</code>.
388 <br><dt>&lsquo;<samp><span class="samp">tcp_port = integer</span></samp>&rsquo;<dd>The TCP port to listen on when <var>enable_tcp</var> is <code>true</code>. The default is
389 <code>6466</code>.
391 <br><dt>&lsquo;<samp><span class="samp">tcp_bind = string</span></samp>&rsquo;<dd>The internet protocol to listen with. Must be one of <code>ipv4</code>, <code>ipv6</code>
392 or <code>any</code> to listen for both IPv4 and IPv6 connections.
394 <br><dt>&lsquo;<samp><span class="samp">tcp_interface = string</span></samp>&rsquo;<dd>Only useful if running as root.
396 <br><dt>&lsquo;<samp><span class="samp">tls_timeout = seconds</span></samp>&rsquo;<dd>The number of seconds to wait for a read() or write() call on a
397 <abbr>TLS</abbr> client file descriptor to complete before returning an
398 error. The default is <var>300</var>.
400 <p>Note that the <code>SAVE</code> command (see <a href="#SAVE">SAVE</a>) may take a longer time
401 to complete than other commands since key generation may need to be done
402 or do to a large <samp><span class="option">--cipher-iterations</span></samp> setting.
404 <br><dt>&lsquo;<samp><span class="samp">keepalive_interval = seconds</span></samp>&rsquo;<dd>Send a keepalive status message to an idle remote client. An idle
405 client is one who is not in a command. The purpose of this status
406 message is to disconnect a hung remote client and release any file mutex
407 locks so another client may open the same data file.
409 <br><dt>&lsquo;<samp><span class="samp">tls_access = string[,string,...]</span></samp>&rsquo;<dd>A comma separated list of client X509 certificate fingerprints in SHA-1
410 format that will be allowed to connect or open a file. If prefixed with
411 <code>!</code> then access is denied for the fingerprint. When <code>!</code> is
412 found by itself in the list it is treated as a default for remaining
413 fingerprints in the list. The <code>+</code> prefix behaves the same but
414 allows access.
416 <p>The access control is two fold: when the client connects its SHA-1
417 fingerprint is matched against the list of allowed fingerprints in the
418 &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section. When allowed in the &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section the
419 connection is established and the client may proceed to <code>OPEN</code>
420 (see <a href="#OPEN">OPEN</a>) a data file. During the <code>OPEN</code> command the
421 fingerprint is checked again in a &lsquo;<samp><span class="samp">filename</span></samp>&rsquo; section. When this
422 parameter is not found in a &lsquo;<samp><span class="samp">filename</span></samp>&rsquo; section then access is granted.
424 <br><dt>&lsquo;<samp><span class="samp">tcp_require_key = boolean</span></samp>&rsquo;<dd>When <code>true</code>, require the remote client to provide the key or passphrase
425 to open a data file even if the file is cached. Note that the cache entry is
426 cleared during the see <a href="#OPEN">OPEN</a> command and the passphrase will be retrieved
427 from the client via a server <em>INQUIRE</em>. This option is a default
428 for all files when specified in the &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section. The default
429 is <code>false</code>.
431 <br><dt>&lsquo;<samp><span class="samp">tcp_wait = integer</span></samp>&rsquo;<dd>The time in tenths of a second to wait between TCP connections. Setting to 0
432 will disable waiting. The default is <code>3</code>.
434 <br><dt>&lsquo;<samp><span class="samp">tls_cipher_suite = string</span></samp>&rsquo;<dd>The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
435 information about the format of this string. The default is <code>SECURE256</code>.
436 </dl>
438 <div class="node">
439 <a name="Pinentry"></a>
440 <p><hr>
441 Next:&nbsp;<a rel="next" accesskey="n" href="#Commands">Commands</a>,
442 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TLS">TLS</a>,
443 Up:&nbsp;<a rel="up" accesskey="u" href="#Configuration">Configuration</a>
445 </div>
447 <h2 class="chapter">5 Pinentry configuration</h2>
449 <p>The <samp><span class="command">pinentry</span></samp> program is used to prompt the user for passphrase
450 input or as a confirmation dialog; it needs to know where to prompt for
451 the input, beit from a terminal or an X11 display.
453 <p>It is the responsibility of the client to tell <samp><span class="command">pinentry</span></samp> about
454 the terminal or X11 display before requiring the input. This is done by
455 using the <samp><span class="command">pwmd</span></samp> see <a href="#OPTION">OPTION</a> protocol command. It need be
456 done only once per client connection. To avoid the use of
457 <samp><span class="command">pinentry</span></samp> entirely, use the <code>OPTION</code> (see <a href="#OPTION">OPTION</a>)
458 <samp><span class="option">--disable-pinentry</span></samp> protocol command.
460 <!-- Node, Next, Previous, Up -->
461 <div class="node">
462 <a name="Commands"></a>
463 <p><hr>
464 Next:&nbsp;<a rel="next" accesskey="n" href="#Status-Messages">Status Messages</a>,
465 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Pinentry">Pinentry</a>,
466 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
468 </div>
470 <h2 class="chapter">6 Protocol commands and their syntax</h2>
472 <ul class="menu">
473 <li><a accesskey="1" href="#AGENT">AGENT</a>
474 <li><a accesskey="2" href="#ATTR">ATTR</a>
475 <li><a accesskey="3" href="#CACHETIMEOUT">CACHETIMEOUT</a>
476 <li><a accesskey="4" href="#CLEARCACHE">CLEARCACHE</a>
477 <li><a accesskey="5" href="#COPY">COPY</a>
478 <li><a accesskey="6" href="#DELETE">DELETE</a>
479 <li><a accesskey="7" href="#DUMP">DUMP</a>
480 <li><a accesskey="8" href="#GET">GET</a>
481 <li><a accesskey="9" href="#GETCONFIG">GETCONFIG</a>
482 <li><a href="#GETINFO">GETINFO</a>
483 <li><a href="#HELP">HELP</a>
484 <li><a href="#IMPORT">IMPORT</a>
485 <li><a href="#ISCACHED">ISCACHED</a>
486 <li><a href="#KEYGRIP">KEYGRIP</a>
487 <li><a href="#LIST">LIST</a>
488 <li><a href="#LOCK">LOCK</a>
489 <li><a href="#LS">LS</a>
490 <li><a href="#MOVE">MOVE</a>
491 <li><a href="#NOP">NOP</a>
492 <li><a href="#OPEN">OPEN</a>
493 <li><a href="#OPTION">OPTION</a>
494 <li><a href="#PASSWD">PASSWD</a>
495 <li><a href="#REALPATH">REALPATH</a>
496 <li><a href="#RENAME">RENAME</a>
497 <li><a href="#RESET">RESET</a>
498 <li><a href="#SAVE">SAVE</a>
499 <li><a href="#STORE">STORE</a>
500 <li><a href="#UNLOCK">UNLOCK</a>
501 <li><a href="#XPATH">XPATH</a>
502 <li><a href="#XPATHATTR">XPATHATTR</a>
503 </ul>
504 <div class="node">
505 <a name="AGENT"></a>
506 <p><hr>
507 Next:&nbsp;<a rel="next" accesskey="n" href="#ATTR">ATTR</a>,
508 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
510 </div>
512 <h2 class="chapter">7 AGENT command</h2>
514 <p><a name="index-AGENT-command-8"></a>Syntax:
515 <pre class="example"> AGENT &lt;command&gt;
516 </pre>
517 <p>Send a <samp><span class="command">gpg-agent</span></samp> protocol <var>command</var> directly to the
518 <samp><span class="command">gpg-agent</span></samp>.
520 <div class="node">
521 <a name="ATTR"></a>
522 <p><hr>
523 Next:&nbsp;<a rel="next" accesskey="n" href="#CACHETIMEOUT">CACHETIMEOUT</a>,
524 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AGENT">AGENT</a>,
525 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
527 </div>
529 <h2 class="chapter">8 ATTR command</h2>
531 <p><a name="index-ATTR-command-9"></a>Syntax:
532 <pre class="example"> ATTR [--inquire] SET|GET|DELETE|LIST [&lt;attribute&gt;] [!]element[&lt;TAB&gt;[!]child[..]] ..
533 </pre>
534 <dl>
535 <dt>ATTR SET attribute [!]element[&lt;TAB&gt;[!]child[..]] [value]<dd>
536 Stores or updates an <var>attribute</var> name and optional <var>value</var> of an
537 element. When no <var>value</var> is specified any existing value will be removed.
539 <br><dt>ATTR DELETE attribute [!]element[&lt;TAB&gt;[!]child[..]]<dd>
540 Removes an <var>attribute</var> from an element.
542 <br><dt>ATTR LIST [!]element[&lt;TAB&gt;[!]child[..]]<dd>
543 Retrieves a newline separated list of attributes names and values
544 from the specified element. Each attribute name and value is space delimited.
546 <br><dt>ATTR GET attribute [!]element[&lt;TAB&gt;[!]child[..]]<dd>
547 Retrieves the value of an <var>attribute</var> from an element.
548 </dl>
550 <p>The <code>_name</code> attribute (case sensitive) cannot be removed nor modified.
551 Use the <code>DELETE</code> (see <a href="#DELETE">DELETE</a>) or <code>RENAME</code> (see <a href="#RENAME">RENAME</a>)
552 commands instead.
554 <p>The <code>_mtime</code> attribute is updated each time an element is modified by
555 either storing content, editing attributes or by deleting a child element.
556 The <code>_ctime</code> attribute is created for each new element in an element
557 path.
559 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
560 arguments are retrieved via a server <em>INQUIRE</em>.
562 <p>See <a href="#Target-Attribute">Target Attribute</a>, for details about this special attribute.
564 <div class="node">
565 <a name="CACHETIMEOUT"></a>
566 <p><hr>
567 Next:&nbsp;<a rel="next" accesskey="n" href="#CLEARCACHE">CLEARCACHE</a>,
568 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ATTR">ATTR</a>,
569 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
571 </div>
573 <h2 class="chapter">9 CACHETIMEOUT command</h2>
575 <p><a name="index-CACHETIMEOUT-command-10"></a>Syntax:
576 <pre class="example"> CACHETIMEOUT &lt;filename&gt; &lt;seconds&gt;
577 </pre>
578 <p>The time in <var>seconds</var> until <var>filename</var> will be removed from the
579 cache. <code>-1</code> will keep the cache entry forever, <code>0</code> will require
580 the passphrase for each <code>OPEN</code> or <code>SAVE</code> command (see <a href="#OPEN">OPEN</a>,
581 see <a href="#SAVE">SAVE</a>). See <a href="#Configuration">Configuration</a>, and the <code>cache_timeout</code>
582 parameter.
584 <div class="node">
585 <a name="CLEARCACHE"></a>
586 <p><hr>
587 Next:&nbsp;<a rel="next" accesskey="n" href="#COPY">COPY</a>,
588 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CACHETIMEOUT">CACHETIMEOUT</a>,
589 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
591 </div>
593 <h2 class="chapter">10 CLEARCACHE command</h2>
595 <p><a name="index-CLEARCACHE-command-11"></a>Syntax:
596 <pre class="example"> CLEARCACHE [&lt;filename&gt;]
597 </pre>
598 <p>Clears a file cache entry for all or the specified <var>filename</var>.
600 <div class="node">
601 <a name="COPY"></a>
602 <p><hr>
603 Next:&nbsp;<a rel="next" accesskey="n" href="#DELETE">DELETE</a>,
604 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CLEARCACHE">CLEARCACHE</a>,
605 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
607 </div>
609 <h2 class="chapter">11 COPY command</h2>
611 <p><a name="index-COPY-command-12"></a>Syntax:
612 <pre class="example"> COPY [--inquire] [!]source[&lt;TAB&gt;[!]child[..]] [!]dest[&lt;TAB&gt;[!]child[..]]
613 </pre>
614 <p>Copies the entire element tree starting from the child node of the source
615 element, to the destination element path. If the destination element path
616 does not exist then it will be created; otherwise it is overwritten.
618 <p>Note that attributes from the source element are merged into the
619 destination element when the destination element path exists. When an
620 attribute of the same name exists in both the source and destination
621 elements then the destination attribute will be updated to the source
622 attribute value.
624 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
625 arguments are retrieved via a server <em>INQUIRE</em>.
627 <div class="node">
628 <a name="DELETE"></a>
629 <p><hr>
630 Next:&nbsp;<a rel="next" accesskey="n" href="#DUMP">DUMP</a>,
631 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COPY">COPY</a>,
632 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
634 </div>
636 <h2 class="chapter">12 DELETE command</h2>
638 <p><a name="index-DELETE-command-13"></a>Syntax:
639 <pre class="example"> DELETE [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
640 </pre>
641 <p>Removes the specified element path and all of its children. This may break
642 an element with a <code>target</code> attribute (see <a href="#Target-Attribute">Target Attribute</a>) that
643 refers to this element or any of its children.
645 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
646 arguments are retrieved via a server <em>INQUIRE</em>.
648 <div class="node">
649 <a name="DUMP"></a>
650 <p><hr>
651 Next:&nbsp;<a rel="next" accesskey="n" href="#GET">GET</a>,
652 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DELETE">DELETE</a>,
653 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
655 </div>
657 <h2 class="chapter">13 DUMP command</h2>
659 <p><a name="index-DUMP-command-14"></a>Syntax:
660 <pre class="example"> DUMP
661 </pre>
662 <p>Shows the in memory <abbr>XML</abbr> document with indenting. See <a href="#XPATH">XPATH</a>, for
663 dumping a specific node.
665 <div class="node">
666 <a name="GET"></a>
667 <p><hr>
668 Next:&nbsp;<a rel="next" accesskey="n" href="#GETCONFIG">GETCONFIG</a>,
669 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DUMP">DUMP</a>,
670 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
672 </div>
674 <h2 class="chapter">14 GET command</h2>
676 <p><a name="index-GET-command-15"></a>Syntax:
677 <pre class="example"> GET [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
678 </pre>
679 <p>Retrieves the content of the specified element. The content is returned
680 with a data response.
682 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
683 arguments are retrieved via a server <em>INQUIRE</em>.
685 <div class="node">
686 <a name="GETCONFIG"></a>
687 <p><hr>
688 Next:&nbsp;<a rel="next" accesskey="n" href="#GETINFO">GETINFO</a>,
689 Previous:&nbsp;<a rel="previous" accesskey="p" href="#GET">GET</a>,
690 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
692 </div>
694 <h2 class="chapter">15 GETCONFIG command</h2>
696 <p><a name="index-GETCONFIG-command-16"></a>Syntax:
697 <pre class="example"> GETCONFIG [filename] &lt;parameter&gt;
698 </pre>
699 <p>Returns the value of a <samp><span class="command">pwmd</span></samp> configuration <var>parameter</var> with a
700 data response. If no file has been opened then the value for <var>filename</var>
701 or the default from the &lsquo;<samp><span class="samp">global</span></samp>&rsquo; section will be returned. If a file
702 has been opened and no <var>filename</var> is specified, a value previously
703 set with the <code>OPTION</code> command (see <a href="#OPTION">OPTION</a>) will be returned.
705 <div class="node">
706 <a name="GETINFO"></a>
707 <p><hr>
708 Next:&nbsp;<a rel="next" accesskey="n" href="#HELP">HELP</a>,
709 Previous:&nbsp;<a rel="previous" accesskey="p" href="#GETCONFIG">GETCONFIG</a>,
710 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
712 </div>
714 <h2 class="chapter">16 GETINFO command</h2>
716 <p><a name="index-GETINFO-command-17"></a>Syntax:
717 <pre class="example"> GETINFO [--data] CACHE | CLIENTS | PID | LAST_ERROR | VERSION
718 </pre>
719 <p>Get server and other information: <var>cache</var> returns the number of cached
720 documents via a status message. <var>clients</var> returns the number of
721 connected clients via a status message. <var>pid</var> returns the process ID
722 number of the server via a data response. <var>VERSION</var> returns the server
723 version number and compile-time features with a data response with each
724 being space delimited. <var>LAST_ERROR</var> returns a detailed description of
725 the last failed command when available. See <a href="#Status-Messages">Status Messages</a>.
727 <p>When the <samp><span class="option">--data</span></samp> option is specified then the result will be sent
728 via a data response rather than a status message.
730 <div class="node">
731 <a name="HELP"></a>
732 <p><hr>
733 Next:&nbsp;<a rel="next" accesskey="n" href="#IMPORT">IMPORT</a>,
734 Previous:&nbsp;<a rel="previous" accesskey="p" href="#GETINFO">GETINFO</a>,
735 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
737 </div>
739 <h2 class="chapter">17 HELP command</h2>
741 <p><a name="index-HELP-command-18"></a>Syntax:
742 <pre class="example"> HELP [&lt;COMMAND&gt;]
743 </pre>
744 <p>Show available commands or command specific help text.
746 <div class="node">
747 <a name="IMPORT"></a>
748 <p><hr>
749 Next:&nbsp;<a rel="next" accesskey="n" href="#ISCACHED">ISCACHED</a>,
750 Previous:&nbsp;<a rel="previous" accesskey="p" href="#HELP">HELP</a>,
751 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
753 </div>
755 <h2 class="chapter">18 IMPORT command</h2>
757 <p><a name="index-IMPORT-command-19"></a>Syntax:
758 <pre class="example"> IMPORT [--root [!]element[&lt;TAB&gt;[!]child[..]]] &lt;content&gt;
759 </pre>
760 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
762 <p>Like the <code>STORE</code> command (see <a href="#STORE">STORE</a>), but the <var>content</var>
763 argument is raw <abbr>XML</abbr> data. The content is created as a child of
764 the element path specified with the <samp><span class="option">--root</span></samp> option or at the
765 document root when not specified. Existing elements of the same name will
766 be overwritten.
768 <p>The content must begin with an <abbr>XML</abbr> element node. See <a href="#Introduction">Introduction</a>,
769 for details.
771 <div class="node">
772 <a name="ISCACHED"></a>
773 <p><hr>
774 Next:&nbsp;<a rel="next" accesskey="n" href="#KEYGRIP">KEYGRIP</a>,
775 Previous:&nbsp;<a rel="previous" accesskey="p" href="#IMPORT">IMPORT</a>,
776 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
778 </div>
780 <h2 class="chapter">19 ISCACHED command</h2>
782 <p><a name="index-ISCACHED-command-20"></a>Syntax:
783 <pre class="example"> ISCACHED [--lock] &lt;filename&gt;
784 </pre>
785 <p>An <em>OK</em> response is returned if the specified <var>filename</var> is found
786 in the file cache. If not found in the cache but exists on the filesystem
787 then <var>GPG_ERR_NO_DATA</var> is returned. Otherwise a filesystem error is
788 returned.
790 <p>The <samp><span class="option">lock</span></samp> option will lock the file mutex of <var>filename</var> when the
791 file exists; it does not need to be opened nor cached.
793 <div class="node">
794 <a name="KEYGRIP"></a>
795 <p><hr>
796 Next:&nbsp;<a rel="next" accesskey="n" href="#LIST">LIST</a>,
797 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ISCACHED">ISCACHED</a>,
798 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
800 </div>
802 <h2 class="chapter">20 KEYGRIP command</h2>
804 <p><a name="index-KEYGRIP-command-21"></a>Syntax:
805 <pre class="example"> KEYGRIP [--sign] &lt;filename&gt;
806 </pre>
807 <p>Returns the hex encoded keygrip of the specified <var>filename</var> with a
808 data response.
810 <p>When the <samp><span class="option">--sign</span></samp> option is specified then the key used for signing
811 of the specified <var>filename</var> will be returned.
813 <p>For symmetrically encrypted data files this command returns the error
814 GPG_ERR_NOT_SUPPORTED.
816 <div class="node">
817 <a name="LIST"></a>
818 <p><hr>
819 Next:&nbsp;<a rel="next" accesskey="n" href="#LOCK">LOCK</a>,
820 Previous:&nbsp;<a rel="previous" accesskey="p" href="#KEYGRIP">KEYGRIP</a>,
821 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
823 </div>
825 <h2 class="chapter">21 LIST command</h2>
827 <p><a name="index-LIST-command-22"></a>Syntax:
828 <pre class="example"> LIST [--inquire] [--no-recurse] [--verbose] [--with-target] [--all] [[!]element[&lt;TAB&gt;[!]child[..]]]
829 </pre>
830 <p>If no element path is given then a newline separated list of root elements
831 is returned with a data response. If given, then all reachable elements
832 of the specified element path are returned unless the <samp><span class="option">--no-recurse</span></samp>
833 option is specified. If specified, only the child elements of the element
834 path are returned without recursing into grandchildren. Each resulting
835 element is prefixed with the literal <code>!</code> character when the element
836 contains no <code>target</code> attribute. See <a href="#Target-Attribute">Target Attribute</a>, for details.
838 <p>When the <samp><span class="option">--verbose</span></samp> option is passed then each element path
839 returned will have zero or more flags appened to it. These flags are
840 delimited from the element path by a single space character. A flag itself
841 is a single character. Flag <code>+</code> indicates that there are child nodes of
842 the current element path. Flag <code>E</code> indicates that an element of an
843 element path contained in a <var>target</var> attribute could not be found. Flag
844 <code>O</code> indicates that a <var>target</var> attribute recursion limit was reached
845 (see <a href="#Configuration">Configuration</a>). Flag <code>T</code> will append the resolved element path
846 of the <var>target</var> attribute contained in the current element (see below).
848 <p>The <samp><span class="option">--with-target</span></samp> option implies <samp><span class="option">--verbose</span></samp> and will append
849 an additional flag <code>T</code> followed by a single space then an element path.
850 The appended element path is the resolved path (see <a href="#REALPATH">REALPATH</a>) of the
851 current element when it contains a <var>target</var> attribute. When no
852 <var>target</var> attribute is found then no flag will be appended.
854 <p>The <samp><span class="option">--no-recurse</span></samp> option limits the amount of data returned to only
855 the listing of children of the specified element path and not any
856 grandchildren.
858 <p>The <samp><span class="option">--all</span></samp> option lists the entire element tree for each root
859 element. This option also implies option <samp><span class="option">--verbose</span></samp>.
861 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
862 arguments are retrieved via a server <em>INQUIRE</em>.
864 <div class="node">
865 <a name="LOCK"></a>
866 <p><hr>
867 Next:&nbsp;<a rel="next" accesskey="n" href="#LS">LS</a>,
868 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LIST">LIST</a>,
869 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
871 </div>
873 <h2 class="chapter">22 LOCK command</h2>
875 <p><a name="index-LOCK-command-23"></a>Syntax:
876 <pre class="example"> LOCK
877 </pre>
878 <p>Locks the mutex associated with the opened file. This prevents other clients
879 from sending commands to the same opened file until the client
880 that sent this command either disconnects or sends the <code>UNLOCK</code>
881 command. See <a href="#UNLOCK">UNLOCK</a>.
883 <div class="node">
884 <a name="LS"></a>
885 <p><hr>
886 Next:&nbsp;<a rel="next" accesskey="n" href="#MOVE">MOVE</a>,
887 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOCK">LOCK</a>,
888 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
890 </div>
892 <h2 class="chapter">23 LS command</h2>
894 <p><a name="index-LS-command-24"></a>Syntax:
895 <pre class="example"> LS
896 </pre>
897 <p>Lists the available data files stored in the data directory
898 (<samp><span class="file">~/.pwmd/data</span></samp>). The result is a newline separated list of filenames.
900 <div class="node">
901 <a name="MOVE"></a>
902 <p><hr>
903 Next:&nbsp;<a rel="next" accesskey="n" href="#NOP">NOP</a>,
904 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LS">LS</a>,
905 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
907 </div>
909 <h2 class="chapter">24 MOVE command</h2>
911 <p><a name="index-MOVE-command-25"></a>Syntax:
912 <pre class="example"> MOVE [--inquire] [!]source[&lt;TAB&gt;[!]child[..]] [[!]dest[&lt;TAB&gt;[!]child[..]]]
913 </pre>
914 <p>Moves the source element path to the destination element path. If the
915 destination is not specified then it will be moved to the root node of the
916 document. If the destination is specified and exists then it will be
917 overwritten; otherwise non-existing elements of the destination element
918 path will be created.
920 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
921 arguments are retrieved via a server <em>INQUIRE</em>.
923 <div class="node">
924 <a name="NOP"></a>
925 <p><hr>
926 Next:&nbsp;<a rel="next" accesskey="n" href="#OPEN">OPEN</a>,
927 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MOVE">MOVE</a>,
928 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
930 </div>
932 <h2 class="chapter">25 NOP command</h2>
934 <p><a name="index-NOP-command-26"></a>Syntax:
935 <pre class="example"> NOP
936 </pre>
937 <p>Does nothing. Always returns successfully.
939 <div class="node">
940 <a name="OPEN"></a>
941 <p><hr>
942 Next:&nbsp;<a rel="next" accesskey="n" href="#OPTION">OPTION</a>,
943 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NOP">NOP</a>,
944 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
946 </div>
948 <h2 class="chapter">26 OPEN command</h2>
950 <p><a name="index-OPEN-command-27"></a>Syntax:
951 <pre class="example"> OPEN [--lock] &lt;filename&gt; [&lt;passphrase&gt;]
952 </pre>
953 <p>Opens <var>filename</var> using <var>passphrase</var>. When the filename is not
954 found on the file-system then a new document will be created. If the file
955 is found, it is looked for in the file cache. If cached and no
956 <var>passphrase</var> was specified then the cached document is opened. When not
957 cached, <cite>pinentry(1)</cite> will be used to retrieve the passphrase to use
958 for decryption unless <samp><span class="option">disable-pinentry</span></samp> (see <a href="#OPTION">OPTION</a>) was
959 specified.
961 <p>When the <samp><span class="option">--lock</span></samp> option is passed then the file mutex will be
962 locked as if the <code>LOCK</code> command (see <a href="#LOCK">LOCK</a>) had been sent after the
963 file has been opened.
965 <div class="node">
966 <a name="OPTION"></a>
967 <p><hr>
968 Next:&nbsp;<a rel="next" accesskey="n" href="#PASSWD">PASSWD</a>,
969 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OPEN">OPEN</a>,
970 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
972 </div>
974 <h2 class="chapter">27 OPTION command</h2>
976 <p><a name="index-OPTION-command-28"></a>Syntax:
977 <pre class="example"> OPTION &lt;NAME&gt;=&lt;VALUE&gt;
978 </pre>
979 <p>Sets a client option <var>name</var> to <var>value</var>. The value for an option is
980 kept for the duration of the connection.
982 <dl>
983 <dt>DISABLE-PINENTRY<dd>Disable use of <samp><span class="command">pinentry</span></samp> for passphrase retrieval. When set, a
984 server inquire is sent to the client to obtain the passphrase. This option
985 may be set as needed before the see <a href="#OPEN">OPEN</a>, see <a href="#PASSWD">PASSWD</a>, and
986 see <a href="#SAVE">SAVE</a> commands.
988 <br><dt>PINENTRY-TIMEOUT<dd>Sets the number of seconds before a pinentry prompt will return an error
989 while waiting for user input.
991 <br><dt>TTYNAME<dd>Passed to the <samp><span class="command">gpg-agent</span></samp> and used for the <samp><span class="command">pinentry</span></samp> dialog.
993 <br><dt>TTYTYPE<dd>Passed to the <samp><span class="command">gpg-agent</span></samp> and used for the <samp><span class="command">pinentry</span></samp> dialog.
995 <br><dt>DISPLAY<dd>Passed to the <samp><span class="command">gpg-agent</span></samp> and used for the <samp><span class="command">pinentry</span></samp> dialog.
997 <br><dt>PINENTRY-DESC<dd>Sets the description string of the <samp><span class="command">gpg-agent</span></samp> and <samp><span class="command">pinentry</span></samp> dialog.
999 <br><dt>PINENTRY-TITLE<dd>Sets the title string of the <samp><span class="command">gpg-agent</span></samp> and <samp><span class="command">pinentry</span></samp> dialog.
1001 <br><dt>PINENTRY-PROMPT<dd>Sets the prompt string of the <samp><span class="command">gpg-agent</span></samp> and <samp><span class="command">pinentry</span></samp> dialog.
1003 <br><dt>LC-CTYPE<dd>Passed to the <samp><span class="command">gpg-agent</span></samp> and used for the <samp><span class="command">pinentry</span></samp> dialog.
1005 <br><dt>LC-MESSAGES<dd>Passed to the <samp><span class="command">gpg-agent</span></samp> and used for the <samp><span class="command">pinentry</span></samp> dialog.
1007 <br><dt>NAME<dd>Associates the thread ID of the connection with the specified textual
1008 representation. Useful for debugging log messages.
1010 <br><dt>LOCK-TIMEOUT<dd>When not <code>0</code>, the duration in tenths of a second to wait for the file
1011 mutex which has been locked by another thread to be released before returning
1012 an error. When <code>-1</code>, then an error will be returned immediately.
1014 <br><dt>LOG-LEVEL<dd>An integer specifiying the logging level.
1015 </dl>
1017 <div class="node">
1018 <a name="PASSWD"></a>
1019 <p><hr>
1020 Next:&nbsp;<a rel="next" accesskey="n" href="#REALPATH">REALPATH</a>,
1021 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OPTION">OPTION</a>,
1022 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1024 </div>
1026 <h2 class="chapter">28 PASSWD command</h2>
1028 <p><a name="index-PASSWD-command-29"></a>Syntax:
1029 <pre class="example"> PASSWD [--reset] [--s2k-count=N]
1030 </pre>
1031 <p>Changes the passphrase of the secret key required to open the current
1032 file or the passphrase of a symmetrically encrypted data file. When the
1033 <samp><span class="option">--reset</span></samp> option is passed then the cache entry for the current
1034 file will be reset and the passphrase, if any, will be required during the
1035 next <code>OPEN</code>. See <a href="#OPEN">OPEN</a>.
1037 <p>The <samp><span class="option">--s2k-count</span></samp> option sets number of hash iterations for a
1038 passphrase and must be either <code>0</code> to use the calibrated count of the
1039 machine (the default), or a value greater than or equal to <code>65536</code>.
1040 See <a href="#SAVE">SAVE</a>. This option has no effect for symmetrically encrypted data
1041 files.
1043 <div class="node">
1044 <a name="REALPATH"></a>
1045 <p><hr>
1046 Next:&nbsp;<a rel="next" accesskey="n" href="#RENAME">RENAME</a>,
1047 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PASSWD">PASSWD</a>,
1048 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1050 </div>
1052 <h2 class="chapter">29 REALPATH command</h2>
1054 <p><a name="index-REALPATH-command-30"></a>Syntax:
1055 <pre class="example"> REALPATH [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
1056 </pre>
1057 <p>Resolves all <code>target</code> attributes of the specified element path and
1058 returns the result with a data response. See <a href="#Target-Attribute">Target Attribute</a>, for details.
1060 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
1061 arguments are retrieved via a server <em>INQUIRE</em>.
1063 <div class="node">
1064 <a name="RENAME"></a>
1065 <p><hr>
1066 Next:&nbsp;<a rel="next" accesskey="n" href="#RESET">RESET</a>,
1067 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REALPATH">REALPATH</a>,
1068 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1070 </div>
1072 <h2 class="chapter">30 RENAME command</h2>
1074 <p><a name="index-RENAME-command-31"></a>Syntax:
1075 <pre class="example"> RENAME [--inquire] [!]element[&lt;TAB&gt;[!]child[..]] &lt;value&gt;
1076 </pre>
1077 <p>Renames the specified <var>element</var> to the new <var>value</var>. If an element of
1078 the same name as the <var>value</var> already exists it will be overwritten.
1080 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
1081 arguments are retrieved via a server <em>INQUIRE</em>.
1083 <div class="node">
1084 <a name="RESET"></a>
1085 <p><hr>
1086 Next:&nbsp;<a rel="next" accesskey="n" href="#SAVE">SAVE</a>,
1087 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RENAME">RENAME</a>,
1088 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1090 </div>
1092 <h2 class="chapter">31 RESET command</h2>
1094 <p><a name="index-RESET-command-32"></a>Syntax:
1095 <pre class="example"> RESET
1096 </pre>
1097 <p>Closes the currently opened file but keeps any previously set client options.
1099 <div class="node">
1100 <a name="SAVE"></a>
1101 <p><hr>
1102 Next:&nbsp;<a rel="next" accesskey="n" href="#STORE">STORE</a>,
1103 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RESET">RESET</a>,
1104 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1106 </div>
1108 <h2 class="chapter">32 SAVE command</h2>
1110 <p><a name="index-SAVE-command-33"></a>Syntax:
1111 <pre class="example"> SAVE [--no-passphrase] [--reset] [--no-agent] [--s2k-count=N] [--cipher=&lt;algo&gt;] [--cipher-iterations=N] [--inquire-keyparam] [--keygrip=hexstring] [--sign-keygrip=hexstring]
1112 </pre>
1113 <p>Writes the <abbr>XML</abbr> document to disk. The file written to is the file that
1114 was opened using the <code>OPEN</code> command (see <a href="#OPEN">OPEN</a>). If the file is a
1115 new one or the option <samp><span class="option">--inquire-keyparam</span></samp> was passed, then a new
1116 keypair will be generated and a pinentry will be used to prompt for the
1117 passphrase to encrypt with unless the <samp><span class="option">--no-passphrase</span></samp> option was
1118 passed in which case the data file will not be passphrase protected.
1120 <p>The <samp><span class="option">--no-agent</span></samp> option disables use of <samp><span class="command">gpg-agent</span></samp> for
1121 passphrase retrieval and caching of new files when <samp><span class="command">gpg-agent</span></samp>
1122 use is enabled. The datafile will be symmetrically encrypted and will not
1123 use or generate any keypair.
1125 <p>The <samp><span class="option">--reset</span></samp> option will clear the cache entry for the current file
1126 and require a passphrase, if needed, before saving.
1128 <p>The <samp><span class="option">--cipher</span></samp> option can be used to encrypt the <abbr>XML</abbr> data to
1129 an alternate cipher. The default is <code>aes256</code>. See the Configuration
1130 (see <a href="#Configuration">Configuration</a>) for available ciphers.
1132 <p>The <samp><span class="option">--cipher-iterations</span></samp> option specifies the number of times to
1133 encrypt the XML data. The default is 0 although 1 iteration is still done.
1135 <p>The <samp><span class="option">--inquire-keyparam</span></samp> option will send a server <em>INQUIRE</em> to
1136 the client to obtain the key paramaters to use when generating a new
1137 keypair. The inquired data is expected to be an S-expression. If not
1138 specified then an &lsquo;<samp><span class="samp">RSA</span></samp>&rsquo; key of &lsquo;<samp><span class="samp">2048</span></samp>&rsquo; bits will be generated
1139 unless otherwise set in the configuration file (see <a href="#Configuration">Configuration</a>). Note
1140 that when this option is specified a new keypair will be generated
1141 reguardless if the file is a new one and that if the data file is protected
1142 the passphrase to open it will be required before generating the new keypair.
1144 <p>You can encrypt the data file to a public key other than the one that it
1145 was originally encrypted with by passing the <samp><span class="option">--keygrip</span></samp> option with
1146 the hex encoded keygrip of the public key as its argument. The keygrip may
1147 be of any key that <samp><span class="command">gpg-agent</span></samp> knows about. The
1148 <samp><span class="option">--sign-keygrip</span></samp> option may also be used to sign with an alternate
1149 secret key. This option may be needed when using a smartcard. This option
1150 has no effect with symmetrically encrypted data files.
1152 <p>The <samp><span class="option">--s2k-count</span></samp> option sets number of hash iterations for a
1153 passphrase. A value less-than <code>65536</code> will use the machine calibrated
1154 value and is the default. This setting only affects new files. To change
1155 the setting use the <code>PASSWD</code> command (see <a href="#PASSWD">PASSWD</a>). This option
1156 has no effect with symmetrically encrypted data files.
1158 <div class="node">
1159 <a name="STORE"></a>
1160 <p><hr>
1161 Next:&nbsp;<a rel="next" accesskey="n" href="#UNLOCK">UNLOCK</a>,
1162 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SAVE">SAVE</a>,
1163 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1165 </div>
1167 <h2 class="chapter">33 STORE command</h2>
1169 <p><a name="index-STORE-command-34"></a>Syntax:
1170 <pre class="example"> STORE [!]element[&lt;TAB&gt;[!]child[..]]&lt;TAB&gt;[content]
1171 </pre>
1172 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
1174 <p>Creates a new element path or modifies the <var>content</var> of an existing
1175 element. If only a single element is specified then a new root element is
1176 created. Otherwise, elements are &lt;TAB&gt; delimited and the content will be
1177 set to the final &lt;TAB&gt; delimited element. If no <var>content</var> is
1178 specified after the final &lt;TAB&gt;, then the content of the element will
1179 be removed, or empty when creating a new element.
1181 <p>The only restriction of an element name is that it not contain whitespace
1182 or begin with the literal element character <code>!</code> unless specifying a
1183 literal element (see <a href="#Target-Attribute">Target Attribute</a>). There is no whitespace between
1184 the &lt;TAB&gt; delimited elements. It is recommended that the content of an
1185 element be base64 encoded when it contains control or &lt;TAB&gt; characters
1186 to prevent <abbr>XML</abbr> parsing and <samp><span class="command">pwmd</span></samp> syntax errors.
1188 <div class="node">
1189 <a name="UNLOCK"></a>
1190 <p><hr>
1191 Next:&nbsp;<a rel="next" accesskey="n" href="#XPATH">XPATH</a>,
1192 Previous:&nbsp;<a rel="previous" accesskey="p" href="#STORE">STORE</a>,
1193 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1195 </div>
1197 <h2 class="chapter">34 UNLOCK command</h2>
1199 <p><a name="index-UNLOCK-command-35"></a>Syntax:
1200 <pre class="example"> UNLOCK
1201 </pre>
1202 <p>Unlocks the file mutex which was locked with the <code>LOCK</code> command or
1203 a commands' <samp><span class="option">--lock</span></samp> option (see <a href="#LOCK">LOCK</a>, see <a href="#OPEN">OPEN</a>,
1204 see <a href="#ISCACHED">ISCACHED</a>).
1206 <div class="node">
1207 <a name="XPATH"></a>
1208 <p><hr>
1209 Next:&nbsp;<a rel="next" accesskey="n" href="#XPATHATTR">XPATHATTR</a>,
1210 Previous:&nbsp;<a rel="previous" accesskey="p" href="#UNLOCK">UNLOCK</a>,
1211 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1213 </div>
1215 <h2 class="chapter">35 XPATH command</h2>
1217 <p><a name="index-XPATH-command-36"></a>Syntax:
1218 <pre class="example"> XPATH [--inquire] &lt;expression&gt;[&lt;TAB&gt;[value]]
1219 </pre>
1220 <p>Evaluates an XPath <var>expression</var>. If no <var>value</var> argument is
1221 specified it is assumed the expression is a request to return a result.
1222 Otherwise, the result is set to the <var>value</var> argument and the document is
1223 updated. If there is no <var>value</var> after the &lt;TAB&gt; character, the value
1224 is assumed to be empty and the document is updated. For example:
1225 <pre class="sp">
1227 </pre>
1228 <pre class="example"> XPATH //element[@_name='password']&lt;TAB&gt;
1229 </pre>
1230 <pre class="sp">
1232 </pre>
1233 would clear the content of all <code>password</code> elements in the data file
1234 while leaving off the trailing &lt;TAB&gt; would return all <code>password</code>
1235 elements in <abbr>XML</abbr> format.
1237 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
1238 arguments are retrieved via a server <em>INQUIRE</em>.
1240 <p>See <a href="http://www.w3schools.com/xpath/xpath_syntax.asp">http://www.w3schools.com/xpath/xpath_syntax.asp</a> for <abbr>XPATH</abbr>
1241 expression syntax.
1243 <div class="node">
1244 <a name="XPATHATTR"></a>
1245 <p><hr>
1246 Previous:&nbsp;<a rel="previous" accesskey="p" href="#XPATH">XPATH</a>,
1247 Up:&nbsp;<a rel="up" accesskey="u" href="#Commands">Commands</a>
1249 </div>
1251 <h2 class="chapter">36 XPATHATTR command</h2>
1253 <p><a name="index-XPATHATTR-command-37"></a>Syntax:
1254 <pre class="example"> XPATHATTR [--inquire] SET|DELETE &lt;name&gt; &lt;expression&gt;[&lt;TAB&gt;[&lt;value&gt;]]
1255 </pre>
1256 <p>Like the <code>XPATH</code> command (see <a href="#XPATH">XPATH</a>) but operates on element
1257 attributes and does not return a result. For the <var>SET</var> operation the
1258 <var>value</var> is optional but the field is required. If not specified then
1259 the attribute value will be empty. For example:
1260 <pre class="sp">
1262 </pre>
1263 <pre class="example"> XPATHATTR SET password //element[@_name='password']&lt;TAB&gt;
1264 </pre>
1265 <pre class="sp">
1267 </pre>
1268 would create an <code>password</code> attribute for each <code>password</code> element
1269 found in the document. The attribute value will be empty but still exist.
1271 <p>When the <samp><span class="option">--inquire</span></samp> option is passed then all remaining non-option
1272 arguments are retrieved via a server <em>INQUIRE</em>.
1274 <p>See <a href="http://www.w3schools.com/xpath/xpath_syntax.asp">http://www.w3schools.com/xpath/xpath_syntax.asp</a> for <abbr>XPATH</abbr>
1275 expression syntax.
1277 <!-- Node, Next, Previous, Up -->
1278 <div class="node">
1279 <a name="Status-Messages"></a>
1280 <p><hr>
1281 Next:&nbsp;<a rel="next" accesskey="n" href="#Target-Attribute">Target Attribute</a>,
1282 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Commands">Commands</a>,
1283 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1285 </div>
1287 <h2 class="chapter">37 Status messages and their meanings</h2>
1289 <p>Some commands send status messages to inform the client about certain
1290 operations or as a progress indicator. Status messages begin with a
1291 <code>KEYWORD</code> followed by a status description for status messages that
1292 require it. What status messages are sent, when, and how often depend on
1293 configuration settings (see <a href="#Configuration">Configuration</a>). A status message sent from
1294 <samp><span class="command">gpg-agent</span></samp> (see <a href="gnupg.html#Invoking-GPG_002dAGENT">Invoking GPG-AGENT</a>) is also forwarded to
1295 the client.
1297 <p><table summary=""><tr align="left"><th valign="top" width="20%">Message </th><th valign="top" width="25%">Arguments </th><th valign="top" width="55%">Description
1298 <br></th></tr><tr align="left"><td valign="top" width="20%">CACHE
1299 <a name="index-CACHE-38"></a></td><td valign="top" width="25%"><code>&lt;integer&gt;</code>
1300 </td><td valign="top" width="55%">The number of cached documents. Sent to each client after connecting
1301 (see <a href="#GETINFO">GETINFO</a>) and after every cache modification.
1303 <p><br></td></tr><tr align="left"><td valign="top" width="20%">CLIENTS
1304 <a name="index-CLIENTS-39"></a></td><td valign="top" width="25%"><code>&lt;integer&gt;</code>
1305 </td><td valign="top" width="55%">The number of connected clients (see <a href="#GETINFO">GETINFO</a>). Sent to each client
1306 when another client either connects or disconnects.
1308 <p><br></td></tr><tr align="left"><td valign="top" width="20%">DECRYPT
1309 <a name="index-DECRYPT-40"></a></td><td valign="top" width="25%"><code>n</code> <code>total</code>
1310 </td><td valign="top" width="55%">Sent to the current client during a decrypt operation. How often this
1311 status message is sent is determined by the <code>cipher_progress</code>
1312 (see <a href="#Configuration">Configuration</a>) setting.
1314 <p><br></td></tr><tr align="left"><td valign="top" width="20%">ENCRYPT
1315 <a name="index-ENCRYPT-41"></a></td><td valign="top" width="25%"><code>n</code> <code>total</code>
1316 </td><td valign="top" width="55%">Sent to the current client during an encrypt operation. How often this
1317 status message is sent is determined by the <code>cipher_progress</code>
1318 (see <a href="#Configuration">Configuration</a>) setting.
1320 <p><br></td></tr><tr align="left"><td valign="top" width="20%">GENKEY
1321 <a name="index-GENKEY-42"></a></td><td valign="top" width="25%">
1322 </td><td valign="top" width="55%">Sent once to the current client just before generating a new key-pair.
1324 <p><br></td></tr><tr align="left"><td valign="top" width="20%">INQUIRE_MAXLEN
1325 <a name="index-INQUIRE_005fMAXLEN-43"></a></td><td valign="top" width="25%"><code>&lt;bytes&gt;</code>
1326 </td><td valign="top" width="55%">Sent to the client from <samp><span class="command">gpg-agent</span></samp> when inquiring data. This
1327 specifies the maximum number of bytes allowed for the client to send and
1328 should not be exceeded.
1330 <p><br></td></tr><tr align="left"><td valign="top" width="20%">KEEPALIVE
1331 <a name="index-KEEPALIVE-44"></a></td><td valign="top" width="25%">
1332 </td><td valign="top" width="55%">Sent to each idle client every <var>keepalive_interval</var>
1333 (see <a href="#Configuration">Configuration</a>) seconds.
1335 <p><br></td></tr><tr align="left"><td valign="top" width="20%">LOCKED
1336 <a name="index-LOCKED-45"></a></td><td valign="top" width="25%">
1337 </td><td valign="top" width="55%">Sent to the current client when another client is holding the lock for
1338 the mutex associated with a file.
1340 <p><br></td></tr><tr align="left"><td valign="top" width="20%">NEWFILE
1341 <a name="index-NEWFILE-46"></a></td><td valign="top" width="25%">
1342 </td><td valign="top" width="55%">Sent to the current client when the opened (see <a href="#OPEN">OPEN</a>) file does not
1343 exist on the file-system.
1345 <p><br></td></tr><tr align="left"><td valign="top" width="20%">XFER
1346 <a name="index-XFER-47"></a></td><td valign="top" width="25%"><code>&lt;sent&gt; &lt;total&gt;</code>
1347 </td><td valign="top" width="55%">Sent to the current client when transferring data. It has two space
1348 delimited arguments. The first being the current amount of bytes transferred
1349 and the other being the total bytes to be transferred.
1350 <br></td></tr></table>
1352 <!-- Node, Next, Previous, Up -->
1353 <div class="node">
1354 <a name="Target-Attribute"></a>
1355 <p><hr>
1356 Next:&nbsp;<a rel="next" accesskey="n" href="#Signals">Signals</a>,
1357 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Status-Messages">Status Messages</a>,
1358 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1360 </div>
1362 <h2 class="chapter">38 The <code>target</code> attribute</h2>
1364 <p><a name="index-target-attribute-48"></a>A <em>case sensitive</em> attribute named <code>target</code> is treated specially
1365 when found in each element of an element path. This attribute, like other
1366 element attributes, is created or modified with the <code>ATTR</code> command
1367 (see <a href="#ATTR">ATTR</a>). The value of this attribute is an existing element path
1368 somewhere in the document. If you are familiar with <abbr>XML</abbr> entities or
1369 maybe the <abbr>HTML</abbr> <code>id</code> or <code>target</code> attributes or a symbolic link
1370 in a file-system, you may find this attribute behaves similar to any of those.
1372 <p>To create a <code>target</code> attribute use the following syntax:
1374 <pre class="example"> ATTR SET target [!]element[&lt;TAB&gt;[!]child[..]] [!]element[&lt;TAB&gt;[!]child[..]]
1375 </pre>
1376 <p>Note the single space between the two element paths. The first element path is
1377 where the <code>target</code> attribute will be created. If the element path does
1378 not exist then it will be created. This is the only time the <code>ATTR</code>
1379 (see <a href="#ATTR">ATTR</a>) command will create elements. The attribute is created in the
1380 final element of the element path.
1382 <p>The second element path is the destination of where you want the first element
1383 path to resolve to. When an element path is passed to a protocol command
1384 <samp><span class="command">pwmd</span></samp> looks for a <code>target</code> attribute when resolving each element
1385 and if found, "jumps" to the attribute value and continues resolving any
1386 remaining elements. When you want to avoid the <code>target</code> attribute for
1387 any element of an element path then prefix the element with the literal
1388 element character &lsquo;<samp><span class="samp">!</span></samp>&rsquo;.
1390 <p>When an element of a element path is removed that a <code>target</code> attribute
1391 resolves to then an error will occur. You may need to either update the
1392 <code>target</code> attribute value with a new element path or remove the attribute
1393 entirely. Remember that since the element contains the <code>target</code> attribute
1394 it will need to be prefixed with the literal element character &lsquo;<samp><span class="samp">!</span></samp>&rsquo; when
1395 specifying the element path. For example, to remove a <code>target</code>
1396 attribute for an element containing it:
1398 <pre class="example"> ATTR DELETE target path&lt;TAB&gt;to&lt;TAB&gt;!element
1399 </pre>
1400 <p>Clients should be careful of creating <code>target</code> loops, or targets that
1401 resolve to themselves. See the <var>recursion_depth</var> (see <a href="#Configuration">Configuration</a>)
1402 configuration parameter for details.
1404 <p>The <code>REALPATH</code> command (see <a href="#REALPATH">REALPATH</a>) can be used to show the element
1405 path after resolving all <code>target</code> attributes.
1407 <!-- Node, Next, Previous, Up -->
1408 <div class="node">
1409 <a name="Signals"></a>
1410 <p><hr>
1411 Next:&nbsp;<a rel="next" accesskey="n" href="#Concept-Index">Concept Index</a>,
1412 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Target-Attribute">Target Attribute</a>,
1413 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1415 </div>
1417 <h2 class="chapter">39 Recognized signals</h2>
1419 <p>Sending the <em>SIGHUP</em> signal to a <samp><span class="command">pwmd</span></samp> process will reload the
1420 configuration file and sending <em>SIGUSR1</em> will clear the entire file
1421 cache.
1423 <!-- Node, Next, Previous, Up -->
1424 <div class="node">
1425 <a name="Concept-Index"></a>
1426 <p><hr>
1427 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Signals">Signals</a>,
1428 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1430 </div>
1432 <h2 class="unnumbered">Concept Index</h2>
1434 <!-- @printindex cp -->
1435 <div class="shortcontents">
1436 <h2>Short Contents</h2>
1437 <ul>
1438 <li><a href="#toc_Introduction">1 Overview of <samp><span class="command">pwmd</span></samp></a></li>
1439 <li><a href="#toc_Invoking">2 Invoking <samp><span class="command">pwmd</span></samp></a></li>
1440 <li><a href="#toc_Configuration">3 <samp><span class="command">pwmd</span></samp> configuration file options</a></li>
1441 <li><a href="#toc_TLS">4 Configuring remote connections over TLS.</a></li>
1442 <li><a href="#toc_Pinentry">5 Pinentry configuration</a></li>
1443 <li><a href="#toc_Commands">6 Protocol commands and their syntax</a></li>
1444 <li><a href="#toc_AGENT">7 AGENT command</a></li>
1445 <li><a href="#toc_ATTR">8 ATTR command</a></li>
1446 <li><a href="#toc_CACHETIMEOUT">9 CACHETIMEOUT command</a></li>
1447 <li><a href="#toc_CLEARCACHE">10 CLEARCACHE command</a></li>
1448 <li><a href="#toc_COPY">11 COPY command</a></li>
1449 <li><a href="#toc_DELETE">12 DELETE command</a></li>
1450 <li><a href="#toc_DUMP">13 DUMP command</a></li>
1451 <li><a href="#toc_GET">14 GET command</a></li>
1452 <li><a href="#toc_GETCONFIG">15 GETCONFIG command</a></li>
1453 <li><a href="#toc_GETINFO">16 GETINFO command</a></li>
1454 <li><a href="#toc_HELP">17 HELP command</a></li>
1455 <li><a href="#toc_IMPORT">18 IMPORT command</a></li>
1456 <li><a href="#toc_ISCACHED">19 ISCACHED command</a></li>
1457 <li><a href="#toc_KEYGRIP">20 KEYGRIP command</a></li>
1458 <li><a href="#toc_LIST">21 LIST command</a></li>
1459 <li><a href="#toc_LOCK">22 LOCK command</a></li>
1460 <li><a href="#toc_LS">23 LS command</a></li>
1461 <li><a href="#toc_MOVE">24 MOVE command</a></li>
1462 <li><a href="#toc_NOP">25 NOP command</a></li>
1463 <li><a href="#toc_OPEN">26 OPEN command</a></li>
1464 <li><a href="#toc_OPTION">27 OPTION command</a></li>
1465 <li><a href="#toc_PASSWD">28 PASSWD command</a></li>
1466 <li><a href="#toc_REALPATH">29 REALPATH command</a></li>
1467 <li><a href="#toc_RENAME">30 RENAME command</a></li>
1468 <li><a href="#toc_RESET">31 RESET command</a></li>
1469 <li><a href="#toc_SAVE">32 SAVE command</a></li>
1470 <li><a href="#toc_STORE">33 STORE command</a></li>
1471 <li><a href="#toc_UNLOCK">34 UNLOCK command</a></li>
1472 <li><a href="#toc_XPATH">35 XPATH command</a></li>
1473 <li><a href="#toc_XPATHATTR">36 XPATHATTR command</a></li>
1474 <li><a href="#toc_Status-Messages">37 Status messages and their meanings</a></li>
1475 <li><a href="#toc_Target-Attribute">38 The <code>target</code> attribute</a></li>
1476 <li><a href="#toc_Signals">39 Recognized signals</a></li>
1477 <li><a href="#toc_Concept-Index">Concept Index</a></li>
1478 </ul>
1479 </div>
1481 <div class="contents">
1482 <h2>Table of Contents</h2>
1483 <ul>
1484 <li><a name="toc_Introduction" href="#Introduction">1 Overview of <samp><span class="command">pwmd</span></samp></a>
1485 <li><a name="toc_Invoking" href="#Invoking">2 Invoking <samp><span class="command">pwmd</span></samp></a>
1486 <li><a name="toc_Configuration" href="#Configuration">3 <samp><span class="command">pwmd</span></samp> configuration file options</a>
1487 <li><a name="toc_TLS" href="#TLS">4 Configuring remote connections over TLS.</a>
1488 <li><a name="toc_Pinentry" href="#Pinentry">5 Pinentry configuration</a>
1489 <li><a name="toc_Commands" href="#Commands">6 Protocol commands and their syntax</a>
1490 <li><a name="toc_AGENT" href="#AGENT">7 AGENT command</a>
1491 <li><a name="toc_ATTR" href="#ATTR">8 ATTR command</a>
1492 <li><a name="toc_CACHETIMEOUT" href="#CACHETIMEOUT">9 CACHETIMEOUT command</a>
1493 <li><a name="toc_CLEARCACHE" href="#CLEARCACHE">10 CLEARCACHE command</a>
1494 <li><a name="toc_COPY" href="#COPY">11 COPY command</a>
1495 <li><a name="toc_DELETE" href="#DELETE">12 DELETE command</a>
1496 <li><a name="toc_DUMP" href="#DUMP">13 DUMP command</a>
1497 <li><a name="toc_GET" href="#GET">14 GET command</a>
1498 <li><a name="toc_GETCONFIG" href="#GETCONFIG">15 GETCONFIG command</a>
1499 <li><a name="toc_GETINFO" href="#GETINFO">16 GETINFO command</a>
1500 <li><a name="toc_HELP" href="#HELP">17 HELP command</a>
1501 <li><a name="toc_IMPORT" href="#IMPORT">18 IMPORT command</a>
1502 <li><a name="toc_ISCACHED" href="#ISCACHED">19 ISCACHED command</a>
1503 <li><a name="toc_KEYGRIP" href="#KEYGRIP">20 KEYGRIP command</a>
1504 <li><a name="toc_LIST" href="#LIST">21 LIST command</a>
1505 <li><a name="toc_LOCK" href="#LOCK">22 LOCK command</a>
1506 <li><a name="toc_LS" href="#LS">23 LS command</a>
1507 <li><a name="toc_MOVE" href="#MOVE">24 MOVE command</a>
1508 <li><a name="toc_NOP" href="#NOP">25 NOP command</a>
1509 <li><a name="toc_OPEN" href="#OPEN">26 OPEN command</a>
1510 <li><a name="toc_OPTION" href="#OPTION">27 OPTION command</a>
1511 <li><a name="toc_PASSWD" href="#PASSWD">28 PASSWD command</a>
1512 <li><a name="toc_REALPATH" href="#REALPATH">29 REALPATH command</a>
1513 <li><a name="toc_RENAME" href="#RENAME">30 RENAME command</a>
1514 <li><a name="toc_RESET" href="#RESET">31 RESET command</a>
1515 <li><a name="toc_SAVE" href="#SAVE">32 SAVE command</a>
1516 <li><a name="toc_STORE" href="#STORE">33 STORE command</a>
1517 <li><a name="toc_UNLOCK" href="#UNLOCK">34 UNLOCK command</a>
1518 <li><a name="toc_XPATH" href="#XPATH">35 XPATH command</a>
1519 <li><a name="toc_XPATHATTR" href="#XPATHATTR">36 XPATHATTR command</a>
1520 <li><a name="toc_Status-Messages" href="#Status-Messages">37 Status messages and their meanings</a>
1521 <li><a name="toc_Target-Attribute" href="#Target-Attribute">38 The <code>target</code> attribute</a>
1522 <li><a name="toc_Signals" href="#Signals">39 Recognized signals</a>
1523 <li><a name="toc_Concept-Index" href="#Concept-Index">Concept Index</a>
1524 </li></ul>
1525 </div>
1527 </body></html>