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