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