16 @dircategory Miscellaneous
18 * pwmd: (pwmd). Password Manager Daemon
23 @subtitle Commands and syntax
28 @c Node, Next, Previous, Up
33 This manual documents @command{pwmd} version 3.3 protocol commands and
38 * Introduction:: Overview of pwmd.
39 * Access Control:: ACL of a single XML element.
40 * Cache Control:: Key and data file cache handling.
41 * Invoking:: Command line options.
42 * Configuration:: Configuration file options.
43 * Commands:: Protocol commands.
44 * Bulk Commands:: Running multiple commands in sequence.
45 * Status Messages:: Status lines and their meaning.
46 * Target Attribute:: A kind of symbolic link.
47 * Other Attributes:: Other attributes specially handled by pwmd.
48 * Key Expiration:: What to do when a key expires.
49 * Signals:: Signals known to pwmd.
50 * Index:: Index of concepts.
53 @c Node, Next, Previous, Up
54 @node Introduction, Access Control, , Top
55 @chapter Overview of @command{pwmd}
60 \- a universal data server
66 [options] [file1] [...]
70 @dfn{Password Manager Daemon} (or @command{pwmd}) is a server that users or
71 applications connect to and send commands to store and retrieve data that is
72 stored in an OpenPGP encrypted @acronym{XML} document. It mimics a filesystem
73 in a lot of ways including per element @acronym{ACL}'s, but also has the
74 advantage of remote connections over @acronym{TLS} and a document cache. The
75 document cache is needed for a data file encrypted with secret keys stored on
76 a smartcard and without availability of an @acronym{HSM}.
78 The server uses the Assuan protocol and is the same used by
79 @command{gpg-agent}, @command{pinentry}, @command{gpgme} and
80 @command{scdaemon}. It also uses @cite{libgpg-error} for error reporting with
81 @var{GPG_ERR_SOURCE_USER_1} being the error source.
84 You can import an existing @command{pwmd} version @var{3.0.x} data file by
85 dumping the raw @acronym{XML} data with
88 importing that file by using @command{pwmd}'s @option{--import} command line
92 manual page for details.
94 It is recommended to read the texinfo documentation of @command{pwmd}
95 since it contains protocol commands and syntax and other details not
100 The @acronym{XML} document uses the following @acronym{DTD}:
103 <?xml version="1.0"?>
105 <!ELEMENT pwmd (element*)>
106 <!ATTLIST element _name CDATA #REQUIRED>
110 The @code{pwmd} element is the document root node while all other elements
111 of the document have the name @code{element} with an attribute @code{_name}
112 whose value uniquely identifies the element at the current element tree depth.
113 It is done this way to avoid @acronym{XML} parsing errors for commonly used
114 characters. A @acronym{URL} for example would be an invalid @acronym{XML}
115 element since the @acronym{URI} contains a @samp{:} which is also the
116 @acronym{XML} namespace separator.
118 As mentioned, an element name must be unique for the current element tree
119 depth. You cannot have two elements containing the same @code{_name} attribute
120 value. @command{pwmd} will stop searching for an element of an @emph{element
121 path} at the first match then continue searching for the next element of the
122 element path beginning at the child node of the matched element.
124 An @emph{element path} is a @code{TAB} delimited character string where each
125 @code{TAB} separates each element in the path. For example, the element path
126 @code{a@code{TAB}b@code{TAB}c} has the following @acronym{XML} document
134 [@dots{} element value or content @dots{}]
141 The only restriction of an element name is that it contain no whitespace
144 @c Node, Next, Previous, Up
145 @node Access Control, Cache Control, Introduction, Top
146 @chapter Access Control
148 Like a filesystem has an @acronym{ACL} to grant or limit access to directories
149 or files for a specific user or group, @command{pwmd} can limit a local user,
150 group, @acronym{TLS} connection or a command to a specific element path. This
151 is done by storing an @acronym{ACL} in the element attribute @var{_acl}. Its
152 syntax is similar to the @var{allowed} configuration parameter
153 (@pxref{Configuration}) with the exception that a @acronym{TLS} fingerprint
154 hash is prefixed with a @code{#}.
156 Access is denied for any user that is not in the @acronym{ACL} of an element
157 with the exception of an invoking user (see @var{invoking_user}). The
158 connected client must be in the @acronym{ACL} for each element in an element
159 path otherwise an error is returned.
161 The first user listed in the @acronym{ACL} is considered the owner of the
162 element. This determines which clients may modify an @var{_acl} attribute and
163 store content for an element. An @var{invoking_user} may always modify an
164 @acronym{ACL}. As an example:
167 <element _name="test" _acl="username,-@@wheel,root,#ABCDEF,/usr/bin/pwmc">
168 <element _name="child"/>
172 The user @code{username} would be allowed both read and write access to the
173 @code{test} element but not if it is a member of the @code{wheel} group
174 although, the @code{root} user, who may be a member of the @code{wheel} group,
175 is allowed read-only access. The SHA-256 @acronym{TLS} fingerprint hash
176 @code{#ABCDEF} is also allowed. No users other than an @var{invoking_user}
177 are allowed access to the @code{child} element. When a command path is found
178 in the @var{_acl} then the local client command name must match one of the
179 command paths in the @var{_acl}. The ability to specify read and write access
180 for each user in an @acronym{ACL} is a feature planned for a later release.
182 @c Node, Next, Previous, Up
183 @node Cache Control, Invoking, Access Control, Top
184 @chapter Cache Control
188 While @command{pwmd} has its own cache settings for an @acronym{XML} document,
189 @command{gpg-agent} has cache settings for the keys used for crypto operations
190 of a data file. Specifically the @option{ignore-cache-for-signing},
191 @option{default-cache-ttl} and @option{max-cache-ttl} options. These
192 @command{gpg-agent} options may need to be adjusted depending on your usage
193 needs. For example, the @code{OPEN} command may not require a passphrase to
194 open a data file due to the gpg-agent having a cached key even though the
195 @code{ISCACHED} command returns an error indicating the data file is not
196 cached; which usually means a passphrase would be required. Keys for symmetric
197 data files are never kept in the @command{gpg-agent} cache regardless of
198 @command{gpg-agent} cache settings.
200 A copy-on-write operation is done for commands that modify the document; the
201 client that invoked the command will work on a copy of the in-memory document.
202 The first client to @code{SAVE} the changes to disk will require other clients
203 to reopen the data file due to the checksum being updated.
205 @c Node, Next, Previous, Up
206 @node Invoking, Configuration, Cache Control, Top
207 @chapter Invoking @command{pwmd}
210 @command{pwmd} uses GpgME for encryption, decryption and signing of the
211 OpenPGP data file. GpgME itself makes use of @command{gpg} for these
212 operations so some configuration of @command{gpg} may be needed. Pwmd spawns
213 a separate @command{gpg-agent} process when @var{gpg_homedir}
214 (@pxref{Configuration}) is not set to an instance of an already running
215 gpg-agent. Any @command{gpg} configuration options that you need set should be
216 put in @var{~/.pwmd/.gnupg/gpg.conf} or the @var{gpg.conf} file located in
217 @var{gpg_homedir}. The same is true for the @var{gpg-agent.conf} file to set
218 any required @command{gpg-agent} options.
220 It is recommended to pass the @option{--allow-preset-passphrase}
221 option to @command{gpg-agent}. Doing so allows @command{pwmd}
222 cache pushing on startup. It is also recommended to pass the
223 @option{--allow-loopback-pinentry} to @command{gpg-agent} (this is the default
224 as of gnupg-2.1.15). This option allows a passphrase to be inquired from
225 @command{pwmd} when a @command{pinentry} is unavailable to the client
228 If you would like to use a keypair from your default gnupg keyring located in
229 ~/.gnupg, but would still like to use a separate gpg-agent process (the
230 default), you would need to first export the public key from the default
231 keyring then import it into the keyring that pwmd uses. You can do this by
232 first exporting the public key, then use the @option{--homedir ~/.pwmd/.gnupg}
233 option of @command{gpg} to import it into the new keyring. For private keys,
234 you would need to copy the private key associated with the exported public key
235 to @var{~/.pwmd/.gnupg/private-keys-v1.d}. If the private key is stored on
236 a smartcard you can also use the @code{KEYINFO --learn} command
239 @cindex Running @command{pwmd}
240 @command{pwmd} is executed as follows:
243 pwmd @var{options} [ file1 ] [ @dots{} ]
246 Non-option arguments are data files to cache upon startup. When the data file
247 requires a passphrase for decryption a @command{pinentry} will prompt either
248 on the current TTY or from an X11 window when the @env{DISPLAY}
249 environment variable is set. @xref{Pinentry}.
253 The following command line options are supported:
257 @item --debug protocol:level[,protocol:level]
258 Enable debugging output. This option can output sensitive information such as
259 passphrases and secret keys so care should be taken where the output gets
260 written to. The @var{protocol} is a single character representing the protocol
261 to log. Use @code{a} for @code{libassuan} with @var{level} being one or more
262 character flags: @code{i} for init, @code{x} for context, @code{e} for engine,
263 @code{d} for data, @code{s} for system IO or @code{c} for control. To debug
264 @code{gpgme} use @code{g} as the @var{protocol} with @var{level} being an
265 integer from @code{1} to @code{9}. To enable @acronym{TLS} debugging output
266 use @code{t} as the @var{protocol} with @var{level} being an integer from
267 @code{1} to @code{9}. A value over @code{10} will enable all @acronym{TLS}
268 debugging output with @code{1} being the default.
270 @item --homedir directory
271 The root directory where pwmd will store its data and temporary files. The
272 default is @file{~/.pwmd}.
274 @item --rcfile, -f rcfile
275 Specify an alternate configuration file. The default is
276 @file{~/.pwmd/config}.
279 Terminate an existing instance of pwmd. The process to terminate is determined
280 from the @option{--homedir} and @option{--rcfile} options.
282 @item --import, -I filename|-
283 Imports the @acronym{XML} @var{filename}. When @var{filename} is @code{-} the
284 @acronym{XML} is read from @code{stdin}. The @acronym{XML} file should be in conformance to
285 the @command{pwmd} @acronym{DTD} (@pxref{Introduction}). You will be prompted for
286 a passphrase to encrypt with. The output is written to the filename specified
287 with @option{--outfile}. To make use of the imported data, place the output
288 file in @file{~/.pwmd/data}.
290 @item --output, -o filename|-
291 When importing, write the encrypted data file to @var{filename}. When
292 @var{filename} is @code{-} output will be written to @code{stdout}.
294 @item --passphrase-file, -k filename"
295 Obtain the passphrase to use when importing from the specified @var{filename}.
297 @item --keyid fingerprint[,fingerprint,@dots{}]
298 Specifies the fingerprint of the encryption key to use as a recipient when
299 importing. When not specified a new key-pair will be created.
301 @item --sign-keyid fingerprint
302 Specifies the fingerprint of the signing key to use for signing of the data
303 file when importing. When not specified the signing key of the generated
304 key-pair or the signing key of the @option{--keyid} option will be used.
306 @item --symmetric, -s
307 Use symmetric or conventional encryption rather than pubic key encryption when
308 importing. Signing is still possible by using the @option{--sign-keyid}
309 option. By default no signing is done when specifying this option.
311 @item --userid string
312 When importing, the user id used to identify the generated key. This should be
313 in the form @code{First Last <email>}.
316 When importing, the algorithm to use when generating the new key pair. The
317 default is determined by @command{gpg}.
319 @item --expire seconds
320 When importing, the time, in seconds since epoch, when the generated key will
321 expire. Specifying @code{0} will never expire the key. The default is three
324 @item --no-passphrase
325 When importing, don't require a passphrase for the generated key.
328 Disable the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and @code{DUMP}
329 protocol commands (@pxref{Commands}). This overrides any
330 @var{disable_list_and_dump} configuration parameter (@pxref{Configuration}).
333 Run as a foreground process and do not fork into the background.
336 Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
337 if an error occurred due to an invalid passphrase or other error.
340 Show the version, copyright and compile time features and exit.
343 Print a summary of options.
347 @c Node, Next, Previous, Up
348 @node Configuration, TLS, Invoking, Top
349 @chapter @command{pwmd} configuration file options
351 @mansect configuration file
352 If no configuration file is specified with the @command{pwmd} @option{-f}
353 command line option, @command{pwmd} will read @file{~/.pwmd/config} if it
354 exists, and if not, will use defaults. Blank lines and lines beginning with
355 @samp{#} are ignored. Some parameters may have data file specific settings by
356 placing them in a file section. A file section is declared by surrounding the
357 filename with braces (i.e., @samp{[filename]}). Global options may be
358 specified in the @code{global} section (e.g., @samp{[global]}) and are the
359 default options for new or unspecified file sections.
361 A tilde @code{~} will be expanded to the home directory of the user starting
362 @command{pwmd} when contained in a parameter whose value is a filename.
364 @cindex Reloading the configuration file
365 The configuration file can be reloaded by sending the @emph{SIGHUP} signal to
366 a @command{pwmd} process. Some security sensitive settings may not be changed
367 until @command{pwmd} is stopped then restarted.
369 @cindex Global configuration options
370 The following options are only for use in the @code{[global]} section:
374 @item socket_path = /path/to/socket
375 Listen on the specified socket. The default is @file{~/.pwmd/socket}.
378 @item socket_perms = octal_mode
379 Permissions to set after creating the socket. This will override any
380 @cite{umask(2)} setting.
383 @item backlog = integer
384 The number of connections to queue. When this limit is reached then new
385 connections will be refused. The default is @code{128}.
387 @cindex invoking_user
388 @item invoking_user = [-!]user,[-!]@@group,[-!]#SHA-256,@dots{}
389 This parameter is not to be confused with setuid or setguid upon startup. It's
390 syntax is the same as the @code{allowed} parameter except that it is a list of
391 local usernames, group names and @acronym{TLS} fingerprint hashes that may use the
392 @command{XPATH}, @command{XPATHATTR} and @command{DUMP} commands (except when
393 disabled with the @code{disable_list_and_dump} option) and also who may modify
394 elements that have no @code{_acl} attribute or is not listed in an
395 @code{_acl}. It is similar to the system administrator root account but for a
396 data file and element paths (@pxref{Access Control}). The default is specified
397 at compile-time and also by default is the user @code{nobody}.
399 @cindex invoking_file
400 @item invoking_file = filename
401 A file containing one entry per line. An entry has the same syntax as the
402 @code{invoking_user} parameter. When both this parameter and the
403 @code{invoking_user} parameter are specified then the @code{invoking_user}
404 parameter will behave as if the @code{invoking_file} entries have been
405 appended to the @code{invoking_user} parameter value.
408 @item strict_open = boolean
409 When @code{true}, disallow creation of a new data file when the current client
410 is not an @code{invoking_user}. The default is @code{false}.
413 @item strict_kill = boolean
414 When @code{false}, the @code{KILL} command (@pxref{KILL}) will allow killing
415 another client that is not of the same @code{UID} or @acronym{TLS} fingerprint of
416 the current client and when not an @code{invoking_user}. The default us
420 @item allowed = [-!]user,[-!]@@group,[+,][-!]#SHA-256,[-!]/path/to/exec[@dots{}]
421 A comma separated list of local user names, group names or @acronym{TLS}
422 fingerprint SHA-256 hashes (in the case of a remote client) which are
423 allowed to connect. Groups should be prefixed with a @samp{@@}. When not
424 specified only the user who started @command{pwmd} may connect. An entry in
425 the list may be prefixed with a @code{-} or @code{!} to prevent access. The
426 order of the list is important since a user may be a member of multiple
429 Connections from local clients may also be limited by command name. A command
430 name is the full path to the execuatble on the filesystem. The command check
431 is done after all other user and group name checks. When no command is
432 specified all commands are allowed. This feature is ignored when the
433 connecting client is not of the same @acronym{UID} as the user that invoked
436 This parameter may also be specified in a filename section to allow or deny a
437 client to @code{OPEN} (@pxref{OPEN}) a data file. It also affects the cache
438 commands @code{CLEARCACHE} (@pxref{CLEARCACHE}) and @code{CACHETIMEOUT}
439 (@pxref{CACHETIMEOUT}). When not specified in a file section, any client
440 allowed to connect may also open any filename provided they can decrypt it.
441 Note that when specified in a file section that any @var{allowed} parameter in
442 the @code{global} seciton is not considered.
444 The following example would deny all users in group @code{primary} but
445 allow @code{username} who may be a member of @code{primary}. It will also
446 allow any @acronym{TLS} client except for the client with @acronym{TLS}
447 fingerprint hash @code{#ABCDEF}. For local connections, the connecting client
448 must be using the /usr/bin/pwmc program:
451 allowed=-@@primary,username,+,!#ABCDEF,/usr/bin/pwmc
455 @item allowed_file = filename
456 A file containing one entry per line. An entry has the same syntax as the
457 @code{allowed} parameter except that a line beginning with a semicolon is
458 ignored. When both this parameter and the @code{allowed} parameter are
459 specified then the @code{allowed_file} entries will be appended to the
460 @code{allowed} parameter value.
463 @item encrypt_to = boolean
464 When @code{true} and @command{SAVE}'ing a data file, allow @command{gpg} to
465 append it's configured key to the list of recipients. The default is
466 @code{false} meaning that only keys specified with @command{SAVE}
467 @option{--keyid} are recipients.
470 @item always_trust = boolean
471 When @code{true}, allow encrypting to untrusted recipients or public
472 encryption keys. If you receive an error when @command{SAVE}'ing stating that
473 the public key is unusable, either enable this option or edit the keys' trust
476 gpg --homedir ~/.pwmd/.gnupg --edit-key <fingerprint>
478 The default is @code{false}.
481 @item gpg_homedir = path
482 The location where @command{gpg} will store its public and private keys and
483 configuration. The default is @file{HOMEDIR/.gnupg} where @var{HOMEDIR} is the
484 default (@file{~/.pwmd}) or the value specified on the command line with the
485 @option{--homedir} command line option (@pxref{Invoking}). If you want to use
486 your standard @command{gpg} keyring then set this to @file{~/.gnupg}. Note
487 that a new instance of @command{gpg-agent} will be started when @emph{not}
488 using the standard keyring and that any configuration options for
489 @command{gpg-agent} will need to placed in
490 @file{HOMEDIR/.gnupg/gpg-agent.conf}.
492 @cindex disable_mlockall
493 @item disable_mlockall = boolean
494 When set to @code{false}, @cite{mlockall(2)} will be called on startup. This
495 will use more physical memory but may also be more secure since no swapping to
496 disk will occur. The default is @var{true}. If possible, use an encrypted swap
497 file or partition and leave this set to @var{true}.
500 @item log_path = /path/to/logfile
501 Logs informational messages to the specified file. The default is
504 @cindex enable_logging
505 @item enable_logging = boolean
506 Enable or disable logging to @var{log_path}. The default is @code{false}.
509 @item log_keepopen = boolean
510 When set to @code{false}, the log file specified with @var{log_path} will be
511 closed after writing each line. The default is @code{true}.
514 @item syslog = boolean
515 Enable logging to @cite{syslog(8)} with facility @emph{LOG_DAEMON} and priority
516 @emph{LOG_INFO}. The default is @code{false}.
519 @item log_level = level
520 When @code{0}, only connections and errors are logged. When @code{1}, data
521 file recipients and signers are logged during @code{OPEN} (@pxref{OPEN}) and
522 @code{SAVE} (@pxref{SAVE}). When @code{2}, client commands are also logged.
523 The default is @code{0}.
526 @item kill_scd = boolean
527 Attempt to kill @command{scdaemon} after a client disconnects. The default is
530 @cindex disable_list_and_dump
531 @item disable_list_and_dump = boolean
532 When @code{true} the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and
533 @code{DUMP} protocol commands (@pxref{Commands}) will be disabled.
536 @item cache_push = file1,file2
537 A comma separated list of filenames to be cached upon startup. @command{pwmd}
538 will prompt for the passphrase for each file unless specified with
539 @var{passphrase_file} parameter in a matching file section.
542 @item priority = integer
543 The priority or niceness of the server. The default is inherited from the
547 @item lock_timeout = integer
548 The default timeout in tenths of a second before giving up while waiting for a
549 file lock and returning an error. The default is @code{50}.
553 @cindex Data file configuration options
557 The following options are defaults for new files when specified in the
558 @samp{global} section. When placed in a data file section they are options
559 specific to that data file only.
562 @cindex require_save_key
563 @item require_save_key = boolean
564 Require the passphrase needed for signing before writing changes of the
565 document to disk regardless of the key cache status. The default is
566 @code{true}. This option compliments @command{gpg-agent} option
567 @option{--ignore-cache-for-signing} and is used as a fail-safe.
570 @item backup = boolean
571 Whether to create a backup of the data file when saving. The backup filename
572 has the @file{.backup} extension appended to the opened file. The default is
575 @cindex cache_timeout
576 @item cache_timeout = seconds
577 The number of seconds to keep the cache entry for this file. If @code{-1}, the
578 cache entry is kept forever. If @code{0}, each time an encrypted file is
579 @code{OPEN}ed (@pxref{OPEN}) a passphrase will be required. The default
580 is @code{600} or 10 minutes.
582 @cindex passphrase_file
583 @item passphrase_file = /path/to/filename
584 Obtain the passphrase to open the data file from @var{filename}. If specified
585 in the @samp{global} section then the @var{passphrase_file} is a default for
586 all data files. Note that if a client changes the passphrase for this data
587 file then the @var{passphrase_file} will need to be updated with the new
590 @cindex recursion_depth
591 @item recursion_depth = integer
592 The maximum number of times to resolve a @code{_target} attribute for an
593 element in an element path (@pxref{Target Attribute}). An error is returned
594 when this value is exceeded. The default is @code{100} but can be disabled by
595 setting to @code{0} (@emph{not recommended}).
597 @item allowed = [-]user,[-]@@group,[!]#TLSFINGERPRINT,@dots{}
598 Same parameter value as the @code{allowed} parameter mentioned above in
599 the @samp{[global]} section but grants or denies a client from opening a
600 specific data file. The default is to allow any client that is allowed to
605 * TLS:: Remote connections over TLS.
606 * Pinentry:: Configuration file and defaults.
609 @node TLS, Pinentry, Configuration, Configuration
610 @chapter Configuring remote connections over TLS.
614 In addition to connecting to @command{pwmd} via a Unix Domain Socket, remote
615 connections can also be made to @command{pwmd} over @acronym{TLS}.
616 Authentication is done by using X.509 client certificates that are signed with
617 the same Certificate Authority (CA) as the server certificate.
619 The CA certificate is expected to be found in
620 @file{~/.pwmd/ca-cert.pem} while the @command{pwmd} server certificate and key
621 file should be put in @file{~/.pwmd/server-cert.pem} and
622 @file{~/.pwmd/server-key.pem}, respectively.
624 See the documentation of @command{certtool} or @command{openssl} for details
625 about creating self-signed certificates.
627 The following @acronym{TLS} configuration options are available:
631 @item enable_tcp = boolean
632 Whether to enable @acronym{TCP}/@acronym{TLS} server support. If enabled, both @acronym{TCP} and the local
633 unix domain socket will listen for connections. The default is
637 @item tcp_port = integer
638 The @acronym{TCP} port to listen on when @var{enable_tcp} is @code{true}. The default is
642 @item tcp_bind = string
643 The internet protocol to listen with. Must be one of @code{ipv4}, @code{ipv6}
644 or @code{any} to listen for both IPv4 and IPv6 connections. The default is
647 @cindex tcp_interface
648 @item tcp_interface = string
649 Only useful if running as root.
652 @item tls_timeout = seconds
653 The number of seconds to wait for a read() or write() call on a
654 @acronym{TLS} client file descriptor to complete before returning an
655 error. The default is @var{300}.
657 @cindex keepalive_interval
658 @item keepalive_interval = seconds
659 Send a keepalive status message to an idle remote client. An idle
660 client is one that is not in a command. The purpose of this status
661 message is to disconnect a hung remote client and release any file mutex
662 locks so another client may open the same data file. The default is @code{60}.
664 @cindex tcp_require_key
665 @item tcp_require_key = boolean
666 When @code{true}, require the remote client to provide the passphrase to open
667 a data file even if the file is cached. This option is a default for all
668 files when specified in the @samp{[global]} section. The default is
671 @cindex tls_cipher_suite
672 @item tls_cipher_suite = string
673 The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
674 information about the format of this string. The default is
675 @code{SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1:-AES-128-CBC:-AES-256-CBC}.
677 @cindex tls_dh_params_file
678 @item tls_dh_params_file = filename
679 The PEM encoded filename containing DH parameters. If not specified
680 then DH algorithms will not be available to the client. See the
681 @command{openssl dhparam} or @command{certtool} manual pages for details about
682 generating this file.
684 Note that SIGHUP will not reload this file once @acronym{TLS} support has been enabled.
685 You will need to restart @command{pwmd} for changes to take effect.
688 @item tls_use_crl = boolean
689 When @code{true}, enable the use of @option{tls_crl_file}. The default is
693 @item tls_crl_file = filename
694 This file is an X.509 Certificate Revocation List (@acronym{CRL}) and can be
695 used to deny clients by adding client certificates to it. @command{pwmd} will
696 need to be restarted to recognize any changes to this file. When not
697 specified the default of @file{~/.pwmd/crl.pem} will be used when
698 @option{tls_use_crl} is @code{true}.
701 @item tls_ca_file = filename
702 The filename of the @acronym{CA} certificate to use. When not specified the
703 default of @file{~/.pwmd/ca-cert.pem} will be used.
705 @cindex tls_server_cert_file
706 @item tls_server_cert_file = filename
707 The filename of the server certificate to use. When not specified the default
708 of @file{~/.pwmd/server-cert.pem} will be used.
710 @cindex tls_server_key_file
711 @item tls_server_key_file = filename
712 The key filename of the server certificate to use. When not specified the
713 default of @file{~/.pwmd/server-key.pem} will be used.
717 @node Pinentry, Commands, TLS, Configuration
718 @chapter Pinentry configuration
720 The @command{pinentry} program is used to prompt the user for passphrase
721 input or as a confirmation dialog; it needs to know where to prompt for
722 the input; from a terminal or an X11 display.
724 It is the responsibility of the client to tell @command{pinentry} about the
725 terminal or X11 display before requiring the input. This is done with the
726 @command{OPTION} command (@pxref{OPTION}) to either set or unset needed
727 @command{pwmd} environment variables and by using the
728 @command{gpg-connect-agent} program. Please read it's documentation about the
729 @emph{UPDATESTARTUPTTY} command.
732 @c Node, Next, Previous, Up
733 @node Commands, Bulk Commands, Pinentry, Top
734 @chapter Protocol commands and their syntax
736 @include commands.texi
738 @c Node, Next, Previous, Up
739 @node Bulk Commands, Status Messages, Commands, Top
740 @chapter Running multiple commands in sequence
741 Multiple commands may be run in sequence by using the @code{BULK} command
742 (@pxref{BULK}). Using this feature may speed up remote connections since less
743 socket IO is needed. The @code{BULK} command uses an @emph{INQUIRE} to obtain
744 an canonical s-expression of commands to be run. The s-expression syntax is as
748 (2:id<I>:<id> <P>:<prot><D>:[<data>] [2:rc<R>:<code>[|<code>@dots{}2:id@dots{}| 2:id@dots{}])
751 Each token is prefixed with an unsigned integer that specifies the length of
752 the token, followed by a colon '@code{:}', followed by the token itself. Pwmd
753 uses token pairs to create a @emph{name=value} relationship. Whitespace is
754 allowed between token pairs. For example, the following is valid:
757 ( 2:id 7:FirstID 4:LIST0: 2:rc 1:0 (2:id6:Second 7:GETINFO7:version))
760 The @code{id} token begins a new command and requires an @var{<id>} token
761 of length @var{<I>} to uniquely identify this command. The next token pair is
762 the protocol command name, without any command arguments, of length @var{<P>}
763 to run followed by a colon '@code{:}', followed by the command @var{<prot>}
764 itself, followed by the length @var{<D>} of both command arguments and data,
765 followed by a colon '@code{:}' and finally the @var{<data>} itself. If no
766 arguments or data are needed for the command, set the length of the data
767 @var{<D>} to @code{0} and append the required colon '@code{:}'.
769 A new command enclosed in parentheses may be run when the previous command
770 returns an error code that matches the @var{<code>} token of length @var{<R>}
771 by appending @var{rc} tokens to the end of the previous commands @var{<data>}
772 token. You may also test another return code for the previous command by
773 placing the next @var{rc} token at the end of the closing parentheses of the
774 previous return code command.
776 Multiple @code{rc} @var{code}'s may be specified for a single command by
777 separating them with a pipe @code{|} character. This lets you specify an
778 @emph{if-this-and-that} expression for a commands return code.
780 If another command is to be run after the previous and does not specify an
781 @var{rc} token, the return value is ignored for the previous command and the
782 next command is run. There is no limit on the number of commands or
783 sub-commands except for system memory.
785 After inquiring the commands to be run, @code{BULK} will run each command with
786 @var{<data>} as its argument and store the result code and data of the command
787 in a @code{bulk-result} canonical s-expression of the syntax:
790 (11:bulk-result2:id<I>:<id>2:rc<R>:<code><D>:[<data>][2:id@dots{}])
793 The @code{11:bulk-result} token begins the result of all commands. The
794 @var{<id>} token of length @var{<I>} is the same that was associated with the
795 command from the @emph{INQUIRE}'d syntax and is prefixed with @code{2:id}. The
796 return code of the command is prefixed with @code{2:rc} followed by the length
797 @var{<R>} of the unsigned integer @var{<code>} then the return @var{<code>}
798 itself. If the command returned any @var{<data>}, it is prefixed with a
799 length @var{<D>} and immediately following the return @var{<code>}. Otherwise,
800 @var{<D>} will be @code{0} and followed by a colon '@code{:}'.
803 @c Node, Next, Previous, Up
804 @node Status Messages, Target Attribute, Bulk Commands, Top
805 @chapter Status messages and their meanings
806 Some commands send status messages to inform the client about certain
807 operations or as a progress indicator. Status messages begin with a
808 @code{KEYWORD} followed by a status description for status messages that
809 require it. What status messages are sent, when, and how often may depend on
810 configuration settings (@pxref{Configuration}).
812 @multitable @columnfractions .20 .25 .55
813 @headitem Message @tab Parameters @tab Description
816 @tab @code{<integer>}
817 @tab The number of cached documents. Sent to each client after connecting
818 (@pxref{GETINFO}) and to every client after a cache modification.
822 @tab @code{<integer>}
823 @tab The number of connected clients (@pxref{GETINFO}). Sent to each client
824 when another client either connects or disconnects.
829 @tab Sent to the current client during a decrypt operation. How often this
830 status message is sent is determined by the @code{keepalive_interval}
831 (@pxref{Configuration}) setting.
836 @tab Sent to the current client during an encrypt operation. How often this
837 status message is sent is determined by the @code{keepalive_interval}
838 (@pxref{Configuration}) setting.
842 @tab @code{[<sigkey_fpr> <pubkey_fpr>]}
843 @tab Sent to the current client during key generation. How often this
844 status message is sent is determined by the @code{keepalive_interval}
845 (@pxref{Configuration}) setting. The @var{sigkey_fpr} and @var{pubkey_fpr}
846 parameters are added when key generation has completed.
849 @cindex INQUIRE_MAXLEN
851 @tab Sent to the current client from @command{gpg-agent} when inquiring data.
852 This specifies the maximum number of bytes allowed for the client to send and
853 should not be exceeded.
858 @tab Sent to each idle client every @var{keepalive_interval}
859 (@pxref{Configuration}) seconds.
864 @tab Sent to the current client when another client is holding the lock for
865 the mutex associated with a data file. How often this status message is sent
866 is determined by the @code{keepalive_interval} (@pxref{Configuration})
872 @tab Sent to the current client when the opened (@pxref{OPEN}) file does not
873 exist on the file-system.
877 @tab @code{<client_id>}
878 @tab Sent to each client with the same opened data file as @var{client_id} to
879 inform them of modifications that were written to disk using the
880 @command{SAVE} command.
884 @tab @code{<sent> <total>}
885 @tab Sent to the current client when transferring data. It has two space
886 delimited arguments. The first being the current amount of bytes transferred
887 and the other being the total bytes to be transferred. Note that since version
888 @code{3.1.1} of @command{pwmd} this status message is sent only once and
889 before the transfer begins with the @var{total} argument set to the size of the
890 data and the @var{sent} argument set to @code{0} leaving it to the client to
891 determine the progress of the transfer as the data is received.
895 @tab @code{<client_id> <state>}
896 @tab Sent to each client to indicate that @var{client_id} has changed to
897 @var{state} (@pxref{GETINFO} for client states). For a client to receive
898 another clients state the option @var{CLIENT-STATE} must be set
903 @tab @code{<epoch_seconds> <epoch_future>|0}
904 @tab Sent to the current client when @code{GET} (@pxref{GET}) encounters an
905 @code{_expire} (@pxref{Other Attributes}) attribute that is in the past or when
906 @code{STORE} (@pxref{STORE}) updates the @code{_expire} attribute from the
907 @code{_age} attribute value. The second field will be @code{0} when @code{GET}
908 sends this status message. Otherwise the second field is the time the next
911 @item PASSPHRASE_HINT
912 @cindex PASSPHRASE_HINT
913 @tab <keyid> <userid>
914 @tab Forwarded from @code{GpgME}. Contains information that is useful in a
915 @command{pinentry}. Only sent when pinentry is disabled (@pxref{OPTION}).
917 @item PASSPHRASE_INFO
918 @cindex PASSPHRASE_INFO
920 @tab Forwarded from @code{GpgME}. Contains information that is useful in a
921 @command{pinentry}. Only sent when pinentry is disabled (@pxref{OPTION}).
926 @tab Sent to each @acronym{TLS} client just before performing a cipher renegotiation
927 after a SIGHUP signal was received.
931 @tab @code{BEGIN|END <command id>}
932 @tab Sent to the current client before and after the @code{BULK} command
933 (@pxref{BULK}) runs each command. The @var{<command id>} is the same that was
934 associated with the command in the s-expression syntax.
937 @c Node, Next, Previous, Up
938 @node Target Attribute, Other Attributes, Status Messages, Top
939 @chapter The @code{target} attribute
940 @cindex target attribute
941 A @emph{case sensitive} attribute named @code{_target} is treated specially
942 when found in each element of an element path. This attribute, like other
943 element attributes, is created or modified with the @code{ATTR} command
944 (@pxref{ATTR}). The value of this attribute is an existing element path
945 somewhere in the document. If you are familiar with @acronym{XML} entities or
946 maybe the HTML @code{id} or @code{_target} attributes or a symbolic link
947 in a file-system, you may find this attribute behaves similar to any of those.
949 To create a @code{_target} attribute use the following syntax:
952 ATTR SET _target element[@code{TAB}child[..]] element[@code{TAB}child[..]]
955 Note the single space between the two element paths. The first element path is
956 where the @code{_target} attribute will be created. If the element path does
957 not exist then it will be created. This is the only time the @code{ATTR}
958 (@pxref{ATTR}) command will create elements. The attribute is created in the
959 final element of the element path.
961 The second element path is the destination of where you want the first element
962 path to resolve to. When an element path is passed as an argument to a
963 protocol command @command{pwmd} looks for a @code{_target} attribute when
964 resolving each element and, if found, "jumps" to the attribute value and
965 continues resolving any remaining elements a commands element path.
967 When an element of a element path is removed that a @code{_target} attribute
968 resolves to then an error will occur when trying to access that element. You
969 may need to either update the @code{_target} attribute value with a new element
970 path or remove the attribute entirely.
972 Clients should be careful of creating @code{_target} loops, or targets that
973 resolve to themselves. See the @var{recursion_depth} in @ref{Configuration}
976 The @code{REALPATH} command (@pxref{REALPATH}) can be used to show the element
977 path after resolving all @code{_target} attributes.
979 @emph{Note that when setting this attribute any children of the element will
983 @c Node, Next, Previous, Up
984 @node Other Attributes, Key Expiration, Target Attribute, Top
985 @chapter Other special attributes
986 @cindex special attributes
987 In addition to the @code{_target} attribute (@pxref{Target Attribute}), there
988 are a few other attributes that are specially handled by @command{pwmd}. The
989 first is the @code{_ctime} attribute which is set to the current time when an
990 element is created. Next is the @code{_mtime} attribute which is created when
991 an element is created and also updated when an element is modified. Neither of
992 these attributes may be modified by the client. The @code{_acl} attribute
993 controls access to the element, albeit modifying or accessing element content,
994 or descending into child elements. @xref{Access Control} for details. The
995 @code{_name} attribute contains the name of an element.
997 The above mentioned attributes are considered reserved attribute names.
998 Reserved attributes are treated specially when a @code{_target} attribute is
999 found for the current element. The @code{ATTR LIST} command will show these
1000 attribute values for the current element and not the attribute values for the
1001 resolved @code{_target} element. All other non-reserved attributes for the
1002 resolved @code{_target} are appended to the @code{ATTR LIST} command output.
1003 Other @code{ATTR} commands (@pxref{ATTR}) behave as usual. You can, for
1004 example, @code{ATTR DELETE} a non-reserved attribute for an element that
1005 contains a @code{_target} attribute. The resolved target elements' attribute
1006 will be removed rather than the element containing the @code{_target}
1009 Another specially handled attribute is the @code{_expire} attribute. This
1010 attribute value, like the @code{_ctime} and @code{_mtime} attributes, is a
1011 timestamp. But this timestamp is usually in the future and for use with the
1012 @code{GET} (@pxref{GET}) and @code{STORE} (@pxref{STORE}) commands. When the
1013 @code{GET} command is issued, it checks for an @code{_expire} attribute an
1014 compares its' value with the current time. If the @code{_expire} timestamp is
1015 in the past then a status message is sent (@pxref{Status Messages}) to inform
1016 the client that the element content should be updated. When the content for
1017 an element containing an @code{_expire} attribute is set when using the
1018 @code{STORE} command, the value of the @code{_age} attribute is added to the
1019 current time and the @code{_expire} attribute value is updated. When no
1020 @code{_age} attribute is found, no modification is done of the @code{_expire}
1024 @c Node, Next, Previous, Up
1025 @node Key Expiration, Signals, Other Attributes, Top
1026 @chapter Key Expiration
1027 @cindex key expiration
1028 When a key used for signing a data file has expired there is no indication
1029 until the next @code{SAVE} command is sent. The command will fail since one
1030 cannot sign the data file with an expired key. The client will need to either
1031 use a different key for signing by either specifying an existing non-expired
1032 key, generate a new key, or change the expire time of the existing key with
1035 To change the expiration of the currently used signing key with @command{gpg},
1036 use the @code{KEYINFO} command (@pxref{KEYINFO}) to obtain the fingerprint of
1037 the signing key of the current data file, then change the expire time with
1041 gpg --homedir ~/.pwmd/.gnupg --edit-key <fingerprint>
1044 Then use the @code{expire} command to set the new key expire date. When
1045 finished, use the @code{save} command to save your changes.
1048 @c Node, Next, Previous, Up
1049 @node Signals, Index, Key Expiration, Top
1050 @chapter Recognized signals
1053 Sending the @emph{SIGHUP} signal to a @command{pwmd} process will reload the
1054 configuration file and sending @emph{SIGUSR1} will clear the entire file
1069 @c Node, Next, Previous, Up
1070 @node Index, , Signals, Top