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