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