doc/pwmd.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
   4 <head>
   5 <title>PWMD Manual</title>
   6
   7 <meta name="description" content="PWMD Manual">
   8 <meta name="keywords" content="PWMD Manual">
   9 <meta name="resource-type" content="document">
  10 <meta name="distribution" content="global">
  11 <meta name="Generator" content="makeinfo">
  12 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  13 <link href="#Top" rel="start" title="Top">
  14 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  15 <link href="dir.html#Top" rel="up" title="(dir)">
  16 <style type="text/css">
  17 <!--
  18 a.summary-letter {text-decoration: none}
  19 blockquote.smallquotation {font-size: smaller}
  20 div.display {margin-left: 3.2em}
  21 div.example {margin-left: 3.2em}
  22 div.indentedblock {margin-left: 3.2em}
  23 div.lisp {margin-left: 3.2em}
  24 div.smalldisplay {margin-left: 3.2em}
  25 div.smallexample {margin-left: 3.2em}
  26 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  27 div.smalllisp {margin-left: 3.2em}
  28 kbd {font-style:oblique}
  29 pre.display {font-family: inherit}
  30 pre.format {font-family: inherit}
  31 pre.menu-comment {font-family: serif}
  32 pre.menu-preformatted {font-family: serif}
  33 pre.smalldisplay {font-family: inherit; font-size: smaller}
  34 pre.smallexample {font-size: smaller}
  35 pre.smallformat {font-family: inherit; font-size: smaller}
  36 pre.smalllisp {font-size: smaller}
  37 span.nocodebreak {white-space:nowrap}
  38 span.nolinebreak {white-space:nowrap}
  39 span.roman {font-family:serif; font-weight:normal}
  40 span.sansserif {font-family:sans-serif; font-weight:normal}
  41 ul.no-bullet {list-style: none}
  42 -->
  43 </style>
  44
  45
  46 </head>
  47
  48 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  49 <h1 class="settitle" align="center">PWMD Manual</h1>
  50
  51
  52
  53
  54 <a name="Top"></a>
  55 <div class="header">
  56 <p>
  57 Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
  58 </div>
  59 <h1 class="node-heading">Top</h1>
  60
  61
  62 <table class="menu" border="0" cellspacing="0">
  63 <tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Overview of pwmd.
  64 </td></tr>
  65 <tr><td align="left" valign="top">&bull; <a href="#Invoking" accesskey="2">Invoking</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Command line options.
  66 </td></tr>
  67 <tr><td align="left" valign="top">&bull; <a href="#Configuration" accesskey="3">Configuration</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Configuration file options.
  68 </td></tr>
  69 <tr><td align="left" valign="top">&bull; <a href="#Commands" accesskey="4">Commands</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Protocol commands.
  70 </td></tr>
  71 <tr><td align="left" valign="top">&bull; <a href="#Status-Messages" accesskey="5">Status Messages</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Status lines and their meaning.
  72 </td></tr>
  73 <tr><td align="left" valign="top">&bull; <a href="#Target-Attribute" accesskey="6">Target Attribute</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">A kind of symbolic link.
  74 </td></tr>
  75 <tr><td align="left" valign="top">&bull; <a href="#Signals" accesskey="7">Signals</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Signals known to pwmd.
  76 </td></tr>
  77 <tr><td align="left" valign="top">&bull; <a href="#Concept-Index" accesskey="8">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Index of concepts.
  78 </td></tr>
  79 </table>
  80
  81 <hr>
  82 <a name="Introduction"></a>
  83 <div class="header">
  84 <p>
  85 Next: <a href="#Invoking" accesskey="n" rel="next">Invoking</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
  86 </div>
  87 <a name="Overview-of-pwmd"></a>
  88 <h2 class="chapter">1 Overview of <code>pwmd</code></h2>
  89
  90
  91
  92
  93
  94
  95 <p><code>pwmd</code> or <em>Password Manager Daemon</em> is a server that
  96 applications connect to and send commands to store and retrieve data
  97 that is saved in an encrypted <abbr>XML</abbr> document.
  98 </p>
  99 <p>The server uses the Assuan protocol (See <a href="http://www.gnupg.org/documentation/manuals/assuan/Implementation.html#Implementation">(assuan)Implementation</a>) which
 100 is the same used by <code>gpg-agent</code>, <code>pinentry</code> and
 101 <code>scdaemon</code>. It also uses <cite>libgpg-error</cite> for error reporting with
 102 the error source set as <var>GPG_ERR_SOURCE_USER_1</var>.
 103 </p>
 104
 105 <p>The <abbr>XML</abbr> document uses the following <abbr>DTD</abbr>:
 106 </p>
 107 <div class="example">
 108 <pre class="example">    &lt;?xml version=&quot;1.0&quot;?&gt;
 109     &lt;!DOCTYPE pwmd [
 110     &lt;!ELEMENT pwmd (element*)&gt;
 111     &lt;!ATTLIST element _name CDATA #REQUIRED&gt;
 112     ]&gt;
 113 </pre></div>
 114
 115 <p>The <code>pwmd</code> element is the document root node while all other elements
 116 of the document have the name <code>element</code> with an attribute <code>_name</code>
 117 whose value uniquely identifies the element at the current element tree depth.
 118 It is done this way to avoid <abbr>XML</abbr> parsing errors for commonly used
 119 characters.  A <abbr>URL</abbr> for example would be an invalid <abbr>XML</abbr> element
 120 since the <abbr>URI</abbr> contains a &lsquo;<samp>:</samp>&rsquo; which is also the <abbr>XML</abbr>
 121 namespace separator.
 122 </p>
 123 <p>As mentioned, an element name must be unique for the current element tree
 124 depth. You cannot have two elements containing the same <code>_name</code> attribute
 125 value. <code>pwmd</code> will stop searching for an element of an <em>element
 126 path</em> at the first match then continue searching for the next element of the
 127 element path beginning at the child node of the matched element.
 128 </p>
 129 <p>An <em>element path</em> is a <tt class="key">TAB</tt> delimited character string where each
 130 <tt class="key">TAB</tt> separates each element in the path.  For example, the element path
 131 <code>a<span class="key">TAB</span>b<span class="key">TAB</span>c</code> has the following <abbr>XML</abbr> document structure:
 132 </p>
 133 <div class="example">
 134 <pre class="example">   &lt;pwmd&gt;
 135             &lt;element _name=&quot;a&quot;&gt;
 136                 &lt;element _name=&quot;b&quot;&gt;
 137                     &lt;element _name=&quot;c&quot;&gt;
 138                         [... element value or content ...]
 139                     &lt;/element&gt;
 140                 &lt;/element&gt;
 141             &lt;/element&gt;
 142         &lt;/pwmd&gt;
 143 </pre></div>
 144
 145 <p>The only restriction of an element name is that it contain no whitespace
 146 characters. It also cannot begin with a &lsquo;<samp>!</samp>&rsquo; since this character is
 147 reserved for the <code>target</code> attribute. See <a href="#Target-Attribute">Target Attribute</a>.
 148 </p>
 149 <hr>
 150 <a name="Invoking"></a>
 151 <div class="header">
 152 <p>
 153 Next: <a href="#Configuration" accesskey="n" rel="next">Configuration</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 154 </div>
 155 <a name="Invoking-pwmd"></a>
 156 <h2 class="chapter">2 Invoking <code>pwmd</code></h2>
 157
 158
 159
 160 <p>When <code>pwmd</code> is started with the <samp>--use-agent</samp> command
 161 line option then <code>pwmd</code> will use <code>gpg-agent</code> for key
 162 generation, decryption, signing and caching of passphrases as the
 163 default rather than symmetrically encrypted data files.
 164 <code>gpg-agent</code> must be running prior to <code>pwmd</code> startup when
 165 this option is enabled. The <code>GPG_AGENT_INFO</code> environment variable is
 166 set by <code>gpg-agent</code> and <code>pwmd</code> uses this variable to
 167 determine where the <code>gpg-agent</code> socket is listening for
 168 connections.
 169 </p>
 170 <p>It is recommended to pass the <samp>--allow-preset-passphrase</samp>
 171 command line option to <code>gpg-agent</code>. Doing so allows <code>pwmd</code>
 172 cache pushing on startup. It is also recommended to pass the
 173 <samp>--allow-loopback-pinentry</samp> to <code>gpg-agent</code>. This option allows
 174 a passphrase to be inquired from <code>pwmd</code> when a <code>pinentry</code> is
 175 unavailable to the client.
 176 </p>
 177 <a name="index-Running-pwmd"></a>
 178 <p><code>pwmd</code> is executed as follows:
 179 </p>
 180 <div class="example">
 181 <pre class="example">pwmd <var>options</var> [ file1 ] [ &hellip; ]
 182 </pre></div>
 183
 184 <p>Non-option arguments are data files to cache on startup. When the data file
 185 requires a passphrase for decryption a <code>pinentry</code> will prompt either
 186 on the current <abbr>TTY</abbr> or from an X11 window when the <code>DISPLAY</code>
 187 environment variable is set.
 188 </p>
 189 <a name="index-Options"></a>
 190 <a name="index-Arguments"></a>
 191 <p>The following command line options are supported:
 192 </p>
 193 <a name="index-Getting-help"></a>
 194 <dl compact="compact">
 195 <dt>&lsquo;<samp>--homedir directory</samp>&rsquo;</dt>
 196 <dd><p>The root directory where pwmd will store its data and temporary files.  The
 197 default is <samp>~/.pwmd</samp>.
 198 </p>
 199 </dd>
 200 <dt>&lsquo;<samp>--rcfile, -f rcfile</samp>&rsquo;</dt>
 201 <dd><p>Specify an alternate configuration file. The default is
 202 <samp>~/.pwmd/config</samp>.
 203 </p>
 204 </dd>
 205 <dt>&lsquo;<samp>--use-agent</samp>&rsquo;</dt>
 206 <dd><p>Enable the use of <code>gpg-agent</code> and add support for data files
 207 encrypted with a keypair. Files previously handled by
 208 <code>gpg-agent</code> when this option is not specified will no longer be
 209 able to be opened and new data files are symmetrically or conventionally
 210 encrypted and without a public and private key. If
 211 specified, both data file types are supported.
 212 </p>
 213 </dd>
 214 <dt>&lsquo;<samp>--import, -I filename</samp>&rsquo;</dt>
 215 <dd><p>Imports an <abbr>XML</abbr> file. The <abbr>XML</abbr> file should be in conformance to
 216 the <code>pwmd</code> <abbr>DTD</abbr> (see <a href="#Introduction">Introduction</a>). You
 217 will be prompted for a passphrase to encrypt with.  The output is written to
 218 the filename specified with <samp>--outfile</samp>. To make use of the imported
 219 data, place the output file in <samp>~/.pwmd/data</samp>.
 220 </p>
 221 </dd>
 222 <dt>&lsquo;<samp>--keyparam S-expression</samp>&rsquo;</dt>
 223 <dd><p>The key parameters to use when generating a new key pair while importing an
 224 <abbr>XML</abbr> file or when converting a <em>version 2</em> data file. The argument
 225 must be a valid S-expression (See <a href="http://www.gnupg.org/documentation/manuals/gcrypt/S_002dexpressions.html#S_002dexpressions">(gcrypt)S-expressions</a>).
 226 </p>
 227 </dd>
 228 <dt>&lsquo;<samp>--keygrip hexstring</samp>&rsquo;</dt>
 229 <dd><p>Specifies the hexadecimal encoded public key-grip to use for encryption when
 230 importing or converting. When not specified a new key-pair will be created.
 231 </p>
 232 </dd>
 233 <dt>&lsquo;<samp>--sign-keygrip hexstring</samp>&rsquo;</dt>
 234 <dd><p>Specifies the hexadecimal encoded public key-grip to use for signing of the
 235 data file when importing or converting. When not specified the generated
 236 public key or the key specified with the <samp>--keygrip</samp> option will be
 237 used.
 238 </p>
 239 </dd>
 240 <dt>&lsquo;<samp>--passphrase-file, -k filename&quot;</samp>&rsquo;</dt>
 241 <dd><p>Obtain the passphrase from the specified filename.
 242 </p>
 243 </dd>
 244 <dt>&lsquo;<samp>--s2k-count iterations</samp>&rsquo;</dt>
 245 <dd><p>The number of times to hash the passphrase when importing or converting.  The
 246 default is the gpg-agent calibrated value of the machine. When less than
 247 &lsquo;<samp>65536</samp>&rsquo; the default will be used.
 248 </p>
 249 </dd>
 250 <dt>&lsquo;<samp>--cipher-iterations iterations</samp>&rsquo;</dt>
 251 <dd><p>The number of symmetric encryption iterations. The value is actually N+1. The
 252 default is 0+1.
 253 </p>
 254 </dd>
 255 <dt>&lsquo;<samp>--cipher algo</samp>&rsquo;</dt>
 256 <dd><p>When importing, the cipher to use for data encryption.  See the <var>cipher</var>
 257 configuration parameter (see <a href="#Configuration">Configuration</a>) for available ciphers. The
 258 default is &lsquo;<samp>aes256</samp>&rsquo;.
 259 </p>
 260 </dd>
 261 <dt>&lsquo;<samp>--convert, -C filename</samp>&rsquo;</dt>
 262 <dd><p>Converts a <code>pwmd</code> <em>version 2</em> data file to a <em>version 3</em>
 263 data file. If encrypted, you will be prompted for a passphrase to use for
 264 decryption unless <samp>--passphrase-file</samp> was specified. The converted data
 265 file will be saved to the filename specified with <samp>--outfile</samp>. All
 266 <samp>--import</samp> related options may also be used when converting.
 267 </p>
 268 </dd>
 269 <dt>&lsquo;<samp>--disable-dump, -D</samp>&rsquo;</dt>
 270 <dd><p>Disable the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and <code>DUMP</code>
 271 protocol commands (see <a href="#Commands">Commands</a>). This overrides any
 272 <var>disable_list_and_dump</var> configuration parameter (see <a href="#Configuration">Configuration</a>).
 273 </p>
 274 </dd>
 275 <dt>&lsquo;<samp>--no-fork, -n</samp>&rsquo;</dt>
 276 <dd><p>Run as a foreground process and do not fork into the background.
 277 </p>
 278 </dd>
 279 <dt>&lsquo;<samp>--ignore, --force</samp>&rsquo;</dt>
 280 <dd><p>Ignore cache pushing failures on startup. By default, <code>pwmd</code> will exit
 281 if an error occurred do to an invalid passphrase or other error.
 282 </p>
 283 </dd>
 284 <dt>&lsquo;<samp>--debug-level keyword,keyword,...</samp>&rsquo;</dt>
 285 <dd><p>Output libassuan See <a href="http://www.gnupg.org/documentation/manuals/assuan/index.html#Top">(assuan)Top</a> protocol IO with the comma
 286 separated list of output keywords.  Valid keywords are: <code>init</code>,
 287 <code>ctx</code>, <code>engine</code>, <code>data</code>, <code>sysio</code> and <code>control</code>.
 288 </p>
 289 </dd>
 290 <dt>&lsquo;<samp>--version</samp>&rsquo;</dt>
 291 <dd><p>Show the version, copyright and compile time features and exit.
 292 </p>
 293 </dd>
 294 <dt>&lsquo;<samp>--help</samp>&rsquo;</dt>
 295 <dd><p>Print a summary of options.
 296 </p></dd>
 297 </dl>
 298
 299
 300 <hr>
 301 <a name="Configuration"></a>
 302 <div class="header">
 303 <p>
 304 Next: <a href="#TLS" accesskey="n" rel="next">TLS</a>, Previous: <a href="#Invoking" accesskey="p" rel="prev">Invoking</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 305 </div>
 306 <a name="pwmd-configuration-file-options"></a>
 307 <h2 class="chapter">3 <code>pwmd</code> configuration file options</h2>
 308
 309
 310 <p>If no configuration file is specified with the <code>pwmd</code> <samp>-f</samp>
 311 command line option, <code>pwmd</code> will read <samp>~/.pwmd/config</samp> if it
 312 exists, and if not, will use defaults.  Blank lines and lines beginning with
 313 &lsquo;<samp>#</samp>&rsquo; are ignored. Some parameters may have data file specific settings by
 314 placing them in a file section. A file section is declared by surrounding the
 315 filename with braces (i.e., &lsquo;<samp>[filename]</samp>&rsquo;).  Global options may be
 316 specified in a &lsquo;<samp>[global]</samp>&rsquo; section and are the default options for new or
 317 unspecified files.
 318 </p>
 319 <p>A tilde <tt class="key">~</tt> will be expanded to the home directory of the invoking user
 320 when contained in a parameter whose value is a filename.
 321 </p>
 322 <a name="index-Reloading-the-configuration-file"></a>
 323 <p>The configuration file can be reloaded by sending the <em>SIGHUP</em> signal to
 324 a <code>pwmd</code> process.
 325 </p>
 326 <a name="index-Global-configuration-options"></a>
 327 <p>The following options are only for use in the &lsquo;<samp>global</samp>&rsquo; section:
 328 </p>
 329 <dl compact="compact">
 330 <dt>&lsquo;<samp>socket_path = /path/to/socket</samp>&rsquo;</dt>
 331 <dd><p>Listen on the specified socket. The default is <samp>~/.pwmd/socket</samp>.
 332 </p>
 333 </dd>
 334 <dt>&lsquo;<samp>socket_perms = octal_mode</samp>&rsquo;</dt>
 335 <dd><p>Permissions to set after creating the socket. This will override any
 336 <cite>umask(2)</cite> setting.
 337 </p>
 338 </dd>
 339 <dt>&lsquo;<samp>allowed = [-]user,[-]@group,...</samp>&rsquo;</dt>
 340 <dd><p>A comma separated list of local user names or group names allowed to connect
 341 to the socket. Groups should be prefixed with a &lsquo;<samp>@</samp>&rsquo;. When not specified
 342 only the invoking user may connect. A username or group name may also be
 343 prefixed with a <tt class="key">-</tt> to prevent access to a specific user or group
 344 in the list. The order of the list is important since a user may be of
 345 multiple groups.
 346 </p>
 347 <p>This parameter may also be specified in a filename section to allow or
 348 deny a local user to <code>OPEN</code> (see <a href="#OPEN">OPEN</a>) a data file and has the
 349 same default to allow only the invoking user.
 350 </p>
 351 <p>The following example would deny all users in group <code>primary</code> but
 352 allow <code>username</code> who is a member of <code>primary</code>:
 353 </p>
 354 <div class="example">
 355 <pre class="example">allowed=-@primary,username
 356 </pre></div>
 357
 358 </dd>
 359 <dt>&lsquo;<samp>disable_mlockall = boolean</samp>&rsquo;</dt>
 360 <dd><p>When set to <code>false</code>, <cite>mlockall(2)</cite> will be called on startup.  This
 361 will use more physical memory but may also be more secure since no swapping to
 362 disk will occur. The default is <var>true</var>.
 363 </p>
 364 </dd>
 365 <dt>&lsquo;<samp>log_path = /path/to/logfile</samp>&rsquo;</dt>
 366 <dd><p>Logs informational messages to the specified file. The default is
 367 <samp>~/.pwmd/log</samp>.
 368 </p>
 369 </dd>
 370 <dt>&lsquo;<samp>enable_logging = boolean</samp>&rsquo;</dt>
 371 <dd><p>Enable or disable logging to <var>log_path</var>. The default is <code>false</code>.
 372 </p>
 373 </dd>
 374 <dt>&lsquo;<samp>log_keepopen = boolean</samp>&rsquo;</dt>
 375 <dd><p>When set to <code>false</code>, the log file specified with <var>log_path</var> will be
 376 closed after writing each line. The default is <code>true</code>.
 377 </p>
 378 </dd>
 379 <dt>&lsquo;<samp>syslog = boolean</samp>&rsquo;</dt>
 380 <dd><p>Enable logging to <cite>syslog(8)</cite> with facility <em>LOG_DAEMON</em> and priority
 381 <em>LOG_INFO</em>. The default is <code>false</code>.
 382 </p>
 383 </dd>
 384 <dt>&lsquo;<samp>log_level = level</samp>&rsquo;</dt>
 385 <dd><p>When <code>0</code>, only connections and errors are logged. When <code>1</code>, client
 386 commands are also logged. When <code>2</code>, the command arguments are also logged.
 387 The default is <code>0</code>.
 388 </p>
 389 </dd>
 390 <dt>&lsquo;<samp>use_agent = boolean</samp>&rsquo;</dt>
 391 <dd><p>When true, enable <code>gpg-agent</code> support (see <a href="#Invoking">Invoking</a>).
 392 </p>
 393 </dd>
 394 <dt>&lsquo;<samp>agent_env_file = filename</samp>&rsquo;</dt>
 395 <dd><p>A file containing the <code>GPG_AGENT_INFO</code> environment variable and value as
 396 output by the <code>gpg-agent</code> <samp>--write-env-file</samp> command line
 397 option.
 398 </p>
 399 </dd>
 400 <dt>&lsquo;<samp>kill_scd = boolean</samp>&rsquo;</dt>
 401 <dd><p>Kill <code>scdaemon</code> after each <code>OPEN</code> (see <a href="#OPEN">OPEN</a>) or <code>SAVE</code>
 402 (see <a href="#SAVE">SAVE</a>) command.
 403 </p>
 404 </dd>
 405 <dt>&lsquo;<samp>require_save_key = boolean</samp>&rsquo;</dt>
 406 <dd><p>Require the passphrase needed to open a data file before writing changes
 407 of the documment to disk reguardless of the key cache status.
 408 </p>
 409 </dd>
 410 <dt>&lsquo;<samp>disable_list_and_dump = boolean</samp>&rsquo;</dt>
 411 <dd><p>When <code>true</code>, the <code>XPATH</code>, <code>XPATHATTR</code>, <code>LIST</code> and
 412 <code>DUMP</code> protocol commands (see <a href="#Commands">Commands</a>) will be disabled.
 413 </p>
 414 </dd>
 415 <dt>&lsquo;<samp>cache_push = file1,file2</samp>&rsquo;</dt>
 416 <dd><p>A comma separated list of filenames that will be pushed into the file cache
 417 upon startup. <code>pwmd</code> will prompt for the passphrase for each file unless
 418 specified with the <var>passphrase</var> or <var>passphrase_file</var> parameters in a
 419 matching file section.
 420 </p>
 421 </dd>
 422 <dt>&lsquo;<samp>priority = integer</samp>&rsquo;</dt>
 423 <dd><p>The priority, or niceness, of the server. The default is inherited from the
 424 parent process.
 425 </p>
 426 </dd>
 427 <dt>&lsquo;<samp>cipher = algorithm</samp>&rsquo;</dt>
 428 <dd><p>The default cipher to use for data encryption. The algorithm must be one of:
 429 <code>aes128</code>, <code>aes192</code>, <code>aes256</code>, <code>serpent128</code>,
 430 <code>serpent192</code>, <code>serpent256</code>, <code>camellia128</code>,
 431 <code>camellia192</code>, <code>camellia256</code>, <code>3des</code>, <code>cast5</code>,
 432 <code>blowfish</code>, <code>twofish128</code> or <code>twofish256</code>. The default is
 433 <code>aes256</code>.
 434 </p>
 435 </dd>
 436 <dt>&lsquo;<samp>cipher_iterations = integer</samp>&rsquo;</dt>
 437 <dd><p>The number of times to encrypt the XML data. This differs from the
 438 <var>s2k_count</var> parameter which specifies the number of times to hash the
 439 passphrase used to encrypt the data. The default is 0 although 1 iteration is
 440 still done.
 441 </p>
 442 </dd>
 443 <dt>&lsquo;<samp>cipher_progress = integer</samp>&rsquo;</dt>
 444 <dd><p>Send a progress message to the client after the specified amount of encryption
 445 or decryption iterations have been done. The default is 2000.
 446 </p>
 447 </dd>
 448 <dt>&lsquo;<samp>keyparam = s-expression</samp>&rsquo;</dt>
 449 <dd><p>The default key paramaters to use when generating a new key-pair. The
 450 default is RSA with 2048 bits. Note that only RSA as the encryption
 451 algorithm is supported at the moment. Both RSA and DSA keys may be used
 452 for signing.
 453 </p>
 454 </dd>
 455 <dt>&lsquo;<samp>pinentry_path = /path/to/pinentry</samp>&rsquo;</dt>
 456 <dd><p>The location of the <code>pinentry</code> binary. This program is used to
 457 prompt for a passphrase when not using <code>gpg-agent</code>. The default
 458 is specified at compile time.
 459 </p>
 460 </dd>
 461 <dt>&lsquo;<samp>pinentry_timeout = seconds</samp>&rsquo;</dt>
 462 <dd><p>The number of seconds to wait for a pinentry before giving up and
 463 returning an error. This timeout value is used for both waiting for
 464 another pinentry to complete and for the pinentry waiting for user input.
 465 </p></dd>
 466 </dl>
 467
 468 <a name="index-Data-file-configuration-options"></a>
 469 <p>The following options are defaults for new files when specified in the
 470 &lsquo;<samp>global</samp>&rsquo; section. When placed in a data file section they are options
 471 specific to that data file only.
 472 </p>
 473 <dl compact="compact">
 474 <dt>&lsquo;<samp>backup = boolean</samp>&rsquo;</dt>
 475 <dd><p>Whether to create a backup of the data file when saving. The backup filename
 476 has the <samp>.backup</samp> extension appended to the opened file. The default is
 477 <code>true</code>.
 478 </p>
 479 </dd>
 480 <dt>&lsquo;<samp>cache_timeout = seconds</samp>&rsquo;</dt>
 481 <dd><p>The number of seconds to keep the cache entry for this file. If <code>-1</code>, the
 482 cache entry is kept forever. If <code>0</code>, each time an encrypted file is
 483 <code>OPEN</code>ed (see <a href="#OPEN">OPEN</a>) a passphrase will be required. The default
 484 is <code>600</code> or 10 minutes.
 485 </p>
 486 </dd>
 487 <dt>&lsquo;<samp>xfer_progress = bytes</samp>&rsquo;</dt>
 488 <dd><p>Commands that send data lines to the client will also send the <code>XFER</code>
 489 status message (see <a href="#Status-Messages">Status Messages</a>) after the specified number of bytes
 490 have been sent. The number of bytes is rounded to <var>ASSUAN_LINELENGTH</var> or
 491 <code>1002</code> bytes. The default is <code>8196</code>.
 492 </p>
 493 </dd>
 494 <dt>&lsquo;<samp>passphrase = string</samp>&rsquo;</dt>
 495 <dd><p>The passphrase to use for this file. If specified in the &lsquo;<samp>global</samp>&rsquo; section
 496 then &lsquo;<samp>global</samp>&rsquo; is treated as a data filename and not a default for other
 497 files. Note that if a client changes the passphrase for this data file then
 498 this value is not modified and will need to be updated.
 499 </p>
 500 </dd>
 501 <dt>&lsquo;<samp>passphrase_file = /path/to/file</samp>&rsquo;</dt>
 502 <dd><p>Same as the <var>passphrase</var> parameter above but obtains the passphrase from
 503 the specified filename.
 504 </p>
 505 </dd>
 506 <dt>&lsquo;<samp>recursion_depth = integer</samp>&rsquo;</dt>
 507 <dd><p>The maximum number of times to resolve a <code>target</code> attribute for an
 508 element in an element path (see <a href="#Target-Attribute">Target Attribute</a>). An error is returned
 509 when this value is exceeded.  The default is <code>100</code> but can be disabled by
 510 setting to <code>0</code> (<em>not recommended</em>).
 511 </p>
 512 </dd>
 513 <dt>&lsquo;<samp>allowed = [-]user,[-]@group,...</samp>&rsquo;</dt>
 514 <dd><p>Same parameter value as the <code>allowed</code> parameter mentioned above in
 515 the &lsquo;<samp>global</samp>&rsquo; section but grants or denies a local user from opening
 516 a specific data file. The default is to allow only the invoking user.
 517 </p>
 518 </dd>
 519 </dl>
 520 <table class="menu" border="0" cellspacing="0">
 521 <tr><td align="left" valign="top">&bull; <a href="#TLS" accesskey="1">TLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Remote connections over TLS.
 522 </td></tr>
 523 <tr><td align="left" valign="top">&bull; <a href="#Pinentry" accesskey="2">Pinentry</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Configuration file and defaults.
 524 </td></tr>
 525 </table>
 526
 527 <hr>
 528 <a name="TLS"></a>
 529 <div class="header">
 530 <p>
 531 Next: <a href="#Pinentry" accesskey="n" rel="next">Pinentry</a>, Previous: <a href="#Configuration" accesskey="p" rel="prev">Configuration</a>, Up: <a href="#Configuration" accesskey="u" rel="up">Configuration</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 532 </div>
 533 <a name="Configuring-remote-connections-over-TLS_002e"></a>
 534 <h2 class="chapter">4 Configuring remote connections over TLS.</h2>
 535 <p>Remote connections can also be made to <code>pwmd</code> over <abbr>TLS</abbr>.
 536 Authentication is done by using X509 client certificates that are signed with
 537 the same Certificate Authority (<abbr>CA</abbr>) as the server certificate.
 538 </p>
 539 <p>The <abbr>CA</abbr> certificate is expected to be found in
 540 <samp>~/.pwmd/ca-cert.pem</samp> while the <code>pwmd</code> server certificate and key
 541 file should be put in <samp>~/.pwmd/server-cert.pem</samp> and
 542 <samp>~/.pwmd/server-key.pem</samp>, respectively.
 543 </p>
 544 <p>See the documentation of <code>certtool</code> or <code>openssl</code> for details
 545 on creating self-signed certificates.
 546 </p>
 547 <p>The following TLS configuration options are available:
 548 </p>
 549 <dl compact="compact">
 550 <dt>&lsquo;<samp>enable_tcp = boolean</samp>&rsquo;</dt>
 551 <dd><p>Whether to enable TCP/TLS server support. If enabled, both TCP and the local
 552 unix domain socket will listen for connections. The default is
 553 <code>false</code>.
 554 </p>
 555 </dd>
 556 <dt>&lsquo;<samp>tcp_port = integer</samp>&rsquo;</dt>
 557 <dd><p>The TCP port to listen on when <var>enable_tcp</var> is <code>true</code>. The default is
 558 <code>6466</code>.
 559 </p>
 560 </dd>
 561 <dt>&lsquo;<samp>tcp_bind = string</samp>&rsquo;</dt>
 562 <dd><p>The internet protocol to listen with. Must be one of <code>ipv4</code>, <code>ipv6</code>
 563 or <code>any</code> to listen for both IPv4 and IPv6 connections.
 564 </p>
 565 </dd>
 566 <dt>&lsquo;<samp>tcp_interface = string</samp>&rsquo;</dt>
 567 <dd><p>Only useful if running as root.
 568 </p>
 569 </dd>
 570 <dt>&lsquo;<samp>tls_timeout = seconds</samp>&rsquo;</dt>
 571 <dd><p>The number of seconds to wait for a read() or write() call on a
 572 <abbr>TLS</abbr> client file descriptor to complete before returning an
 573 error. The default is <var>300</var>.
 574 </p>
 575 <p>Note that the <code>SAVE</code> command (see <a href="#SAVE">SAVE</a>) may take a longer time
 576 to complete than other commands since key generation may need to be done
 577 or do to a large <samp>--cipher-iterations</samp> setting.
 578 </p>
 579 </dd>
 580 <dt>&lsquo;<samp>keepalive_interval = seconds</samp>&rsquo;</dt>
 581 <dd><p>Send a keepalive status message to an idle remote client.  An idle
 582 client is one who is not in a command. The purpose of this status
 583 message is to disconnect a hung remote client and release any file mutex
 584 locks so another client may open the same data file. The default is <code>60</code>.
 585 </p>
 586 </dd>
 587 <dt>&lsquo;<samp>tls_access = [+][!-]string[,[!-]string,...]</samp>&rsquo;</dt>
 588 <dd><p>A comma separated list of client X509 certificate fingerprints in SHA-1
 589 format that will be allowed to connect or open a file. If prefixed with
 590 <code>!</code> or <code>-</code> then access is denied for the fingerprint. When
 591 <code>!</code> or <code>-</code> is found by itself in the list it is treated as a
 592 default for remaining fingerprints in the list. The <code>+</code> prefix
 593 behaves the same but allows access. The order of the list is important
 594 meaning that of one or more fingerprints of the same SHA-1 hash, only
 595 the final in the list is considered.
 596 </p>
 597 <p>The access control is two fold: when the client connects its SHA-1
 598 fingerprint is matched against the list of allowed fingerprints in the
 599 &lsquo;<samp>global</samp>&rsquo; section. When allowed in the &lsquo;<samp>global</samp>&rsquo; section the
 600 connection is established and the client may proceed to <code>OPEN</code>
 601 (see <a href="#OPEN">OPEN</a>) a data file. During the <code>OPEN</code>, <code>CLEARCACHE</code>
 602 and <code>CACHETIMEOUT</code> commands, the
 603 fingerprint is checked again in a &lsquo;<samp>filename</samp>&rsquo; section. When this
 604 parameter is not found in a &lsquo;<samp>filename</samp>&rsquo; section then access is
 605 granted.
 606 </p>
 607 </dd>
 608 <dt>&lsquo;<samp>tcp_require_key = boolean</samp>&rsquo;</dt>
 609 <dd><p>When <code>true</code>, require the remote client to provide the key or passphrase
 610 to open a data file even if the file is cached. Note that the cache entry is
 611 cleared during the see <a href="#OPEN">OPEN</a> command and the passphrase will be retrieved
 612 from the client via a server <em>INQUIRE</em>. This option is a default
 613 for all files when specified in the &lsquo;<samp>global</samp>&rsquo; section. The default
 614 is <code>false</code>.
 615 </p>
 616 </dd>
 617 <dt>&lsquo;<samp>tcp_wait = integer</samp>&rsquo;</dt>
 618 <dd><p>The time in tenths of a second to wait between TCP connections.  Setting to 0
 619 will disable waiting. The default is <code>3</code>.
 620 </p>
 621 </dd>
 622 <dt>&lsquo;<samp>tls_cipher_suite = string</samp>&rsquo;</dt>
 623 <dd><p>The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
 624 information about the format of this string. The default is <code>SECURE256</code>.
 625 </p></dd>
 626 </dl>
 627
 628 <hr>
 629 <a name="Pinentry"></a>
 630 <div class="header">
 631 <p>
 632 Next: <a href="#Commands" accesskey="n" rel="next">Commands</a>, Previous: <a href="#TLS" accesskey="p" rel="prev">TLS</a>, Up: <a href="#Configuration" accesskey="u" rel="up">Configuration</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 633 </div>
 634 <a name="Pinentry-configuration"></a>
 635 <h2 class="chapter">5 Pinentry configuration</h2>
 636
 637 <p>The <code>pinentry</code> program is used to prompt the user for passphrase
 638 input or as a confirmation dialog; it needs to know where to prompt for
 639 the input, beit from a terminal or an X11 display.
 640 </p>
 641 <p>It is the responsibility of the client to tell <code>pinentry</code> about
 642 the terminal or X11 display before requiring the input. This is done by
 643 using the <code>pwmd</code> see <a href="#OPTION">OPTION</a> protocol command. It need be
 644 done only once per client connection. To avoid the use of
 645 <code>pinentry</code> entirely, use the <code>OPTION</code> (see <a href="#OPTION">OPTION</a>)
 646 <samp>--disable-pinentry</samp> protocol command.
 647 </p>
 648 <hr>
 649 <a name="Commands"></a>
 650 <div class="header">
 651 <p>
 652 Next: <a href="#Status-Messages" accesskey="n" rel="next">Status Messages</a>, Previous: <a href="#Pinentry" accesskey="p" rel="prev">Pinentry</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 653 </div>
 654 <a name="Protocol-commands-and-their-syntax"></a>
 655 <h2 class="chapter">6 Protocol commands and their syntax</h2>
 656 <table class="menu" border="0" cellspacing="0">
 657 <tr><td align="left" valign="top">&bull; <a href="#AGENT" accesskey="1">AGENT</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 658 </td></tr>
 659 <tr><td align="left" valign="top">&bull; <a href="#ATTR" accesskey="2">ATTR</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 660 </td></tr>
 661 <tr><td align="left" valign="top">&bull; <a href="#CACHETIMEOUT" accesskey="3">CACHETIMEOUT</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 662 </td></tr>
 663 <tr><td align="left" valign="top">&bull; <a href="#CLEARCACHE" accesskey="4">CLEARCACHE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 664 </td></tr>
 665 <tr><td align="left" valign="top">&bull; <a href="#COPY" accesskey="5">COPY</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 666 </td></tr>
 667 <tr><td align="left" valign="top">&bull; <a href="#DELETE" accesskey="6">DELETE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 668 </td></tr>
 669 <tr><td align="left" valign="top">&bull; <a href="#DUMP" accesskey="7">DUMP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 670 </td></tr>
 671 <tr><td align="left" valign="top">&bull; <a href="#GET" accesskey="8">GET</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 672 </td></tr>
 673 <tr><td align="left" valign="top">&bull; <a href="#GETCONFIG" accesskey="9">GETCONFIG</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 674 </td></tr>
 675 <tr><td align="left" valign="top">&bull; <a href="#GETINFO">GETINFO</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 676 </td></tr>
 677 <tr><td align="left" valign="top">&bull; <a href="#HELP">HELP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 678 </td></tr>
 679 <tr><td align="left" valign="top">&bull; <a href="#IMPORT">IMPORT</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 680 </td></tr>
 681 <tr><td align="left" valign="top">&bull; <a href="#ISCACHED">ISCACHED</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 682 </td></tr>
 683 <tr><td align="left" valign="top">&bull; <a href="#KEYGRIP">KEYGRIP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 684 </td></tr>
 685 <tr><td align="left" valign="top">&bull; <a href="#LIST">LIST</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 686 </td></tr>
 687 <tr><td align="left" valign="top">&bull; <a href="#LOCK">LOCK</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 688 </td></tr>
 689 <tr><td align="left" valign="top">&bull; <a href="#LS">LS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 690 </td></tr>
 691 <tr><td align="left" valign="top">&bull; <a href="#MOVE">MOVE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 692 </td></tr>
 693 <tr><td align="left" valign="top">&bull; <a href="#NOP">NOP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 694 </td></tr>
 695 <tr><td align="left" valign="top">&bull; <a href="#OPEN">OPEN</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 696 </td></tr>
 697 <tr><td align="left" valign="top">&bull; <a href="#OPTION">OPTION</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 698 </td></tr>
 699 <tr><td align="left" valign="top">&bull; <a href="#PASSWD">PASSWD</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 700 </td></tr>
 701 <tr><td align="left" valign="top">&bull; <a href="#REALPATH">REALPATH</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 702 </td></tr>
 703 <tr><td align="left" valign="top">&bull; <a href="#RENAME">RENAME</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 704 </td></tr>
 705 <tr><td align="left" valign="top">&bull; <a href="#RESET">RESET</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 706 </td></tr>
 707 <tr><td align="left" valign="top">&bull; <a href="#SAVE">SAVE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 708 </td></tr>
 709 <tr><td align="left" valign="top">&bull; <a href="#STORE">STORE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 710 </td></tr>
 711 <tr><td align="left" valign="top">&bull; <a href="#UNLOCK">UNLOCK</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 712 </td></tr>
 713 <tr><td align="left" valign="top">&bull; <a href="#XPATH">XPATH</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 714 </td></tr>
 715 <tr><td align="left" valign="top">&bull; <a href="#XPATHATTR">XPATHATTR</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 716 </td></tr>
 717 </table>
 718 <hr>
 719 <a name="AGENT"></a>
 720 <div class="header">
 721 <p>
 722 Next: <a href="#ATTR" accesskey="n" rel="next">ATTR</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 723 </div>
 724 <a name="AGENT-command"></a>
 725 <h2 class="chapter">7 AGENT command</h2>
 726 <a name="index-AGENT-command"></a>
 727 <p>Syntax:
 728 </p><div class="example">
 729 <pre class="example">AGENT &lt;command&gt;
 730 </pre></div>
 731
 732 <p>Send a <code>gpg-agent</code> protocol <var>command</var> directly to the
 733 <code>gpg-agent</code>.
 734 </p>
 735
 736 <hr>
 737 <a name="ATTR"></a>
 738 <div class="header">
 739 <p>
 740 Next: <a href="#CACHETIMEOUT" accesskey="n" rel="next">CACHETIMEOUT</a>, Previous: <a href="#AGENT" accesskey="p" rel="prev">AGENT</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 741 </div>
 742 <a name="ATTR-command"></a>
 743 <h2 class="chapter">8 ATTR command</h2>
 744 <a name="index-ATTR-command"></a>
 745 <p>Syntax:
 746 </p><div class="example">
 747 <pre class="example">ATTR [--inquire] SET|GET|DELETE|LIST [&lt;attribute&gt;] [!]element[&lt;TAB&gt;[!]child[..]] ..
 748 </pre></div>
 749
 750 <dl compact="compact">
 751 <dt>ATTR SET attribute [!]element[&lt;TAB&gt;[!]child[..]] [value]</dt>
 752 <dd>
 753 <p>Stores or updates an <var>attribute</var> name and optional <var>value</var> of an
 754 element. When no <var>value</var> is specified any existing value will be removed.
 755 </p>
 756 </dd>
 757 <dt>ATTR DELETE attribute [!]element[&lt;TAB&gt;[!]child[..]]</dt>
 758 <dd>
 759 <p>Removes an <var>attribute</var> from an element.
 760 </p>
 761 </dd>
 762 <dt>ATTR LIST [!]element[&lt;TAB&gt;[!]child[..]]</dt>
 763 <dd>
 764 <p>Retrieves a newline separated list of attributes names and values
 765 from the specified element. Each attribute name and value is space delimited.
 766 </p>
 767 </dd>
 768 <dt>ATTR GET attribute [!]element[&lt;TAB&gt;[!]child[..]]</dt>
 769 <dd>
 770 <p>Retrieves the value of an <var>attribute</var> from an element.
 771 </p></dd>
 772 </dl>
 773
 774 <p>The <code>_name</code> attribute (case sensitive) cannot be removed nor modified.
 775 Use the <code>DELETE</code> (see <a href="#DELETE">DELETE</a>) or <code>RENAME</code> (see <a href="#RENAME">RENAME</a>)
 776 commands instead.
 777 </p>
 778 <p>The <code>_mtime</code> attribute is updated each time an element is modified by
 779 either storing content, editing attributes or by deleting a child element.
 780 The <code>_ctime</code> attribute is created for each new element in an element
 781 path.
 782 </p>
 783 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
 784 arguments are retrieved via a server <em>INQUIRE</em>.
 785 </p>
 786 <p>See <a href="#Target-Attribute">Target Attribute</a>, for details about this special attribute.
 787 </p>
 788
 789 <hr>
 790 <a name="CACHETIMEOUT"></a>
 791 <div class="header">
 792 <p>
 793 Next: <a href="#CLEARCACHE" accesskey="n" rel="next">CLEARCACHE</a>, Previous: <a href="#ATTR" accesskey="p" rel="prev">ATTR</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 794 </div>
 795 <a name="CACHETIMEOUT-command"></a>
 796 <h2 class="chapter">9 CACHETIMEOUT command</h2>
 797 <a name="index-CACHETIMEOUT-command"></a>
 798 <p>Syntax:
 799 </p><div class="example">
 800 <pre class="example">CACHETIMEOUT &lt;filename&gt; &lt;seconds&gt;
 801 </pre></div>
 802
 803 <p>The time in <var>seconds</var> until <var>filename</var> will be removed from the
 804 cache. <code>-1</code> will keep the cache entry forever, <code>0</code> will require
 805 the passphrase for each <code>OPEN</code> or <code>SAVE</code> command (see <a href="#OPEN">OPEN</a>,
 806 see <a href="#SAVE">SAVE</a>). See <a href="#Configuration">Configuration</a>, and the <code>cache_timeout</code>
 807 parameter.
 808 </p>
 809
 810 <hr>
 811 <a name="CLEARCACHE"></a>
 812 <div class="header">
 813 <p>
 814 Next: <a href="#COPY" accesskey="n" rel="next">COPY</a>, Previous: <a href="#CACHETIMEOUT" accesskey="p" rel="prev">CACHETIMEOUT</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 815 </div>
 816 <a name="CLEARCACHE-command"></a>
 817 <h2 class="chapter">10 CLEARCACHE command</h2>
 818 <a name="index-CLEARCACHE-command"></a>
 819 <p>Syntax:
 820 </p><div class="example">
 821 <pre class="example">CLEARCACHE [&lt;filename&gt;]
 822 </pre></div>
 823
 824 <p>Clears a file cache entry for all or the specified <var>filename</var>.
 825 </p>
 826
 827 <hr>
 828 <a name="COPY"></a>
 829 <div class="header">
 830 <p>
 831 Next: <a href="#DELETE" accesskey="n" rel="next">DELETE</a>, Previous: <a href="#CLEARCACHE" accesskey="p" rel="prev">CLEARCACHE</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 832 </div>
 833 <a name="COPY-command"></a>
 834 <h2 class="chapter">11 COPY command</h2>
 835 <a name="index-COPY-command"></a>
 836 <p>Syntax:
 837 </p><div class="example">
 838 <pre class="example">COPY [--inquire] [!]source[&lt;TAB&gt;[!]child[..]] [!]dest[&lt;TAB&gt;[!]child[..]]
 839 </pre></div>
 840
 841 <p>Copies the entire element tree starting from the child node of the source
 842 element, to the destination element path. If the destination element path
 843 does not exist then it will be created; otherwise it is overwritten.
 844 </p>
 845 <p>Note that attributes from the source element are merged into the
 846 destination element when the destination element path exists. When an
 847 attribute of the same name exists in both the source and destination
 848 elements then the destination attribute will be updated to the source
 849 attribute value.
 850 </p>
 851 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
 852 arguments are retrieved via a server <em>INQUIRE</em>.
 853 </p>
 854
 855 <hr>
 856 <a name="DELETE"></a>
 857 <div class="header">
 858 <p>
 859 Next: <a href="#DUMP" accesskey="n" rel="next">DUMP</a>, Previous: <a href="#COPY" accesskey="p" rel="prev">COPY</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 860 </div>
 861 <a name="DELETE-command"></a>
 862 <h2 class="chapter">12 DELETE command</h2>
 863 <a name="index-DELETE-command"></a>
 864 <p>Syntax:
 865 </p><div class="example">
 866 <pre class="example">DELETE [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
 867 </pre></div>
 868
 869 <p>Removes the specified element path and all of its children. This may break
 870 an element with a <code>target</code> attribute (see <a href="#Target-Attribute">Target Attribute</a>) that
 871 refers to this element or any of its children.
 872 </p>
 873 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
 874 arguments are retrieved via a server <em>INQUIRE</em>.
 875 </p>
 876
 877 <hr>
 878 <a name="DUMP"></a>
 879 <div class="header">
 880 <p>
 881 Next: <a href="#GET" accesskey="n" rel="next">GET</a>, Previous: <a href="#DELETE" accesskey="p" rel="prev">DELETE</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 882 </div>
 883 <a name="DUMP-command"></a>
 884 <h2 class="chapter">13 DUMP command</h2>
 885 <a name="index-DUMP-command"></a>
 886 <p>Syntax:
 887 </p><div class="example">
 888 <pre class="example">DUMP
 889 </pre></div>
 890
 891 <p>Shows the in memory <abbr>XML</abbr> document with indenting. See <a href="#XPATH">XPATH</a>, for
 892 dumping a specific node.
 893 </p>
 894
 895 <hr>
 896 <a name="GET"></a>
 897 <div class="header">
 898 <p>
 899 Next: <a href="#GETCONFIG" accesskey="n" rel="next">GETCONFIG</a>, Previous: <a href="#DUMP" accesskey="p" rel="prev">DUMP</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 900 </div>
 901 <a name="GET-command"></a>
 902 <h2 class="chapter">14 GET command</h2>
 903 <a name="index-GET-command"></a>
 904 <p>Syntax:
 905 </p><div class="example">
 906 <pre class="example">GET [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
 907 </pre></div>
 908
 909 <p>Retrieves the content of the specified element. The content is returned
 910 with a data response.
 911 </p>
 912 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
 913 arguments are retrieved via a server <em>INQUIRE</em>.
 914 </p>
 915
 916 <hr>
 917 <a name="GETCONFIG"></a>
 918 <div class="header">
 919 <p>
 920 Next: <a href="#GETINFO" accesskey="n" rel="next">GETINFO</a>, Previous: <a href="#GET" accesskey="p" rel="prev">GET</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 921 </div>
 922 <a name="GETCONFIG-command"></a>
 923 <h2 class="chapter">15 GETCONFIG command</h2>
 924 <a name="index-GETCONFIG-command"></a>
 925 <p>Syntax:
 926 </p><div class="example">
 927 <pre class="example">GETCONFIG [filename] &lt;parameter&gt;
 928 </pre></div>
 929
 930 <p>Returns the value of a <code>pwmd</code> configuration <var>parameter</var> with a
 931 data response. If no file has been opened then the value for <var>filename</var>
 932 or the default from the &lsquo;<samp>global</samp>&rsquo; section will be returned. If a file
 933 has been opened and no <var>filename</var> is specified, a value previously
 934 set with the <code>OPTION</code> command (see <a href="#OPTION">OPTION</a>) will be returned.
 935 </p>
 936
 937 <hr>
 938 <a name="GETINFO"></a>
 939 <div class="header">
 940 <p>
 941 Next: <a href="#HELP" accesskey="n" rel="next">HELP</a>, Previous: <a href="#GETCONFIG" accesskey="p" rel="prev">GETCONFIG</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 942 </div>
 943 <a name="GETINFO-command"></a>
 944 <h2 class="chapter">16 GETINFO command</h2>
 945 <a name="index-GETINFO-command"></a>
 946 <p>Syntax:
 947 </p><div class="example">
 948 <pre class="example">GETINFO [--data] CACHE | CLIENTS | PID | LAST_ERROR | VERSION
 949 </pre></div>
 950
 951 <p>Get server and other information: <var>cache</var> returns the number of cached
 952 documents via a status message. <var>clients</var> returns the number of
 953 connected clients via a status message. <var>pid</var> returns the process ID
 954 number of the server via a data response. <var>VERSION</var> returns the server
 955 version number and compile-time features with a data response with each
 956 being space delimited. <var>LAST_ERROR</var> returns a detailed description of
 957 the last failed command when available. See <a href="#Status-Messages">Status Messages</a>.
 958 </p>
 959 <p>When the <samp>--data</samp> option is specified then the result will be sent
 960 via a data response rather than a status message.
 961 </p>
 962
 963 <hr>
 964 <a name="HELP"></a>
 965 <div class="header">
 966 <p>
 967 Next: <a href="#IMPORT" accesskey="n" rel="next">IMPORT</a>, Previous: <a href="#GETINFO" accesskey="p" rel="prev">GETINFO</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 968 </div>
 969 <a name="HELP-command"></a>
 970 <h2 class="chapter">17 HELP command</h2>
 971 <a name="index-HELP-command"></a>
 972 <p>Syntax:
 973 </p><div class="example">
 974 <pre class="example">HELP [&lt;COMMAND&gt;]
 975 </pre></div>
 976
 977 <p>Show available commands or command specific help text.
 978 </p>
 979
 980 <hr>
 981 <a name="IMPORT"></a>
 982 <div class="header">
 983 <p>
 984 Next: <a href="#ISCACHED" accesskey="n" rel="next">ISCACHED</a>, Previous: <a href="#HELP" accesskey="p" rel="prev">HELP</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
 985 </div>
 986 <a name="IMPORT-command"></a>
 987 <h2 class="chapter">18 IMPORT command</h2>
 988 <a name="index-IMPORT-command"></a>
 989 <p>Syntax:
 990 </p><div class="example">
 991 <pre class="example">IMPORT [--root [!]element[&lt;TAB&gt;[!]child[..]]] &lt;content&gt;
 992 </pre></div>
 993
 994 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
 995 </p>
 996 <p>Like the <code>STORE</code> command (see <a href="#STORE">STORE</a>), but the <var>content</var>
 997 argument is raw <abbr>XML</abbr> data. The content is created as a child of
 998 the element path specified with the <samp>--root</samp> option or at the
 999 document root when not specified. Existing elements of the same name will
1000 be overwritten.
1001 </p>
1002 <p>The content must begin with an <abbr>XML</abbr> element node. See <a href="#Introduction">Introduction</a>,
1003 for details.
1004 </p>
1005
1006 <hr>
1007 <a name="ISCACHED"></a>
1008 <div class="header">
1009 <p>
1010 Next: <a href="#KEYGRIP" accesskey="n" rel="next">KEYGRIP</a>, Previous: <a href="#IMPORT" accesskey="p" rel="prev">IMPORT</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1011 </div>
1012 <a name="ISCACHED-command"></a>
1013 <h2 class="chapter">19 ISCACHED command</h2>
1014 <a name="index-ISCACHED-command"></a>
1015 <p>Syntax:
1016 </p><div class="example">
1017 <pre class="example">ISCACHED [--lock] &lt;filename&gt;
1018 </pre></div>
1019
1020 <p>An <em>OK</em> response is returned if the specified <var>filename</var> is found
1021 in the file cache. If not found in the cache but exists on the filesystem
1022 then <var>GPG_ERR_NO_DATA</var> is returned. Otherwise a filesystem error is
1023 returned.
1024 </p>
1025 <p>The <samp>lock</samp> option will lock the file mutex of <var>filename</var> when the
1026 file exists; it does not need to be opened nor cached.
1027 </p>
1028
1029 <hr>
1030 <a name="KEYGRIP"></a>
1031 <div class="header">
1032 <p>
1033 Next: <a href="#LIST" accesskey="n" rel="next">LIST</a>, Previous: <a href="#ISCACHED" accesskey="p" rel="prev">ISCACHED</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1034 </div>
1035 <a name="KEYGRIP-command"></a>
1036 <h2 class="chapter">20 KEYGRIP command</h2>
1037 <a name="index-KEYGRIP-command"></a>
1038 <p>Syntax:
1039 </p><div class="example">
1040 <pre class="example">KEYGRIP [--sign] &lt;filename&gt;
1041 </pre></div>
1042
1043 <p>Returns the hex encoded keygrip of the specified <var>filename</var> with a
1044 data response.
1045 </p>
1046 <p>When the <samp>--sign</samp> option is specified then the key used for signing
1047 of the specified <var>filename</var> will be returned.
1048 </p>
1049 <p>For symmetrically encrypted data files this command returns the error
1050 GPG_ERR_NOT_SUPPORTED.
1051 </p>
1052
1053 <hr>
1054 <a name="LIST"></a>
1055 <div class="header">
1056 <p>
1057 Next: <a href="#LOCK" accesskey="n" rel="next">LOCK</a>, Previous: <a href="#KEYGRIP" accesskey="p" rel="prev">KEYGRIP</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1058 </div>
1059 <a name="LIST-command"></a>
1060 <h2 class="chapter">21 LIST command</h2>
1061 <a name="index-LIST-command"></a>
1062 <p>Syntax:
1063 </p><div class="example">
1064 <pre class="example">LIST [--inquire] [--no-recurse] [--verbose] [--with-target] [--all] [[!]element[&lt;TAB&gt;[!]child[..]]]
1065 </pre></div>
1066
1067 <p>If no element path is given then a newline separated list of root elements
1068 is returned with a data response. If given, then all reachable elements
1069 of the specified element path are returned unless the <samp>--no-recurse</samp>
1070 option is specified. If specified, only the child elements of the element
1071 path are returned without recursing into grandchildren. Each resulting
1072 element is prefixed with the literal <code>!</code> character when the element
1073 contains no <code>target</code> attribute. See <a href="#Target-Attribute">Target Attribute</a>, for details.
1074 </p>
1075 <p>When the <samp>--verbose</samp> option is passed then each element path
1076 returned will have zero or more flags appened to it. These flags are
1077 delimited from the element path by a single space character. A flag itself
1078 is a single character. Flag <code>+</code> indicates that there are child nodes of
1079 the current element path. Flag <code>E</code> indicates that an element of an
1080 element path contained in a <var>target</var> attribute could not be found. Flag
1081 <code>O</code> indicates that a <var>target</var> attribute recursion limit was reached
1082 (see <a href="#Configuration">Configuration</a>). Flag <code>T</code> will append the resolved element path
1083 of the <var>target</var> attribute contained in the current element (see below).
1084 </p>
1085 <p>The <samp>--with-target</samp> option implies <samp>--verbose</samp> and will append
1086 an additional flag <code>T</code> followed by a single space then an element path.
1087 The appended element path is the resolved path (see <a href="#REALPATH">REALPATH</a>) of the
1088 current element when it contains a <var>target</var> attribute. When no
1089 <var>target</var> attribute is found then no flag will be appended.
1090 </p>
1091 <p>The <samp>--no-recurse</samp> option limits the amount of data returned to only
1092 the listing of children of the specified element path and not any
1093 grandchildren.
1094 </p>
1095 <p>The <samp>--all</samp> option lists the entire element tree for each root
1096 element. This option also implies option <samp>--verbose</samp>.
1097 </p>
1098 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1099 arguments are retrieved via a server <em>INQUIRE</em>.
1100 </p>
1101
1102 <hr>
1103 <a name="LOCK"></a>
1104 <div class="header">
1105 <p>
1106 Next: <a href="#LS" accesskey="n" rel="next">LS</a>, Previous: <a href="#LIST" accesskey="p" rel="prev">LIST</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1107 </div>
1108 <a name="LOCK-command"></a>
1109 <h2 class="chapter">22 LOCK command</h2>
1110 <a name="index-LOCK-command"></a>
1111 <p>Syntax:
1112 </p><div class="example">
1113 <pre class="example">LOCK
1114 </pre></div>
1115
1116 <p>Locks the mutex associated with the opened file. This prevents other clients
1117 from sending commands to the same opened file until the client
1118 that sent this command either disconnects or sends the <code>UNLOCK</code>
1119 command. See <a href="#UNLOCK">UNLOCK</a>.
1120 </p>
1121
1122 <hr>
1123 <a name="LS"></a>
1124 <div class="header">
1125 <p>
1126 Next: <a href="#MOVE" accesskey="n" rel="next">MOVE</a>, Previous: <a href="#LOCK" accesskey="p" rel="prev">LOCK</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1127 </div>
1128 <a name="LS-command"></a>
1129 <h2 class="chapter">23 LS command</h2>
1130 <a name="index-LS-command"></a>
1131 <p>Syntax:
1132 </p><div class="example">
1133 <pre class="example">LS
1134 </pre></div>
1135
1136 <p>Lists the available data files stored in the data directory
1137 (<samp>~/.pwmd/data</samp>). The result is a newline separated list of filenames.
1138 </p>
1139
1140 <hr>
1141 <a name="MOVE"></a>
1142 <div class="header">
1143 <p>
1144 Next: <a href="#NOP" accesskey="n" rel="next">NOP</a>, Previous: <a href="#LS" accesskey="p" rel="prev">LS</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1145 </div>
1146 <a name="MOVE-command"></a>
1147 <h2 class="chapter">24 MOVE command</h2>
1148 <a name="index-MOVE-command"></a>
1149 <p>Syntax:
1150 </p><div class="example">
1151 <pre class="example">MOVE [--inquire] [!]source[&lt;TAB&gt;[!]child[..]] [[!]dest[&lt;TAB&gt;[!]child[..]]]
1152 </pre></div>
1153
1154 <p>Moves the source element path to the destination element path. If the
1155 destination is not specified then it will be moved to the root node of the
1156 document. If the destination is specified and exists then it will be
1157 overwritten; otherwise non-existing elements of the destination element
1158 path will be created.
1159 </p>
1160 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1161 arguments are retrieved via a server <em>INQUIRE</em>.
1162 </p>
1163
1164 <hr>
1165 <a name="NOP"></a>
1166 <div class="header">
1167 <p>
1168 Next: <a href="#OPEN" accesskey="n" rel="next">OPEN</a>, Previous: <a href="#MOVE" accesskey="p" rel="prev">MOVE</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1169 </div>
1170 <a name="NOP-command"></a>
1171 <h2 class="chapter">25 NOP command</h2>
1172 <a name="index-NOP-command"></a>
1173 <p>Syntax:
1174 </p><div class="example">
1175 <pre class="example">NOP
1176 </pre></div>
1177
1178 <p>Does nothing. Always returns successfully.
1179 </p>
1180
1181 <hr>
1182 <a name="OPEN"></a>
1183 <div class="header">
1184 <p>
1185 Next: <a href="#OPTION" accesskey="n" rel="next">OPTION</a>, Previous: <a href="#NOP" accesskey="p" rel="prev">NOP</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1186 </div>
1187 <a name="OPEN-command"></a>
1188 <h2 class="chapter">26 OPEN command</h2>
1189 <a name="index-OPEN-command"></a>
1190 <p>Syntax:
1191 </p><div class="example">
1192 <pre class="example">OPEN [--lock] &lt;filename&gt; [&lt;passphrase&gt;]
1193 </pre></div>
1194
1195 <p>Opens <var>filename</var> using <var>passphrase</var>. When the filename is not
1196 found on the file-system  then a new document will be created. If the file
1197 is found, it is looked for in the file cache. If cached and no
1198 <var>passphrase</var> was specified then the cached document is opened. When not
1199 cached, <cite>pinentry(1)</cite> will be used to retrieve the passphrase to use
1200 for decryption unless <samp>disable-pinentry</samp> (see <a href="#OPTION">OPTION</a>) was
1201 specified.
1202 </p>
1203 <p>When the <samp>--lock</samp> option is passed then the file mutex will be
1204 locked as if the <code>LOCK</code> command (see <a href="#LOCK">LOCK</a>) had been sent after the
1205 file has been opened.
1206 </p>
1207
1208 <hr>
1209 <a name="OPTION"></a>
1210 <div class="header">
1211 <p>
1212 Next: <a href="#PASSWD" accesskey="n" rel="next">PASSWD</a>, Previous: <a href="#OPEN" accesskey="p" rel="prev">OPEN</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1213 </div>
1214 <a name="OPTION-command"></a>
1215 <h2 class="chapter">27 OPTION command</h2>
1216 <a name="index-OPTION-command"></a>
1217 <p>Syntax:
1218 </p><div class="example">
1219 <pre class="example">OPTION &lt;NAME&gt;=&lt;VALUE&gt;
1220 </pre></div>
1221
1222 <p>Sets a client option <var>name</var> to <var>value</var>. The value for an option is
1223 kept for the duration of the connection.
1224 </p>
1225 <dl compact="compact">
1226 <dt>DISABLE-PINENTRY</dt>
1227 <dd><p>Disable use of <code>pinentry</code> for passphrase retrieval. When set, a
1228 server inquire is sent to the client to obtain the passphrase. This option
1229 may be set as needed before the see <a href="#OPEN">OPEN</a>, see <a href="#PASSWD">PASSWD</a>, and
1230 see <a href="#SAVE">SAVE</a> commands.
1231 </p>
1232 </dd>
1233 <dt>PINENTRY-TIMEOUT</dt>
1234 <dd><p>Sets the number of seconds before a pinentry prompt will return an error
1235 while waiting for user input.
1236 </p>
1237 </dd>
1238 <dt>TTYNAME</dt>
1239 <dd><p>Passed to the <code>gpg-agent</code> and used for the <code>pinentry</code> dialog.
1240 </p>
1241 </dd>
1242 <dt>TTYTYPE</dt>
1243 <dd><p>Passed to the <code>gpg-agent</code> and used for the <code>pinentry</code> dialog.
1244 </p>
1245 </dd>
1246 <dt>DISPLAY</dt>
1247 <dd><p>Passed to the <code>gpg-agent</code> and used for the <code>pinentry</code> dialog.
1248 </p>
1249 </dd>
1250 <dt>PINENTRY-DESC</dt>
1251 <dd><p>Sets the description string of the <code>gpg-agent</code> and <code>pinentry</code> dialog.
1252 </p>
1253 </dd>
1254 <dt>PINENTRY-TITLE</dt>
1255 <dd><p>Sets the title string of the <code>gpg-agent</code> and <code>pinentry</code> dialog.
1256 </p>
1257 </dd>
1258 <dt>PINENTRY-PROMPT</dt>
1259 <dd><p>Sets the prompt string of the <code>gpg-agent</code> and <code>pinentry</code> dialog.
1260 </p>
1261 </dd>
1262 <dt>LC-CTYPE</dt>
1263 <dd><p>Passed to the <code>gpg-agent</code> and used for the <code>pinentry</code> dialog.
1264 </p>
1265 </dd>
1266 <dt>LC-MESSAGES</dt>
1267 <dd><p>Passed to the <code>gpg-agent</code> and used for the <code>pinentry</code> dialog.
1268 </p>
1269 </dd>
1270 <dt>NAME</dt>
1271 <dd><p>Associates the thread ID of the connection with the specified textual
1272 representation. Useful for debugging log messages.
1273 </p>
1274 </dd>
1275 <dt>LOCK-TIMEOUT</dt>
1276 <dd><p>When not <code>0</code>, the duration in tenths of a second to wait for the file
1277 mutex which has been locked by another thread to be released before returning
1278 an error. When <code>-1</code>, then an error will be returned immediately.
1279 </p>
1280 </dd>
1281 <dt>LOG-LEVEL</dt>
1282 <dd><p>An integer specifiying the logging level.
1283 </p></dd>
1284 </dl>
1285
1286
1287 <hr>
1288 <a name="PASSWD"></a>
1289 <div class="header">
1290 <p>
1291 Next: <a href="#REALPATH" accesskey="n" rel="next">REALPATH</a>, Previous: <a href="#OPTION" accesskey="p" rel="prev">OPTION</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1292 </div>
1293 <a name="PASSWD-command"></a>
1294 <h2 class="chapter">28 PASSWD command</h2>
1295 <a name="index-PASSWD-command"></a>
1296 <p>Syntax:
1297 </p><div class="example">
1298 <pre class="example">PASSWD [--reset] [--s2k-count=N] [--no-passphrase]
1299 </pre></div>
1300
1301 <p>Changes the passphrase of the secret key required to open the current
1302 file or the passphrase of a symmetrically encrypted data file. When the
1303 <samp>--reset</samp> option is passed then the cache entry for the current
1304 file will be reset and the passphrase, if any, will be required during the
1305 next <code>OPEN</code>. See <a href="#OPEN">OPEN</a>.
1306 </p>
1307 <p>The <samp>--s2k-count</samp> option sets number of hash iterations for a
1308 passphrase and must be either <code>0</code> to use the calibrated count of the
1309 machine (the default), or a value greater than or equal to <code>65536</code>.
1310 See <a href="#SAVE">SAVE</a>. This option has no effect for symmetrically encrypted data
1311 files.
1312 </p>
1313 <p>The <samp>--no-passphrase</samp> option will prevent requiring a passphrase for
1314 the data file, although a passphrase may be required when changing it.
1315 </p>
1316
1317 <hr>
1318 <a name="REALPATH"></a>
1319 <div class="header">
1320 <p>
1321 Next: <a href="#RENAME" accesskey="n" rel="next">RENAME</a>, Previous: <a href="#PASSWD" accesskey="p" rel="prev">PASSWD</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1322 </div>
1323 <a name="REALPATH-command"></a>
1324 <h2 class="chapter">29 REALPATH command</h2>
1325 <a name="index-REALPATH-command"></a>
1326 <p>Syntax:
1327 </p><div class="example">
1328 <pre class="example">REALPATH [--inquire] [!]element[&lt;TAB&gt;[!]child[..]]
1329 </pre></div>
1330
1331 <p>Resolves all <code>target</code> attributes of the specified element path and
1332 returns the result with a data response. See <a href="#Target-Attribute">Target Attribute</a>, for details.
1333 </p>
1334 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1335 arguments are retrieved via a server <em>INQUIRE</em>.
1336 </p>
1337
1338 <hr>
1339 <a name="RENAME"></a>
1340 <div class="header">
1341 <p>
1342 Next: <a href="#RESET" accesskey="n" rel="next">RESET</a>, Previous: <a href="#REALPATH" accesskey="p" rel="prev">REALPATH</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1343 </div>
1344 <a name="RENAME-command"></a>
1345 <h2 class="chapter">30 RENAME command</h2>
1346 <a name="index-RENAME-command"></a>
1347 <p>Syntax:
1348 </p><div class="example">
1349 <pre class="example">RENAME [--inquire] [!]element[&lt;TAB&gt;[!]child[..]] &lt;value&gt;
1350 </pre></div>
1351
1352 <p>Renames the specified <var>element</var> to the new <var>value</var>. If an element of
1353 the same name as the <var>value</var> already exists it will be overwritten.
1354 </p>
1355 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1356 arguments are retrieved via a server <em>INQUIRE</em>.
1357 </p>
1358
1359 <hr>
1360 <a name="RESET"></a>
1361 <div class="header">
1362 <p>
1363 Next: <a href="#SAVE" accesskey="n" rel="next">SAVE</a>, Previous: <a href="#RENAME" accesskey="p" rel="prev">RENAME</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1364 </div>
1365 <a name="RESET-command"></a>
1366 <h2 class="chapter">31 RESET command</h2>
1367 <a name="index-RESET-command"></a>
1368 <p>Syntax:
1369 </p><div class="example">
1370 <pre class="example">RESET
1371 </pre></div>
1372
1373 <p>Closes the currently opened file but keeps any previously set client options.
1374 </p>
1375
1376 <hr>
1377 <a name="SAVE"></a>
1378 <div class="header">
1379 <p>
1380 Next: <a href="#STORE" accesskey="n" rel="next">STORE</a>, Previous: <a href="#RESET" accesskey="p" rel="prev">RESET</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1381 </div>
1382 <a name="SAVE-command"></a>
1383 <h2 class="chapter">32 SAVE command</h2>
1384 <a name="index-SAVE-command"></a>
1385 <p>Syntax:
1386 </p><div class="example">
1387 <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]
1388 </pre></div>
1389
1390 <p>Writes the <abbr>XML</abbr> document to disk. The file written to is the file that
1391 was opened using the <code>OPEN</code> command (see <a href="#OPEN">OPEN</a>). If the file is a
1392 new one or the option <samp>--inquire-keyparam</samp> was passed, then a new
1393 keypair will be generated and a pinentry will be used to prompt for the
1394 passphrase to encrypt with unless the <samp>--no-passphrase</samp> option was
1395 passed in which case the data file will not be passphrase protected.
1396 </p>
1397 <p>The <samp>--no-agent</samp> option disables use of <code>gpg-agent</code> for
1398 passphrase retrieval and caching of new files when <code>gpg-agent</code>
1399 use is enabled. The datafile will be symmetrically encrypted and will not
1400 use or generate any keypair.
1401 </p>
1402 <p>The <samp>--reset</samp> option will clear the cache entry for the current file
1403 and require a passphrase, if needed, before saving.
1404 </p>
1405 <p>The <samp>--cipher</samp> option can be used to encrypt the <abbr>XML</abbr> data to
1406 an alternate cipher. The default is <code>aes256</code>. See the Configuration
1407 (see <a href="#Configuration">Configuration</a>) for available ciphers.
1408 </p>
1409 <p>The <samp>--cipher-iterations</samp> option  specifies the number of times to
1410 encrypt the XML data. The default is 0 although 1 iteration is still done.
1411 </p>
1412 <p>The <samp>--inquire-keyparam</samp> option will send a server <em>INQUIRE</em> to
1413 the client to obtain the key paramaters to use when generating a new
1414 keypair. The inquired data is expected to be an S-expression. If not
1415 specified then an &lsquo;<samp>RSA</samp>&rsquo; key of &lsquo;<samp>2048</samp>&rsquo; bits will be generated
1416 unless otherwise set in the configuration file (see <a href="#Configuration">Configuration</a>). Note
1417 that when this option is specified a new keypair will be generated
1418 reguardless if the file is a new one and that if the data file is protected
1419 the passphrase to open it will be required before generating the new keypair.
1420 </p>
1421 <p>You can encrypt the data file to a public key other than the one that it
1422 was originally encrypted with by passing the <samp>--keygrip</samp> option with
1423 the hex encoded keygrip of the public key as its argument. The keygrip may
1424 be of any key that <code>gpg-agent</code> knows about. The
1425 <samp>--sign-keygrip</samp> option may also be used to sign with an alternate
1426 secret key. This option may be needed when using a smartcard. This option
1427 has no effect with symmetrically encrypted data files.
1428 </p>
1429 <p>The <samp>--s2k-count</samp> option sets number of hash iterations for a
1430 passphrase. A value less-than <code>65536</code> will use the machine calibrated
1431 value and is the default. This setting only affects new files. To change
1432 the setting use the <code>PASSWD</code> command (see <a href="#PASSWD">PASSWD</a>). This option
1433 has no effect with symmetrically encrypted data files.
1434 </p>
1435
1436 <hr>
1437 <a name="STORE"></a>
1438 <div class="header">
1439 <p>
1440 Next: <a href="#UNLOCK" accesskey="n" rel="next">UNLOCK</a>, Previous: <a href="#SAVE" accesskey="p" rel="prev">SAVE</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1441 </div>
1442 <a name="STORE-command"></a>
1443 <h2 class="chapter">33 STORE command</h2>
1444 <a name="index-STORE-command"></a>
1445 <p>Syntax:
1446 </p><div class="example">
1447 <pre class="example">STORE [!]element[&lt;TAB&gt;[!]child[..]]&lt;TAB&gt;[content]
1448 </pre></div>
1449
1450 <p>This command uses a server <em>INQUIRE</em> to retrieve data from the client.
1451 </p>
1452 <p>Creates a new element path or modifies the <var>content</var> of an existing
1453 element. If only a single element is specified then a new root element is
1454 created. Otherwise, elements are <tt class="key">TAB</tt> delimited and the content will be
1455 set to the final <tt class="key">TAB</tt> delimited element. If no <var>content</var> is
1456 specified after the final <tt class="key">TAB</tt>, then the content of the element will
1457 be removed, or empty when creating a new element.
1458 </p>
1459 <p>The only restriction of an element name is that it not contain whitespace
1460 or begin with the literal element character <code>!</code> unless specifying a
1461 literal element (see <a href="#Target-Attribute">Target Attribute</a>). There is no whitespace between
1462 the <tt class="key">TAB</tt> delimited elements. It is recommended that the content of an
1463 element be base64 encoded when it contains control or <tt class="key">TAB</tt> characters
1464 to prevent <abbr>XML</abbr> parsing and <code>pwmd</code> syntax errors.
1465 </p>
1466
1467 <hr>
1468 <a name="UNLOCK"></a>
1469 <div class="header">
1470 <p>
1471 Next: <a href="#XPATH" accesskey="n" rel="next">XPATH</a>, Previous: <a href="#STORE" accesskey="p" rel="prev">STORE</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1472 </div>
1473 <a name="UNLOCK-command"></a>
1474 <h2 class="chapter">34 UNLOCK command</h2>
1475 <a name="index-UNLOCK-command"></a>
1476 <p>Syntax:
1477 </p><div class="example">
1478 <pre class="example">UNLOCK
1479 </pre></div>
1480
1481 <p>Unlocks the file mutex which was locked with the <code>LOCK</code> command or
1482 a commands&rsquo; <samp>--lock</samp> option (see <a href="#LOCK">LOCK</a>, see <a href="#OPEN">OPEN</a>,
1483 see <a href="#ISCACHED">ISCACHED</a>).
1484 </p>
1485
1486 <hr>
1487 <a name="XPATH"></a>
1488 <div class="header">
1489 <p>
1490 Next: <a href="#XPATHATTR" accesskey="n" rel="next">XPATHATTR</a>, Previous: <a href="#UNLOCK" accesskey="p" rel="prev">UNLOCK</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1491 </div>
1492 <a name="XPATH-command"></a>
1493 <h2 class="chapter">35 XPATH command</h2>
1494 <a name="index-XPATH-command"></a>
1495 <p>Syntax:
1496 </p><div class="example">
1497 <pre class="example">XPATH [--inquire] &lt;expression&gt;[&lt;TAB&gt;[value]]
1498 </pre></div>
1499
1500 <p>Evaluates an XPath <var>expression</var>. If no <var>value</var> argument is
1501 specified it is assumed the expression is a request to return a result.
1502 Otherwise, the result is set to the <var>value</var> argument and the document is
1503 updated. If there is no <var>value</var> after the <tt class="key">TAB</tt> character, the value
1504 is assumed to be empty and the document is updated. For example:
1505 </p><br>
1506 <div class="example">
1507 <pre class="example">XPATH //element[@_name='password']<span class="key">TAB</span>
1508 </pre></div>
1509 <br>
1510 <p>would clear the content of all <code>password</code> elements in the data file
1511 while leaving off the trailing <tt class="key">TAB</tt> would return all <code>password</code>
1512 elements in <abbr>XML</abbr> format.
1513 </p>
1514 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1515 arguments are retrieved via a server <em>INQUIRE</em>.
1516 </p>
1517 <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>
1518 expression syntax.
1519 </p>
1520
1521 <hr>
1522 <a name="XPATHATTR"></a>
1523 <div class="header">
1524 <p>
1525 Previous: <a href="#XPATH" accesskey="p" rel="prev">XPATH</a>, Up: <a href="#Commands" accesskey="u" rel="up">Commands</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1526 </div>
1527 <a name="XPATHATTR-command"></a>
1528 <h2 class="chapter">36 XPATHATTR command</h2>
1529 <a name="index-XPATHATTR-command"></a>
1530 <p>Syntax:
1531 </p><div class="example">
1532 <pre class="example">XPATHATTR [--inquire] SET|DELETE &lt;name&gt; &lt;expression&gt;[&lt;TAB&gt;[&lt;value&gt;]]
1533 </pre></div>
1534
1535 <p>Like the <code>XPATH</code> command (see <a href="#XPATH">XPATH</a>) but operates on element
1536 attributes and does not return a result. For the <var>SET</var> operation the
1537 <var>value</var> is optional but the field is required. If not specified then
1538 the attribute value will be empty. For example:
1539 </p><br>
1540 <div class="example">
1541 <pre class="example">XPATHATTR SET password //element[@_name='password']<span class="key">TAB</span>
1542 </pre></div>
1543 <br>
1544 <p>would create an <code>password</code> attribute for each <code>password</code> element
1545 found in the document. The attribute value will be empty but still exist.
1546 </p>
1547 <p>When the <samp>--inquire</samp> option is passed then all remaining non-option
1548 arguments are retrieved via a server <em>INQUIRE</em>.
1549 </p>
1550 <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>
1551 expression syntax.
1552 </p>
1553
1554
1555 <hr>
1556 <a name="Status-Messages"></a>
1557 <div class="header">
1558 <p>
1559 Next: <a href="#Target-Attribute" accesskey="n" rel="next">Target Attribute</a>, Previous: <a href="#Commands" accesskey="p" rel="prev">Commands</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1560 </div>
1561 <a name="Status-messages-and-their-meanings"></a>
1562 <h2 class="chapter">37 Status messages and their meanings</h2>
1563 <p>Some commands send status messages to inform the client about certain
1564 operations or as a progress indicator.  Status messages begin with a
1565 <code>KEYWORD</code> followed by a status description for status messages that
1566 require it. What status messages are sent, when, and how often depend on
1567 configuration settings (see <a href="#Configuration">Configuration</a>). A status message sent from
1568 <code>gpg-agent</code> (See <a href="http://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT">(gnupg)Invoking GPG-AGENT</a>) is also forwarded to
1569 the client.
1570 </p>
1571 <table>
1572 <thead><tr><th width="20%">Message</th><th width="25%">Arguments</th><th width="55%">Description</th></tr></thead>
1573 <tr><td width="20%">CACHE
1574 <a name="index-CACHE"></a></td><td width="25%"><code>&lt;integer&gt;</code></td><td width="55%">The number of cached documents. Sent to each client after connecting
1575 (see <a href="#GETINFO">GETINFO</a>) and after every cache modification.</td></tr>
1576 <tr><td width="20%">CLIENTS
1577 <a name="index-CLIENTS"></a></td><td width="25%"><code>&lt;integer&gt;</code></td><td width="55%">The number of connected clients (see <a href="#GETINFO">GETINFO</a>). Sent to each client
1578 when another client either connects or disconnects.</td></tr>
1579 <tr><td width="20%">DECRYPT
1580 <a name="index-DECRYPT"></a></td><td width="25%"><code>n</code> <code>total</code></td><td width="55%">Sent to the current client during a decrypt operation. How often this
1581 status message is sent is determined by the <code>cipher_progress</code>
1582 (see <a href="#Configuration">Configuration</a>) setting.</td></tr>
1583 <tr><td width="20%">ENCRYPT
1584 <a name="index-ENCRYPT"></a></td><td width="25%"><code>n</code> <code>total</code></td><td width="55%">Sent to the current client during an  encrypt operation. How often this
1585 status message is sent is determined by the <code>cipher_progress</code>
1586 (see <a href="#Configuration">Configuration</a>) setting.</td></tr>
1587 <tr><td width="20%">GENKEY
1588 <a name="index-GENKEY"></a></td><td width="25%"></td><td width="55%">Sent once to the current client just before generating a new key-pair.</td></tr>
1589 <tr><td width="20%">INQUIRE_MAXLEN
1590 <a name="index-INQUIRE_005fMAXLEN"></a></td><td width="25%"><code>&lt;bytes&gt;</code></td><td width="55%">Sent to the client from <code>gpg-agent</code> when inquiring data. This
1591 specifies the maximum number of bytes allowed for the client to send and
1592 should not be exceeded.</td></tr>
1593 <tr><td width="20%">KEEPALIVE
1594 <a name="index-KEEPALIVE"></a></td><td width="25%"></td><td width="55%">Sent to each idle client every <var>keepalive_interval</var>
1595 (see <a href="#Configuration">Configuration</a>) seconds.</td></tr>
1596 <tr><td width="20%">LOCKED
1597 <a name="index-LOCKED"></a></td><td width="25%"></td><td width="55%">Sent to the current client when another client is holding the lock for
1598 the mutex associated with a file.</td></tr>
1599 <tr><td width="20%">NEWFILE
1600 <a name="index-NEWFILE"></a></td><td width="25%"></td><td width="55%">Sent to the current client when the opened (see <a href="#OPEN">OPEN</a>) file does not
1601 exist on the file-system.</td></tr>
1602 <tr><td width="20%">XFER
1603 <a name="index-XFER"></a></td><td width="25%"><code>&lt;sent&gt; &lt;total&gt;</code></td><td width="55%">Sent to the current client when transferring data. It has two space
1604 delimited arguments. The first being the current amount of bytes transferred
1605 and the other being the total bytes to be transferred.</td></tr>
1606 </table>
1607
1608 <hr>
1609 <a name="Target-Attribute"></a>
1610 <div class="header">
1611 <p>
1612 Next: <a href="#Signals" accesskey="n" rel="next">Signals</a>, Previous: <a href="#Status-Messages" accesskey="p" rel="prev">Status Messages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1613 </div>
1614 <a name="The-target-attribute"></a>
1615 <h2 class="chapter">38 The <code>target</code> attribute</h2>
1616 <a name="index-target-attribute"></a>
1617 <p>A <em>case sensitive</em> attribute named <code>target</code> is treated specially
1618 when found in each element of an element path. This attribute, like other
1619 element attributes, is created or modified with the <code>ATTR</code> command
1620 (see <a href="#ATTR">ATTR</a>). The value of this attribute is an existing element path
1621 somewhere in the document.  If you are familiar with <abbr>XML</abbr> entities or
1622 maybe the <abbr>HTML</abbr> <code>id</code> or <code>target</code> attributes or a symbolic link
1623 in a file-system, you may find this attribute behaves similar to any of those.
1624 </p>
1625 <p>To create a <code>target</code> attribute use the following syntax:
1626 </p>
1627 <div class="example">
1628 <pre class="example">ATTR SET target [!]element[<span class="key">TAB</span>[!]child[..]] [!]element[<span class="key">TAB</span>[!]child[..]]
1629 </pre></div>
1630
1631 <p>Note the single space between the two element paths. The first element path is
1632 where the <code>target</code> attribute will be created. If the element path does
1633 not exist then it will be created.  This is the only time the <code>ATTR</code>
1634 (see <a href="#ATTR">ATTR</a>) command will create elements. The attribute is created in the
1635 final element of the element path.
1636 </p>
1637 <p>The second element path is the destination of where you want the first element
1638 path to resolve to. When an element path is passed to a protocol command
1639 <code>pwmd</code> looks for a <code>target</code> attribute when resolving each element
1640 and if found, &quot;jumps&quot; to the attribute value and continues resolving any
1641 remaining elements.  When you want to avoid the <code>target</code> attribute for
1642 any element of an element path then prefix the element with the literal
1643 element character &lsquo;<samp>!</samp>&rsquo;.
1644 </p>
1645 <p>When an element of a element path is removed that a <code>target</code> attribute
1646 resolves to then an error will occur. You may need to either update the
1647 <code>target</code> attribute value with a new element path or remove the attribute
1648 entirely. Remember that since the element contains the <code>target</code> attribute
1649 it will need to be prefixed with the literal element character &lsquo;<samp>!</samp>&rsquo; when
1650 specifying the element path. For example, to remove a <code>target</code>
1651 attribute for an element containing it:
1652 </p>
1653 <div class="example">
1654 <pre class="example">ATTR DELETE target path<span class="key">TAB</span>to<span class="key">TAB</span>!element
1655 </pre></div>
1656
1657 <p>Clients should be careful of creating <code>target</code> loops, or targets that
1658 resolve to themselves. See the <var>recursion_depth</var> (see <a href="#Configuration">Configuration</a>)
1659 configuration parameter for details.
1660 </p>
1661 <p>The <code>REALPATH</code> command (see <a href="#REALPATH">REALPATH</a>) can be used to show the element
1662 path after resolving all <code>target</code> attributes.
1663 </p>
1664
1665 <hr>
1666 <a name="Signals"></a>
1667 <div class="header">
1668 <p>
1669 Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Target-Attribute" accesskey="p" rel="prev">Target Attribute</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1670 </div>
1671 <a name="Recognized-signals"></a>
1672 <h2 class="chapter">39 Recognized signals</h2>
1673
1674 <p>Sending the <em>SIGHUP</em> signal to a <code>pwmd</code> process will reload the
1675 configuration file and sending <em>SIGUSR1</em> will clear the entire file
1676 cache.
1677 </p>
1678
1679
1680 <hr>
1681 <a name="Concept-Index"></a>
1682 <div class="header">
1683 <p>
1684 Previous: <a href="#Signals" accesskey="p" rel="prev">Signals</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
1685 </div>
1686 <a name="Concept-Index-1"></a>
1687 <h2 class="unnumbered">Concept Index</h2>
1688
1689
1690 <a name="SEC_Overview"></a>
1691 <h2 class="shortcontents-heading">Short Table of Contents</h2>
1692
1693 <div class="shortcontents">
1694 <ul class="no-bullet">
1695 <li><a name="stoc-Overview-of-pwmd" href="#toc-Overview-of-pwmd">1 Overview of <code>pwmd</code></a></li>
1696 <li><a name="stoc-Invoking-pwmd" href="#toc-Invoking-pwmd">2 Invoking <code>pwmd</code></a></li>
1697 <li><a name="stoc-pwmd-configuration-file-options" href="#toc-pwmd-configuration-file-options">3 <code>pwmd</code> configuration file options</a></li>
1698 <li><a name="stoc-Configuring-remote-connections-over-TLS_002e" href="#toc-Configuring-remote-connections-over-TLS_002e">4 Configuring remote connections over TLS.</a></li>
1699 <li><a name="stoc-Pinentry-configuration" href="#toc-Pinentry-configuration">5 Pinentry configuration</a></li>
1700 <li><a name="stoc-Protocol-commands-and-their-syntax" href="#toc-Protocol-commands-and-their-syntax">6 Protocol commands and their syntax</a></li>
1701 <li><a name="stoc-AGENT-command" href="#toc-AGENT-command">7 AGENT command</a></li>
1702 <li><a name="stoc-ATTR-command" href="#toc-ATTR-command">8 ATTR command</a></li>
1703 <li><a name="stoc-CACHETIMEOUT-command" href="#toc-CACHETIMEOUT-command">9 CACHETIMEOUT command</a></li>
1704 <li><a name="stoc-CLEARCACHE-command" href="#toc-CLEARCACHE-command">10 CLEARCACHE command</a></li>
1705 <li><a name="stoc-COPY-command" href="#toc-COPY-command">11 COPY command</a></li>
1706 <li><a name="stoc-DELETE-command" href="#toc-DELETE-command">12 DELETE command</a></li>
1707 <li><a name="stoc-DUMP-command" href="#toc-DUMP-command">13 DUMP command</a></li>
1708 <li><a name="stoc-GET-command" href="#toc-GET-command">14 GET command</a></li>
1709 <li><a name="stoc-GETCONFIG-command" href="#toc-GETCONFIG-command">15 GETCONFIG command</a></li>
1710 <li><a name="stoc-GETINFO-command" href="#toc-GETINFO-command">16 GETINFO command</a></li>
1711 <li><a name="stoc-HELP-command" href="#toc-HELP-command">17 HELP command</a></li>
1712 <li><a name="stoc-IMPORT-command" href="#toc-IMPORT-command">18 IMPORT command</a></li>
1713 <li><a name="stoc-ISCACHED-command" href="#toc-ISCACHED-command">19 ISCACHED command</a></li>
1714 <li><a name="stoc-KEYGRIP-command" href="#toc-KEYGRIP-command">20 KEYGRIP command</a></li>
1715 <li><a name="stoc-LIST-command" href="#toc-LIST-command">21 LIST command</a></li>
1716 <li><a name="stoc-LOCK-command" href="#toc-LOCK-command">22 LOCK command</a></li>
1717 <li><a name="stoc-LS-command" href="#toc-LS-command">23 LS command</a></li>
1718 <li><a name="stoc-MOVE-command" href="#toc-MOVE-command">24 MOVE command</a></li>
1719 <li><a name="stoc-NOP-command" href="#toc-NOP-command">25 NOP command</a></li>
1720 <li><a name="stoc-OPEN-command" href="#toc-OPEN-command">26 OPEN command</a></li>
1721 <li><a name="stoc-OPTION-command" href="#toc-OPTION-command">27 OPTION command</a></li>
1722 <li><a name="stoc-PASSWD-command" href="#toc-PASSWD-command">28 PASSWD command</a></li>
1723 <li><a name="stoc-REALPATH-command" href="#toc-REALPATH-command">29 REALPATH command</a></li>
1724 <li><a name="stoc-RENAME-command" href="#toc-RENAME-command">30 RENAME command</a></li>
1725 <li><a name="stoc-RESET-command" href="#toc-RESET-command">31 RESET command</a></li>
1726 <li><a name="stoc-SAVE-command" href="#toc-SAVE-command">32 SAVE command</a></li>
1727 <li><a name="stoc-STORE-command" href="#toc-STORE-command">33 STORE command</a></li>
1728 <li><a name="stoc-UNLOCK-command" href="#toc-UNLOCK-command">34 UNLOCK command</a></li>
1729 <li><a name="stoc-XPATH-command" href="#toc-XPATH-command">35 XPATH command</a></li>
1730 <li><a name="stoc-XPATHATTR-command" href="#toc-XPATHATTR-command">36 XPATHATTR command</a></li>
1731 <li><a name="stoc-Status-messages-and-their-meanings" href="#toc-Status-messages-and-their-meanings">37 Status messages and their meanings</a></li>
1732 <li><a name="stoc-The-target-attribute" href="#toc-The-target-attribute">38 The <code>target</code> attribute</a></li>
1733 <li><a name="stoc-Recognized-signals" href="#toc-Recognized-signals">39 Recognized signals</a></li>
1734 <li><a name="stoc-Concept-Index-1" href="#toc-Concept-Index-1">Concept Index</a></li>
1735
1736 </ul>
1737 </div>
1738
1739 <a name="SEC_Contents"></a>
1740 <h2 class="contents-heading">Table of Contents</h2>
1741
1742 <div class="contents">
1743 <ul class="no-bullet">
1744 <li><a name="toc-Overview-of-pwmd" href="#Introduction">1 Overview of <code>pwmd</code></a></li>
1745 <li><a name="toc-Invoking-pwmd" href="#Invoking">2 Invoking <code>pwmd</code></a></li>
1746 <li><a name="toc-pwmd-configuration-file-options" href="#Configuration">3 <code>pwmd</code> configuration file options</a></li>
1747 <li><a name="toc-Configuring-remote-connections-over-TLS_002e" href="#TLS">4 Configuring remote connections over TLS.</a></li>
1748 <li><a name="toc-Pinentry-configuration" href="#Pinentry">5 Pinentry configuration</a></li>
1749 <li><a name="toc-Protocol-commands-and-their-syntax" href="#Commands">6 Protocol commands and their syntax</a></li>
1750 <li><a name="toc-AGENT-command" href="#AGENT">7 AGENT command</a></li>
1751 <li><a name="toc-ATTR-command" href="#ATTR">8 ATTR command</a></li>
1752 <li><a name="toc-CACHETIMEOUT-command" href="#CACHETIMEOUT">9 CACHETIMEOUT command</a></li>
1753 <li><a name="toc-CLEARCACHE-command" href="#CLEARCACHE">10 CLEARCACHE command</a></li>
1754 <li><a name="toc-COPY-command" href="#COPY">11 COPY command</a></li>
1755 <li><a name="toc-DELETE-command" href="#DELETE">12 DELETE command</a></li>
1756 <li><a name="toc-DUMP-command" href="#DUMP">13 DUMP command</a></li>
1757 <li><a name="toc-GET-command" href="#GET">14 GET command</a></li>
1758 <li><a name="toc-GETCONFIG-command" href="#GETCONFIG">15 GETCONFIG command</a></li>
1759 <li><a name="toc-GETINFO-command" href="#GETINFO">16 GETINFO command</a></li>
1760 <li><a name="toc-HELP-command" href="#HELP">17 HELP command</a></li>
1761 <li><a name="toc-IMPORT-command" href="#IMPORT">18 IMPORT command</a></li>
1762 <li><a name="toc-ISCACHED-command" href="#ISCACHED">19 ISCACHED command</a></li>
1763 <li><a name="toc-KEYGRIP-command" href="#KEYGRIP">20 KEYGRIP command</a></li>
1764 <li><a name="toc-LIST-command" href="#LIST">21 LIST command</a></li>
1765 <li><a name="toc-LOCK-command" href="#LOCK">22 LOCK command</a></li>
1766 <li><a name="toc-LS-command" href="#LS">23 LS command</a></li>
1767 <li><a name="toc-MOVE-command" href="#MOVE">24 MOVE command</a></li>
1768 <li><a name="toc-NOP-command" href="#NOP">25 NOP command</a></li>
1769 <li><a name="toc-OPEN-command" href="#OPEN">26 OPEN command</a></li>
1770 <li><a name="toc-OPTION-command" href="#OPTION">27 OPTION command</a></li>
1771 <li><a name="toc-PASSWD-command" href="#PASSWD">28 PASSWD command</a></li>
1772 <li><a name="toc-REALPATH-command" href="#REALPATH">29 REALPATH command</a></li>
1773 <li><a name="toc-RENAME-command" href="#RENAME">30 RENAME command</a></li>
1774 <li><a name="toc-RESET-command" href="#RESET">31 RESET command</a></li>
1775 <li><a name="toc-SAVE-command" href="#SAVE">32 SAVE command</a></li>
1776 <li><a name="toc-STORE-command" href="#STORE">33 STORE command</a></li>
1777 <li><a name="toc-UNLOCK-command" href="#UNLOCK">34 UNLOCK command</a></li>
1778 <li><a name="toc-XPATH-command" href="#XPATH">35 XPATH command</a></li>
1779 <li><a name="toc-XPATHATTR-command" href="#XPATHATTR">36 XPATHATTR command</a></li>
1780 <li><a name="toc-Status-messages-and-their-meanings" href="#Status-Messages">37 Status messages and their meanings</a></li>
1781 <li><a name="toc-The-target-attribute" href="#Target-Attribute">38 The <code>target</code> attribute</a></li>
1782 <li><a name="toc-Recognized-signals" href="#Signals">39 Recognized signals</a></li>
1783 <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
1784
1785 </ul>
1786 </div>
1787
1788 <hr>
1789
1790
1791
1792 </body>
1793 </html>