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