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