1 >\input texinfo @c -*-texinfo-*-
16 @dircategory Miscellaneous
18 * pwmd: (pwmd). Password Manager Daemon
23 @subtitle Commands and syntax
27 @c Node, Next, Previous, Up
31 This manual documents @command{pwmd} version 3.0 protocol commands and
36 * Introduction:: Overview of pwmd.
37 * Invoking:: Command line options.
38 * Configuration:: Configuration file options.
39 * Commands:: Protocol commands.
40 * Status Messages:: Status lines and their meaning.
41 * Target Attribute:: A kind of symbolic link.
42 * Signals:: Signals known to pwmd.
43 * Concept Index:: Index of concepts.
46 @c Node, Next, Previous, Up
47 @node Introduction, Invoking, , Top
48 @chapter Overview of @command{pwmd}
53 \- a univeral data server
59 [options] [file1] [...]
63 @command{pwmd} or @dfn{Password Manager Daemon} is a server that
64 applications connect to and send commands to store and retrieve data
65 that is saved in an encrypted @abbr{XML} document.
67 The server uses the Assuan protocol (@inforef{Implementation,,assuan}) which
68 is the same used by @command{gpg-agent}, @command{pinentry} and
69 @command{scdaemon}. It also uses @cite{libgpg-error} for error reporting with
70 the error source set as @var{GPG_ERR_SOURCE_USER_1}.
73 It is recommended to read the texinfo documentation of @command{pwmd}
74 since it contains protocol commands and syntax and other details not
79 The @abbr{XML} document uses the following @abbr{DTD}:
84 <!ELEMENT pwmd (element*)>
85 <!ATTLIST element _name CDATA #REQUIRED>
89 The @code{pwmd} element is the document root node while all other elements
90 of the document have the name @code{element} with an attribute @code{_name}
91 whose value uniquely identifies the element at the current element tree depth.
92 It is done this way to avoid @abbr{XML} parsing errors for commonly used
93 characters. A @abbr{URL} for example would be an invalid @abbr{XML} element
94 since the @abbr{URI} contains a @samp{:} which is also the @abbr{XML}
97 As mentioned, an element name must be unique for the current element tree
98 depth. You cannot have two elements containing the same @code{_name} attribute
99 value. @command{pwmd} will stop searching for an element of an @emph{element
100 path} at the first match then continue searching for the next element of the
101 element path beginning at the child node of the matched element.
103 An @emph{element path} is a @key{TAB} delimited character string where each
104 @key{TAB} separates each element in the path. For example, the element path
105 @code{a@key{TAB}b@key{TAB}c} has the following @abbr{XML} document structure:
112 [... element value or content ...]
119 The only restriction of an element name is that it contain no whitespace
120 characters. It also cannot begin with a @samp{!} since this character is
121 reserved for the @code{target} attribute. @xref{Target Attribute}.
123 @c Node, Next, Previous, Up
124 @node Invoking, Configuration, Introduction, Top
125 @chapter Invoking @command{pwmd}
129 When @command{pwmd} is started with the @option{--use-agent} command
130 line option then @command{pwmd} will use @command{gpg-agent} for key
131 generation, decryption, signing and caching of passphrases as the
132 default rather than symmetrically encrypted data files.
133 @command{gpg-agent} must be running prior to @command{pwmd} startup when
134 this option is enabled. The @env{GPG_AGENT_INFO} environment variable is
135 set by @command{gpg-agent} and @command{pwmd} uses this variable to
136 determine where the @command{gpg-agent} socket is listening for
139 It is recommended to pass the @option{--allow-preset-passphrase}
140 command line option to @command{gpg-agent}. Doing so allows @command{pwmd}
141 cache pushing on startup. It is also recommended to pass the
142 @option{--allow-loopback-pinentry} to @command{gpg-agent}. This option allows
143 a passphrase to be inquired from @command{pwmd} when a @command{pinentry} is
144 unavailable to the client.
146 @cindex Running @command{pwmd}
147 @command{pwmd} is executed as follows:
150 pwmd @var{options} [ file1 ] [ @dots{} ]
153 Non-option arguments are data files to cache on startup. When the data file
154 requires a passphrase for decryption a @command{pinentry} will prompt either
155 on the current @abbr{TTY} or from an X11 window when the @env{DISPLAY}
156 environment variable is set.
160 The following command line options are supported:
164 @item --homedir directory
165 The root directory where pwmd will store its data and temporary files. The
166 default is @file{~/.pwmd}.
168 @item --rcfile, -f rcfile
169 Specify an alternate configuration file. The default is
170 @file{~/.pwmd/config}.
173 Enable the use of @command{gpg-agent} and add support for data files
174 encrypted with a keypair. Files previously handled by
175 @command{gpg-agent} when this option is not specified will no longer be
176 able to be opened and new data files are symmetrically or conventionally
177 encrypted and without a public and private key. If
178 specified, both data file types are supported.
180 @item --import, -I filename
181 Imports an @abbr{XML} file. The @abbr{XML} file should be in conformance to
182 the @command{pwmd} @abbr{DTD} (@pxref{Introduction}). You
183 will be prompted for a passphrase to encrypt with. The output is written to
184 the filename specified with @option{--outfile}. To make use of the imported
185 data, place the output file in @file{~/.pwmd/data}.
187 @item --keyparam S-expression
188 The key parameters to use when generating a new key pair while importing an
189 @abbr{XML} file or when converting a @emph{version 2} data file. The argument
190 must be a valid S-expression (@inforef{S-expressions,, gcrypt}).
192 @item --keygrip hexstring
193 Specifies the hexadecimal encoded public key-grip to use for encryption when
194 importing or converting. When not specified a new key-pair will be created.
196 @item --sign-keygrip hexstring
197 Specifies the hexadecimal encoded public key-grip to use for signing of the
198 data file when importing or converting. When not specified the generated
199 public key or the key specified with the @option{--keygrip} option will be
202 @item --passphrase-file, -k filename"
203 Obtain the passphrase from the specified filename.
205 @item --s2k-count iterations
206 The number of times to hash the passphrase when importing or converting. The
207 default is the gpg-agent calibrated value of the machine. When less than
208 @samp{65536} the default will be used.
210 @item --cipher-iterations iterations
211 The number of symmetric encryption iterations. The value is actually N+1. The
215 When importing, the cipher to use for data encryption. See the @var{cipher}
216 configuration parameter (@pxref{Configuration}) for available ciphers. The
217 default is @samp{aes256}.
219 @item --convert, -C filename
220 Converts a @command{pwmd} @emph{version 2} data file to a @emph{version 3}
221 data file. If encrypted, you will be prompted for a passphrase to use for
222 decryption unless @option{--passphrase-file} was specified. The converted data
223 file will be saved to the filename specified with @option{--outfile}. All
224 @option{--import} related options may also be used when converting.
226 @item --disable-dump, -D
227 Disable the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and @code{DUMP}
228 protocol commands (@pxref{Commands}). This overrides any
229 @var{disable_list_and_dump} configuration parameter (@pxref{Configuration}).
232 Run as a foreground process and do not fork into the background.
234 @item --ignore, --force
235 Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
236 if an error occurred do to an invalid passphrase or other error.
238 @item --debug-level keyword,keyword,...
239 Output libassuan @inforef{Top,,assuan} protocol IO with the comma
240 separated list of output keywords. Valid keywords are: @code{init},
241 @code{ctx}, @code{engine}, @code{data}, @code{sysio} and @code{control}.
244 Show the version, copyright and compile time features and exit.
247 Print a summary of options.
251 @c Node, Next, Previous, Up
252 @node Configuration, TLS, Invoking, Top
253 @chapter @command{pwmd} configuration file options
255 @mansect configuration file
256 If no configuration file is specified with the @command{pwmd} @option{-f}
257 command line option, @command{pwmd} will read @file{~/.pwmd/config} if it
258 exists, and if not, will use defaults. Blank lines and lines beginning with
259 @samp{#} are ignored. Some parameters may have data file specific settings by
260 placing them in a file section. A file section is declared by surrounding the
261 filename with braces (i.e., @samp{[filename]}). Global options may be
262 specified in a @samp{[global]} section and are the default options for new or
265 A tilde @key{~} will be expanded to the home directory of the invoking user
266 when contained in a parameter whose value is a filename.
268 @cindex Reloading the configuration file
269 The configuration file can be reloaded by sending the @emph{SIGHUP} signal to
270 a @command{pwmd} process.
272 @cindex Global configuration options
273 The following options are only for use in the @samp{global} section:
276 @item socket_path = /path/to/socket
277 Listen on the specified socket. The default is @file{~/.pwmd/socket}.
279 @item socket_perms = octal_mode
280 Permissions to set after creating the socket. This will override any
281 @cite{umask(2)} setting.
283 @item allowed = [-]user,[-]@@group,...
284 A comma separated list of local user names or group names allowed to connect
285 to the socket. Groups should be prefixed with a @samp{@@}. When not specified
286 only the invoking user may connect. A username or group name may also be
287 prefixed with a @key{-} to prevent access to a specific user or group
288 in the list. The order of the list is important since a user may be of
291 This parameter may also be specified in a filename section to allow or
292 deny a local user to @code{OPEN} (@pxref{OPEN}) a data file and has the
293 same default to allow only the invoking user.
295 The following example would deny all users in group @code{primary} but
296 allow @code{username} who is a member of @code{primary}:
299 allowed=-@@primary,username
302 @item disable_mlockall = boolean
303 When set to @code{false}, @cite{mlockall(2)} will be called on startup. This
304 will use more physical memory but may also be more secure since no swapping to
305 disk will occur. The default is @var{true}.
307 @item log_path = /path/to/logfile
308 Logs informational messages to the specified file. The default is
311 @item enable_logging = boolean
312 Enable or disable logging to @var{log_path}. The default is @code{false}.
314 @item log_keepopen = boolean
315 When set to @code{false}, the log file specified with @var{log_path} will be
316 closed after writing each line. The default is @code{true}.
318 @item syslog = boolean
319 Enable logging to @cite{syslog(8)} with facility @emph{LOG_DAEMON} and priority
320 @emph{LOG_INFO}. The default is @code{false}.
322 @item log_level = level
323 When @code{0}, only connections and errors are logged. When @code{1}, client
324 commands are also logged. When @code{2}, the command arguments are also logged.
325 The default is @code{0}.
327 @item use_agent = boolean
328 When true, enable @command{gpg-agent} support (@pxref{Invoking}).
330 @item agent_env_file = filename
331 A file containing the @env{GPG_AGENT_INFO} environment variable and value as
332 output by the @command{gpg-agent} @option{--write-env-file} command line
335 @item kill_scd = boolean
336 Kill @command{scdaemon} after each @code{OPEN} (@pxref{OPEN}) or @code{SAVE}
337 (@pxref{SAVE}) command.
339 @item require_save_key = boolean
340 Require the passphrase needed to open a data file before writing changes
341 of the documment to disk reguardless of the key cache status.
343 @item disable_list_and_dump = boolean
344 When @code{true}, the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and
345 @code{DUMP} protocol commands (@pxref{Commands}) will be disabled.
347 @item cache_push = file1,file2
348 A comma separated list of filenames that will be pushed into the file cache
349 upon startup. @command{pwmd} will prompt for the passphrase for each file unless
350 specified with the @var{passphrase} or @var{passphrase_file} parameters in a
351 matching file section.
353 @item priority = integer
354 The priority, or niceness, of the server. The default is inherited from the
357 @item cipher = algorithm
358 The default cipher to use for data encryption. The algorithm must be one of:
359 @code{aes128}, @code{aes192}, @code{aes256}, @code{serpent128},
360 @code{serpent192}, @code{serpent256}, @code{camellia128},
361 @code{camellia192}, @code{camellia256}, @code{3des}, @code{cast5},
362 @code{blowfish}, @code{twofish128} or @code{twofish256}. The default is
365 @item cipher_iterations = integer
366 The number of times to encrypt the XML data. This differs from the
367 @var{s2k_count} parameter which specifies the number of times to hash the
368 passphrase used to encrypt the data. The default is 0 although 1 iteration is
371 @item cipher_progress = integer
372 Send a progress message to the client after the specified amount of encryption
373 or decryption iterations have been done. The default is 2000.
375 @item keyparam = s-expression
376 The default key paramaters to use when generating a new key-pair. The
377 default is RSA with 2048 bits. Note that only RSA as the encryption
378 algorithm is supported at the moment. Both RSA and DSA keys may be used
381 @item pinentry_path = /path/to/pinentry
382 The location of the @command{pinentry} binary. This program is used to
383 prompt for a passphrase when not using @command{gpg-agent}. The default
384 is specified at compile time.
386 @item pinentry_timeout = seconds
387 The number of seconds to wait for a pinentry before giving up and
388 returning an error. This timeout value is used for both waiting for
389 another pinentry to complete and for the pinentry waiting for user input.
392 @cindex Data file configuration options
393 The following options are defaults for new files when specified in the
394 @samp{global} section. When placed in a data file section they are options
395 specific to that data file only.
398 @item backup = boolean
399 Whether to create a backup of the data file when saving. The backup filename
400 has the @file{.backup} extension appended to the opened file. The default is
403 @item cache_timeout = seconds
404 The number of seconds to keep the cache entry for this file. If @code{-1}, the
405 cache entry is kept forever. If @code{0}, each time an encrypted file is
406 @code{OPEN}ed (@pxref{OPEN}) a passphrase will be required. The default
407 is @code{600} or 10 minutes.
409 @item xfer_progress = bytes
410 Commands that send data lines to the client will also send the @code{XFER}
411 status message (@pxref{Status Messages}) after the specified number of bytes
412 have been sent. The number of bytes is rounded to @var{ASSUAN_LINELENGTH} or
413 @code{1002} bytes. The default is @code{8196}.
415 @item passphrase = string
416 The passphrase to use for this file. If specified in the @samp{global} section
417 then @samp{global} is treated as a data filename and not a default for other
418 files. Note that if a client changes the passphrase for this data file then
419 this value is not modified and will need to be updated.
421 @item passphrase_file = /path/to/file
422 Same as the @var{passphrase} parameter above but obtains the passphrase from
423 the specified filename.
425 @item recursion_depth = integer
426 The maximum number of times to resolve a @code{target} attribute for an
427 element in an element path (@pxref{Target Attribute}). An error is returned
428 when this value is exceeded. The default is @code{100} but can be disabled by
429 setting to @code{0} (@emph{not recommended}).
431 @item allowed = [-]user,[-]@@group,...
432 Same parameter value as the @code{allowed} parameter mentioned above in
433 the @samp{global} section but grants or denies a local user from opening
434 a specific data file. The default is to allow only the invoking user.
438 * TLS:: Remote connections over TLS.
439 * Pinentry:: Configuration file and defaults.
442 @node TLS, Pinentry, Configuration, Configuration
443 @chapter Configuring remote connections over TLS.
447 Remote connections can also be made to @command{pwmd} over @abbr{TLS}.
448 Authentication is done by using X509 client certificates that are signed with
449 the same Certificate Authority (@abbr{CA}) as the server certificate.
451 The @abbr{CA} certificate is expected to be found in
452 @file{~/.pwmd/ca-cert.pem} while the @command{pwmd} server certificate and key
453 file should be put in @file{~/.pwmd/server-cert.pem} and
454 @file{~/.pwmd/server-key.pem}, respectively.
456 See the documentation of @command{certtool} or @command{openssl} for details
457 on creating self-signed certificates.
459 The following TLS configuration options are available:
462 @item enable_tcp = boolean
463 Whether to enable TCP/TLS server support. If enabled, both TCP and the local
464 unix domain socket will listen for connections. The default is
467 @item tcp_port = integer
468 The TCP port to listen on when @var{enable_tcp} is @code{true}. The default is
471 @item tcp_bind = string
472 The internet protocol to listen with. Must be one of @code{ipv4}, @code{ipv6}
473 or @code{any} to listen for both IPv4 and IPv6 connections.
475 @item tcp_interface = string
476 Only useful if running as root.
478 @item tls_timeout = seconds
479 The number of seconds to wait for a read() or write() call on a
480 @abbr{TLS} client file descriptor to complete before returning an
481 error. The default is @var{300}.
483 Note that the @code{SAVE} command (@pxref{SAVE}) may take a longer time
484 to complete than other commands since key generation may need to be done
485 or do to a large @option{--cipher-iterations} setting.
487 @item keepalive_interval = seconds
488 Send a keepalive status message to an idle remote client. An idle
489 client is one who is not in a command. The purpose of this status
490 message is to disconnect a hung remote client and release any file mutex
491 locks so another client may open the same data file. The default is @code{60}.
493 @item tls_access = [+][!-]string[,[!-]string,...]
494 A comma separated list of client X509 certificate fingerprints in SHA-1
495 format that will be allowed to connect or open a file. If prefixed with
496 @code{!} or @code{-} then access is denied for the fingerprint. When
497 @code{!} or @code{-} is found by itself in the list it is treated as a
498 default for remaining fingerprints in the list. The @code{+} prefix
499 behaves the same but allows access. The order of the list is important
500 meaning that if one or more fingerprints is of the same SHA-1 hash, only
501 the final in the list is considered.
503 The access control is two fold: when the client connects its SHA-1
504 fingerprint is matched against the list of allowed fingerprints in the
505 @samp{global} section. When allowed in the @samp{global} section the
506 connection is established and the client may proceed to @code{OPEN}
507 (@pxref{OPEN}) a data file. During the @code{OPEN}, @code{CLEARCACHE}
508 and @code{CACHETIMEOUT} commands, the
509 fingerprint is checked again in a @samp{filename} section. When this
510 parameter is not found in a @samp{filename} section then access is
513 @item tcp_require_key = boolean
514 When @code{true}, require the remote client to provide the key or passphrase
515 to open a data file even if the file is cached. Note that the cache entry is
516 cleared during the @pxref{OPEN} command and the passphrase will be retrieved
517 from the client via a server @emph{INQUIRE}. This option is a default
518 for all files when specified in the @samp{global} section. The default
521 @item tcp_wait = integer
522 The time in tenths of a second to wait between TCP connections. Setting to 0
523 will disable waiting. The default is @code{3}.
525 @item tls_cipher_suite = string
526 The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
527 information about the format of this string. The default is @code{SECURE256}.
530 @node Pinentry, Commands, TLS, Configuration
531 @chapter Pinentry configuration
533 The @command{pinentry} program is used to prompt the user for passphrase
534 input or as a confirmation dialog; it needs to know where to prompt for
535 the input, beit from a terminal or an X11 display.
537 It is the responsibility of the client to tell @command{pinentry} about
538 the terminal or X11 display before requiring the input. This is done by
539 using the @command{pwmd} @code{OPTION} (@pxref{OPTION}) protocol command. It
540 need be done only once per client connection. To avoid the use of
541 @command{pinentry} entirely, use the @code{OPTION} (@pxref{OPTION})
542 @option{--disable-pinentry} protocol command.
545 @c Node, Next, Previous, Up
546 @node Commands, Status Messages, Pinentry, Top
547 @chapter Protocol commands and their syntax
549 @include commands.texi
551 @c Node, Next, Previous, Up
552 @node Status Messages, Target Attribute, Commands, Top
553 @chapter Status messages and their meanings
554 Some commands send status messages to inform the client about certain
555 operations or as a progress indicator. Status messages begin with a
556 @code{KEYWORD} followed by a status description for status messages that
557 require it. What status messages are sent, when, and how often may depend on
558 configuration settings (@pxref{Configuration}). A status message sent from
559 @command{gpg-agent} (@inforef{Invoking GPG-AGENT,,gnupg}) is also forwarded to
562 @multitable @columnfractions .20 .25 .55
563 @headitem Message @tab Parameters @tab Description
566 @tab @code{<integer>}
567 @tab The number of cached documents. Sent to each client after connecting
568 (@pxref{GETINFO}) and after every cache modification.
572 @tab @code{<integer>}
573 @tab The number of connected clients (@pxref{GETINFO}). Sent to each client
574 when another client either connects or disconnects.
578 @tab @code{<current>} @code{<total>}
579 @tab Sent to the current client during a decrypt operation. How often this
580 status message is sent is determined by the @code{cipher_progress}
581 (@pxref{Configuration}) setting.
585 @tab @code{<current>} @code{<total>}
586 @tab Sent to the current client during an encrypt operation. How often this
587 status message is sent is determined by the @code{cipher_progress}
588 (@pxref{Configuration}) setting.
593 @tab Sent once to the current client just before generating a new key-pair.
596 @cindex INQUIRE_MAXLEN
598 @tab Sent to the client from @command{gpg-agent} when inquiring data. This
599 specifies the maximum number of bytes allowed for the client to send and
600 should not be exceeded.
605 @tab Sent to each idle client every @var{keepalive_interval}
606 (@pxref{Configuration}) seconds.
611 @tab Sent to the current client when another client is holding the lock for
612 the mutex associated with a file.
617 @tab Sent to the current client when the opened (@pxref{OPEN}) file does not
618 exist on the file-system.
622 @tab @code{<sent> <total>}
623 @tab Sent to the current client when transferring data. It has two space
624 delimited arguments. The first being the current amount of bytes transferred
625 and the other being the total bytes to be transferred.
628 @c Node, Next, Previous, Up
629 @node Target Attribute, Signals, Status Messages, Top
630 @chapter The @code{target} attribute
631 @cindex target attribute
632 A @emph{case sensitive} attribute named @code{target} is treated specially
633 when found in each element of an element path. This attribute, like other
634 element attributes, is created or modified with the @code{ATTR} command
635 (@pxref{ATTR}). The value of this attribute is an existing element path
636 somewhere in the document. If you are familiar with @abbr{XML} entities or
637 maybe the @abbr{HTML} @code{id} or @code{target} attributes or a symbolic link
638 in a file-system, you may find this attribute behaves similar to any of those.
640 To create a @code{target} attribute use the following syntax:
643 ATTR SET target [!]element[@key{TAB}[!]child[..]] [!]element[@key{TAB}[!]child[..]]
646 Note the single space between the two element paths. The first element path is
647 where the @code{target} attribute will be created. If the element path does
648 not exist then it will be created. This is the only time the @code{ATTR}
649 (@pxref{ATTR}) command will create elements. The attribute is created in the
650 final element of the first element path.
652 The second element path is the destination of where you want the first element
653 path to resolve to. When an element path is passed as an argument to a
654 protocol command @command{pwmd} looks for a @code{target} attribute when
655 resolving each element and, if found, "jumps" to the attribute value and
656 continues resolving any remaining elements. When you want to avoid the
657 @code{target} attribute for any element of an element path then prefix the
658 element with the literal element character @samp{!}.
660 When an element of a element path is removed that a @code{target} attribute
661 resolves to then an error will occur when trying to access that element. You
662 may need to either update the @code{target} attribute value with a new element
663 path or remove the attribute entirely. Remember that since the element
664 contains the @code{target} attribute it will need to be prefixed with the
665 literal element character @samp{!} when specifying the element path to prevent
666 @command{pwmd} from trying to resolve the @code{target} attribute. For
667 example, to remove a @code{target} attribute for an element containing it:
670 ATTR DELETE target path@key{TAB}to@key{TAB}!element
673 Clients should be careful of creating @code{target} loops, or targets that
674 resolve to themselves. See the @var{recursion_depth} (@pxref{Configuration})
675 configuration parameter for details.
677 The @code{REALPATH} command (@pxref{REALPATH}) can be used to show the element
678 path after resolving all @code{target} attributes.
681 @c Node, Next, Previous, Up
682 @node Signals, Concept Index, Target Attribute, Top
683 @chapter Recognized signals
686 Sending the @emph{SIGHUP} signal to a @command{pwmd} process will reload the
687 configuration file and sending @emph{SIGUSR1} will clear the entire file
692 .BR gpg-agent (1), pinentry (1)
696 @c Node, Next, Previous, Up
697 @node Concept Index, , Signals, Top
698 @unnumbered Concept Index