doc/pwmd.html

   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>
  28
  29 </div>
  30
  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>
  41
  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>
  48
  49 </div>
  50
  51 <h2 class="chapter">1 Overview of <samp><span class="command">pwmd</span></samp></h2>
  52
  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.
  56
  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>.
  61
  62    <p>The <abbr>XML</abbr> document uses the following <abbr>DTD</abbr>:
  63
  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.
  77
  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.
  83
  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:
  87
  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>.
 101
 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>
 109
 110 </div>
 111
 112 <h2 class="chapter">2 Invoking <samp><span class="command">pwmd</span></samp></h2>
 113
 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.
 123
 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.
 130
 131    <p><a name="index-Running-_0040command_007bpwmd_007d-1"></a><samp><span class="command">pwmd</span></samp> is executed as follows:
 132
 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.
 139
 140    <p><a name="index-Options-2"></a><a name="index-Arguments-3"></a>The following command line options are supported:
 141
 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>.
 146
 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>.
 149
 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.
 156
 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>.
 162
 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>).
 166
 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.
 169
 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.
 174
 175      <br><dt>&lsquo;<samp><span class="samp">--passphrase-file, -k filename"</span></samp>&rsquo;<dd>Obtain the passphrase from the specified filename.
 176
 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.
 180
 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.
 183
 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;.
 187
 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.
 193
 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>).
 197
 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.
 199
 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.
 202
 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>.
 206
 207      <br><dt>&lsquo;<samp><span class="samp">--version</span></samp>&rsquo;<dd>Show the version, copyright and compile time features and exit.
 208
 209      <br><dt>&lsquo;<samp><span class="samp">--help</span></samp>&rsquo;<dd>Print a summary of options.
 210 </dl>
 211
 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>
 219
 220 </div>
 221
 222 <h2 class="chapter">3 <samp><span class="command">pwmd</span></samp> configuration file options</h2>
 223
 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.
 232
 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.
 235
 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.
 238
 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:
 240
 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>.
 243
 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.
 246
 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.
 250
 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>.
 254
 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>.
 257
 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>.
 259
 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>.
 262
 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>.
 266
 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>).
 268
 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.
 272
 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.
 275
 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.
 278
 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.
 281
 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.
 286
 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.
 289
 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>.
 296
 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.
 301
 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.
 304
 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.
 309
 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.
 313
 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>
 318
 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.
 322
 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>.
 327
 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>.
 332
 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>.
 337
 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.
 342
 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.
 345
 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>).
 350
 351    </dl>
 352
 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>
 357
 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>
 364
 365 </div>
 366
 367 <h2 class="chapter">4 Configuring remote connections over TLS.</h2>
 368
 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.
 372
 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.
 377
 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.
 380
 381    <p>The following TLS configuration options are available:
 382
 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>.
 387
 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>.
 390
 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.
 393
 394      <br><dt>&lsquo;<samp><span class="samp">tcp_interface = string</span></samp>&rsquo;<dd>Only useful if running as root.
 395
 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>.
 399
 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.
 403
 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.
 408
 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.
 415
 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.
 423
 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>.
 430
 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>.
 433
 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>
 437
 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>
 444
 445 </div>
 446
 447 <h2 class="chapter">5 Pinentry configuration</h2>
 448
 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.
 452
 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.
 459
 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>
 467
 468 </div>
 469
 470 <h2 class="chapter">6 Protocol commands and their syntax</h2>
 471
 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>
 509
 510 </div>
 511
 512 <h2 class="chapter">7 AGENT command</h2>
 513
 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>.
 519
 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>
 526
 527 </div>
 528
 529 <h2 class="chapter">8 ATTR command</h2>
 530
 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.
 538
 539      <br><dt>ATTR DELETE attribute [!]element[&lt;TAB&gt;[!]child[..]]<dd>
 540     Removes an <var>attribute</var> from an element.
 541
 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.
 545
 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>
 549
 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.
 553
 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.
 558
 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>.
 561
 562    <p>See <a href="#Target-Attribute">Target Attribute</a>, for details about this special attribute.
 563
 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>
 570
 571 </div>
 572
 573 <h2 class="chapter">9 CACHETIMEOUT command</h2>
 574
 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.
 583
 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>
 590
 591 </div>
 592
 593 <h2 class="chapter">10 CLEARCACHE command</h2>
 594
 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>.
 599
 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>
 606
 607 </div>
 608
 609 <h2 class="chapter">11 COPY command</h2>
 610
 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.
 617
 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.
 623
 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>.
 626
 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>
 633
 634 </div>
 635
 636 <h2 class="chapter">12 DELETE command</h2>
 637
 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.
 644
 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>.
 647
 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>
 654
 655 </div>
 656
 657 <h2 class="chapter">13 DUMP command</h2>
 658
 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.
 664
 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>
 671
 672 </div>
 673
 674 <h2 class="chapter">14 GET command</h2>
 675
 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.
 681
 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>.
 684
 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>
 691
 692 </div>
 693
 694 <h2 class="chapter">15 GETCONFIG command</h2>
 695
 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.
 704
 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>
 711
 712 </div>
 713
 714 <h2 class="chapter">16 GETINFO command</h2>
 715
 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>.
 726
 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.
 729
 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>
 736
 737 </div>
 738
 739 <h2 class="chapter">17 HELP command</h2>
 740
 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.
 745
 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>
 752
 753 </div>
 754
 755 <h2 class="chapter">18 IMPORT command</h2>
 756
 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.
 761
 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.
 767
 768    <p>The content must begin with an <abbr>XML</abbr> element node. See <a href="#Introduction">Introduction</a>,
 769 for details.
 770
 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>
 777
 778 </div>
 779
 780 <h2 class="chapter">19 ISCACHED command</h2>
 781
 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.
 789
 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.
 792
 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>
 799
 800 </div>
 801
 802 <h2 class="chapter">20 KEYGRIP command</h2>
 803
 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.
 809
 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.
 812
 813    <p>For symmetrically encrypted data files this command returns the error
 814 GPG_ERR_NOT_SUPPORTED.
 815
 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>
 822
 823 </div>
 824
 825 <h2 class="chapter">21 LIST command</h2>
 826
 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.
 837
 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).
 847
 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.
 853
 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.
 857
 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>.
 860
 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>.
 863
 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>
 870
 871 </div>
 872
 873 <h2 class="chapter">22 LOCK command</h2>
 874
 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>.
 882
 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>
 889
 890 </div>
 891
 892 <h2 class="chapter">23 LS command</h2>
 893
 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.
 899
 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>
 906
 907 </div>
 908
 909 <h2 class="chapter">24 MOVE command</h2>
 910
 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.
 919
 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>.
 922
 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>
 929
 930 </div>
 931
 932 <h2 class="chapter">25 NOP command</h2>
 933
 934 <p><a name="index-NOP-command-26"></a>Syntax:
 935 <pre class="example">     NOP
 936 </pre>
 937    <p>Does nothing. Always returns successfully.
 938
 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>
 945
 946 </div>
 947
 948 <h2 class="chapter">26 OPEN command</h2>
 949
 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.
 960
 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.
 964
 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>
 971
 972 </div>
 973
 974 <h2 class="chapter">27 OPTION command</h2>
 975
 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.
 981
 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.
 987
 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.
 990
 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.
 992
 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.
 994
 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.
 996
 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.
 998
 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.
1000
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.
1002
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.
1004
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.
1006
1007      <br><dt>NAME<dd>Associates the thread ID of the connection with the specified textual
1008 representation. Useful for debugging log messages.
1009
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.
1013
1014      <br><dt>LOG-LEVEL<dd>An integer specifiying the logging level.
1015 </dl>
1016
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>
1023
1024 </div>
1025
1026 <h2 class="chapter">28 PASSWD command</h2>
1027
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>.
1036
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.
1042
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>
1049
1050 </div>
1051
1052 <h2 class="chapter">29 REALPATH command</h2>
1053
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.
1059
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>.
1062
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>
1069
1070 </div>
1071
1072 <h2 class="chapter">30 RENAME command</h2>
1073
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.
1079
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>.
1082
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>
1089
1090 </div>
1091
1092 <h2 class="chapter">31 RESET command</h2>
1093
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.
1098
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>
1105
1106 </div>
1107
1108 <h2 class="chapter">32 SAVE command</h2>
1109
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.
1119
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.
1124
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.
1127
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.
1131
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.
1134
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.
1143
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.
1151
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.
1157
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>
1164
1165 </div>
1166
1167 <h2 class="chapter">33 STORE command</h2>
1168
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.
1173
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.
1180
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.
1187
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>
1194
1195 </div>
1196
1197 <h2 class="chapter">34 UNLOCK command</h2>
1198
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>).
1205
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>
1212
1213 </div>
1214
1215 <h2 class="chapter">35 XPATH command</h2>
1216
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">
1226
1227 </pre>
1228 <pre class="example">     XPATH //element[@_name='password']&lt;TAB&gt;
1229 </pre>
1230    <pre class="sp">
1231
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.
1236
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>.
1239
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.
1242
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>
1248
1249 </div>
1250
1251 <h2 class="chapter">36 XPATHATTR command</h2>
1252
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">
1261
1262 </pre>
1263 <pre class="example">     XPATHATTR SET password //element[@_name='password']&lt;TAB&gt;
1264 </pre>
1265    <pre class="sp">
1266
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.
1270
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>.
1273
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.
1276
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>
1284
1285 </div>
1286
1287 <h2 class="chapter">37 Status messages and their meanings</h2>
1288
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.
1296
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.
1302
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.
1307
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.
1313
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.
1319
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.
1323
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.
1329
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.
1334
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.
1339
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.
1344
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>
1351
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>
1359
1360 </div>
1361
1362 <h2 class="chapter">38 The <code>target</code> attribute</h2>
1363
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.
1371
1372    <p>To create a <code>target</code> attribute use the following syntax:
1373
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.
1381
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;.
1389
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:
1397
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.
1403
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.
1406
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>
1414
1415 </div>
1416
1417 <h2 class="chapter">39 Recognized signals</h2>
1418
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.
1422
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>
1429
1430 </div>
1431
1432 <h2 class="unnumbered">Concept Index</h2>
1433
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>
1480
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>
1526
1527 </body></html>
1528