1 \input texinfo @c -*-texinfo-*-
7 @dircategory Miscellaneous
9 * pwmd: (pwmd). Password Manager Daemon
14 @subtitle Commands and syntax
18 @c Node, Next, Previous, Up
22 This manual documents @command{pwmd} protocol commands and their syntax.
26 * Introduction:: Overview of pwmd.
27 * Invoking:: Command line options.
28 * Configuration:: Configuration file options.
29 * Commands:: Protocol commands.
30 * Status Messages:: Status lines and their meaning.
31 * Target Attribute:: A kind of symbolic link.
32 * Concept Index:: Index of concepts.
35 @c Node, Next, Previous, Up
36 @node Introduction, Invoking, , Top
37 @chapter Overview of @command{pwmd}
39 @command{pwmd} or @dfn{Password Manager Daemon} is a server that listens on a
40 local UNIX domain socket. Applications connect to this socket and send
41 commands to store and retrieve data that is saved in an @dfn{OpenPGP}
42 encrypted @abbr{XML} data file.
44 The server uses the Assuan protocol (@inforef{Implementation,,assuan}) which
45 is the same used by @command{gpg-agent}, @command{pinentry} and
46 @command{scdaemon}. It also uses @cite{libgpg-error} for error reporting with
47 the error source set as @var{GPG_ERR_SOURCE_USER_1}.
49 The data file is in @abbr{XML} format and uses the following @abbr{DTD}:
54 <!ELEMENT pwmd (element*)>
55 <!ATTLIST element _name CDATA #REQUIRED>
59 The @command{pwmd} element is the document root node while all other elements
60 of the document have the name @code{element} with an attribute @code{_name}
61 whose value uniquely identifies the element at the current element tree depth.
62 It is done this way to avoid @abbr{XML} parsing errors for commonly used
63 characters. A @abbr{URL} for example would be an invalid @abbr{XML} element
64 since the @abbr{URI} contains a @samp{:} which is also the @abbr{XML}
67 As mentioned, an element name must be unique for the current element tree
68 depth. You cannot have two elements containing the same @code{_name} attribute
69 value. @command{pwmd} will stop searching for an element of an @emph{element
70 path} at the first match then continue searching for the next element of the
71 element path beginning at the child node of the matched element.
73 An @emph{element path} is a @key{TAB} delimited character string where each
74 @key{TAB} separates each element in the path. For example, the element path
75 @code{a@key{TAB}b@key{TAB}c} has the following @abbr{XML} document structure:
82 [... element value or content ...]
89 The only restriction of an element name is that it contain no whitespace
90 characters. It also cannot begin with a @samp{!} since this character is
91 reserved for the @code{target} attribute. @xref{Target Attribute}.
93 @c Node, Next, Previous, Up
94 @node Invoking, Configuration, Introduction, Top
95 @chapter Invoking @command{pwmd}
97 Since @command{pwmd} uses @command{gpg-agent} for key generation, decryption,
98 signing and caching of passphrases, @command{gpg-agent} must be running prior
99 to @command{pwmd} startup. The @env{GPG_AGENT_INFO} environment variable is
100 set by @command{gpg-agent} and @command{pwmd} uses this variable to determine
101 where the @command{gpg-agent} socket is listening for connections.
103 It is recommended to pass the @option{--allow-preset-passphrase}
104 command line option to @command{gpg-agent}. Doing so allows @command{pwmd}
105 cache pushing on startup. It is also recommended to pass the
106 @option{--allow-loopback-pinentry} to @command{gpg-agent}. This option allows
107 a passphrase to be inquired from @command{pwmd} when a @command{pinentry} is
108 unavailable to the client.
110 @cindex Running @command{pwmd}
111 @command{pwmd} is executed as follows:
114 pwmd @var{options} [ file1 ] [ @dots{ } ]
117 Non-option arguments are data files to cache on startup. When the data file
118 requires a passphrase for decryption a @command{pinentry} will prompt either
119 on the current @abbr{TTY} or from an X11 window when the @env{DISPLAY}
120 environment variable is set.
124 The following command line options are supported:
128 @item --homedir directory
129 The root directory where pwmd will store its data and temporary files. The
130 default is @file{~/.pwmd}.
132 @item --rcfile, -f rcfile
133 Specify an alternate configuration file. The default is @file{~/.pwmd/config}.
135 @item --import, -I filename
136 Imports an @abbr{XML} file. The @abbr{XML} file should be in conformance to
137 the @command{pwmd} @abbr{DTD} (@pxref{Introduction}). You
138 will be prompted for a passphrase to encrypt with. The output is written to
139 the filename specified with @option{--outfile}. To make use of the imported
140 data, place the resulting file in @file{~/.pwmd/data}.
142 @item --keyparam S-expression
143 The key parameters to use when generating a new key pair while importing an
144 @abbr{XML} file or when converting a @emph{version 2} data file. The argument
145 must be a valid S-expression (@inforef{S-expressions,, gcrypt}).
147 @item --keygrip hexstring
148 Specifies the hexadecimal encoded public key-grip to use for encryption when
149 importing or converting. When not specified a new key-pair will be created.
151 @item --sign-keygrip hexstring
152 Specifies the hexadecimal encoded public key-grip to use for signing of the
153 data file when importing or converting. When not specified the generated
154 public key or the key specified with the @option{--keygrip} option will be
157 @item --passphrase-file, -k filename"
158 Obtain the passphrase from the specified filename.
160 @item --s2k-count iterations
161 The number of times to hash the passphrase when importing or converting. The
162 default is the gpg-agent calibrated value of the machine. When less than
163 @samp{65536} the default will be used.
165 @item --cipher-iterations iterations
166 The number of symmetric encryption iterations. The value is actually N+1. The
170 When importing, the cipher to use for data encryption. See the @var{cipher}
171 configuration parameter (@pxref{Configuration}) for available ciphers. The
172 default is @samp{aes256}.
174 @item --convert, -C filename
175 Converts a @command{pwmd} @emph{version 2} data file to a @emph{version 3}
176 data file. If encrypted, you will be prompted for a passphrase to use for
177 decryption unless @option{--passphrase-file} was specified. The converted data
178 file will be saved to the filename specified with @option{--outfile}. All
179 @option{--import} related options may also be used when converting.
181 @item --disable-dump, -D
182 Disable the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and @code{DUMP}
183 protocol commands (@pxref{Commands}). This overrides any
184 @var{disable_list_and_dump} configuration parameter (@pxref{Configuration}).
187 Run as a foreground process and do not fork into the background.
190 Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
191 if an error occurred do to an invalid passphrase or other error.
193 @item --debug-level keyword,keyword,...
194 Output libassuan @inforef{Top,,assuan} protocol IO with the comma
195 separated list of output keywords. Valid keywords are: @code{init},
196 @code{ctx}, @code{engine}, @code{data}, @code{sysio} and @code{control}.
199 Show the version, copyright and compile time features and exit.
202 Print a summary of options.
206 Sending the @emph{SIGHUP} signal to a @command{pwmd} process will reload the
207 configuration file and sending @emph{SIGUSR1} will clear the entire file
210 @c Node, Next, Previous, Up
211 @node Configuration, TLS, Invoking, Top
212 @chapter @command{pwmd} configuration options
213 If no configuration file is specified with the @command{pwmd} @option{-f}
214 command line option, @command{pwmd} will read @file{~/.pwmd/config} if it
215 exists, and if not, will use defaults. Blank lines and lines beginning with
216 @samp{#} are ignored. Some parameters may have data file specific settings by
217 placing them in a file section. A file section is declared by surrounding the
218 filename with braces (i.e., @samp{[filename]}). Global options may be
219 specified in a @samp{[global]} section and are the default options for new or
222 A tilde @key{~} will be expanded to the home directory of the invoking user
223 when contained in a parameter whose value is a filename.
225 @cindex Reloading the configuration file
226 The configuration file can be reloaded by sending the @emph{SIGHUP} signal to
227 a @command{pwmd} process.
229 @cindex Global configuration options
230 The following options are only for use in the @samp{global} section:
233 @item socket_path = /path/to/socket
234 Listen on the specified socket. The default is @file{~/.pwmd/socket}.
236 @item socket_perms = octal_mode
237 Permissions to set after creating the socket. This will override any
238 @cite{umask(2)} setting.
240 @item allowed = user,@@group,...
241 A comma separated list of local user names or group names allowed to connect
242 to the socket. Groups should be prefixed with a @samp{@@}. When not specified
243 only the invoking user may connect. The connecting user name is obtained via
244 @var{SO_PEERCRED} when supported by the system.
246 @item disable_mlockall = boolean
247 When set to @var{false}, @cite{mlockall(2)} will be called on startup. This
248 will use more physical memory but may also be more secure since no swapping to
251 @item log_path = /path/to/logfile
252 Logs informational messages to the specified file. The default is
255 @item enable_logging = boolean
256 Enable or disable logging to @var{log_path}. The default is @code{false}.
258 @item syslog = boolean
259 Enable logging to @cite{syslog(8)} with facility @emph{LOG_DAEMON} and priority
260 @emph{LOG_INFO}. The default is @code{false}.
262 @item log_level = level
263 When @code{0}, only connections and errors are logged. When @code{1}, client
264 commands are also logged. When @code{2}, the command arguments are also logged.
265 The default is @code{0}.
267 @item agent_env_file = filename
268 A file containing the @env{GPG_AGENT_INFO} environment variable and value as
269 output by the @command{gpg-agent} @option{--write-env-file} command line
272 @item kill_scd = boolean
273 Kill @command{scdaemon} after each @code{OPEN} (@pxref{OPEN}) or @code{SAVE}
274 (@pxref{SAVE}) command.
276 @item disable_list_and_dump = boolean
277 When @code{true}, the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and
278 @code{DUMP} protocol commands (@pxref{Commands}) will be disabled.
280 @item cache_push = file1,file2
281 A comma separated list of filenames that will be pushed into the file cache
282 upon startup. @command{pwmd} will prompt for the passphrase for each file unless
283 specified with the @var{passphrase} or @var{passphrase_file} parameters in a
284 matching file section.
286 @item priority = integer
287 The priority, or niceness, of the server. The default is inherited from the
290 @item cipher = algorithm
291 The default cipher to use for data encryption. The algorithm must be one of:
292 @code{aes128}, @code{aes192}, @code{aes256}, @code{serpent128},
293 @code{serpent192}, @code{serpent256}, @code{camellia128},
294 @code{camellia192}, @code{camellia256}, @code{3des}, @code{cast5},
295 @code{blowfish}, @code{twofish128} or @code{twofish256}. The default is
298 @item cipher_iterations = integer
299 The number of times to encrypt the XML data. This differs from the
300 @var{s2k_count} parameter which specifies the number of times to hash the
301 passphrase used to encrypt the data. The default is 0 although 1 iteration is
304 @item cipher_progress = integer
305 Send a progress message to the client after the specified amount of encryption
306 or decryption iterations have been done. The default is 2000.
308 @item algo = algorithm
309 The default algorithm to use when generating a new key-pair. The default is
313 The default number of bits to use when generating a new key-pair. The default
317 @cindex Data file configuration options
318 The following options are defaults for new files when specified in the
319 @samp{global} section. When placed in a data file section they are options
320 specific to that data file only.
323 @item backup = boolean
324 Whether to create a backup of the data file when saving. The backup filename
325 has the @file{.backup} extension appended to the opened file. The default is
328 @item cache_timeout = seconds
329 The number of seconds to keep the cache entry for this file. If @code{-1}, the
330 cache entry is kept forever. If @code{0}, each time an encrypted file is
331 @code{OPEN}ed (@pxref{OPEN}) a passphrase will be required. The default
334 @item xfer_progress = bytes
335 Commands that send data lines to the client will also send the @code{XFER}
336 status message (@pxref{Status Messages}) after the specified number of bytes
337 have been sent. The number of bytes is rounded to @var{ASSUAN_LINELENGTH} or
338 @code{1002} bytes. The default is @code{8196}.
340 @item passphrase = string
341 The passphrase to use for this file. If specified in the @samp{global} section
342 then @samp{global} is treated as a data filename and not a default for other
343 files. Note that if a client changes the passphrase for this data file then
344 this value is not modified and will need to be updated.
346 @item passphrase_file = /path/to/file
347 Same as the @var{passphrase} parameter above but obtains the passphrase from
348 the specified filename.
350 @item recursion_depth = integer
351 The maximum number of times to resolve a @code{target} attribute for an
352 element in an element path (@pxref{Target Attribute}). An error is returned
353 when this value is exceeded. The default is @code{100} but can be disabled by
354 setting to @code{0} (@emph{not recommended}).
358 * TLS:: Remote connections over TLS.
361 @node TLS, Commands, Configuration, Configuration
362 @chapter Configuring remote connections over TLS.
363 Remote connections can be made to @command{pwmd} over @abbr{TLS}.
364 Authentication is done by using X509 client certificates that are signed with
365 the same Certificate Authority (@abbr{CA}) as the server certificate.
367 The @abbr{CA} certificate is expected to be found in
368 @file{~/.pwmd/ca-cert.pem} while the @command{pwmd} server certificate and key
369 file should be put in @file{~/.pwmd/server-cert.pem} and
370 @file{~/.pwmd/server-key.pem}, respectively.
372 See the documentation of @command{certtool} or @command{openssl} for details
373 on creating self-signed certificates.
375 The following TLS configuration options are available:
378 @item enable_tcp = boolean
379 Whether to enable TCP/TLS server support. If enabled, both TCP and the local
380 unix domain socket will listen for connections. The default is
383 @item tcp_port = integer
384 The TCP port to listen on when @var{enable_tcp} is @code{true}. The default is
387 @item tcp_bind = string
388 The internet protocol to listen with. Must be one of @code{ipv4}, @code{ipv6}
389 or @code{any} to listen for both IPv4 and IPv6 connections.
391 @item tcp_interface = string
392 Only useful if running as root.
394 @item tls_access = string[,string,...]
395 A comma separated list of client x509 certificate fingerprints in SHA-1 format
396 that will be allowed to open a file. If prefixed with @code{!} then access is
397 denied for the connected client. The access control is for filenames and this
398 option can be specified in either the @samp{global} or a filename section.
399 When defined but empty then access will be denied. When defined and only
400 @code{+}, then all clients will be allowed to connect.
402 @item tcp_require_key = boolean
403 When @code{true}, require the remote client to provide the key or passphrase
404 to open a data file even if the file is cached. Note that the cache entry is
405 cleared during the @pxref{OPEN} command and the passphrase will be retrieved
406 from the client via a server @emph{INQUIRE}. The default is @code{false}.
408 @item tcp_wait = integer
409 The time in tenths of a second to wait for a new TCP connection. Setting to 0
410 will disable waiting. The default is @code{3}.
412 @item tls_cipher_suite = string
413 The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for
414 information about the format of this string. The default is @code{SECURE256}.
416 @item tls_use_crl = boolean
417 When @code{true}, enabling reading of @file{~/.pwmd/crl.pem}. This
418 file is a x509 Certificate Revokation List and can be used to deny
419 certificates stored in it. The default is @code{false}.
422 @c Node, Next, Previous, Up
423 @node Commands, Status Messages, TLS, Top
424 @chapter Protocol commands and their syntax
426 @include commands.texi
428 @c Node, Next, Previous, Up
429 @node Status Messages, Target Attribute, Commands, Top
430 @chapter Status messages and their meanings
431 Some commands send status messages to inform the client about certain
432 operations or as a progress indicator. Status messages begin with a
433 @code{KEYWORD} followed by a status description for status messages that
434 require it. What status messages are sent, when, and how often depend on
435 configuration settings (@pxref{Configuration}). A status message sent from
436 @command{gpg-agent} (@inforef{Invoking GPG-AGENT,,gnupg}) is also forwarded to
439 @multitable @columnfractions .20 .25 .55
440 @headitem Message @tab Arguments @tab Description
443 @tab @code{<integer>}
444 @tab The number of cached documents. Sent to each client after connecting
445 (@pxref{GETINFO}) and after every cache modification.
449 @tab @code{<integer>}
450 @tab The number of connected clients (@pxref{GETINFO}). Sent to each client
451 when another client either connects or disconnects.
455 @tab @code{n} @code{total}
456 @tab Sent to the current client during a decrypt operation. How often this
457 status message is sent is determined by the @code{cipher_progress}
458 (@pxref{Configuration}) setting.
462 @tab @code{n} @code{total}
463 @tab Sent to the current client during an encrypt operation. How often this
464 status message is sent is determined by the @code{cipher_progress}
465 (@pxref{Configuration}) setting.
470 @tab Sent once to the current client just before generating a new key-pair.
473 @cindex INQUIRE_MAXLEN
475 @tab Sent to the client from @command{gpg-agent} when inquiring data. This
476 specifies the maximum number of bytes allowed for the client to send and
477 should not be exceeded.
482 @tab Sent to the current client when another client is holding the lock for
483 the mutex associated with a file.
488 @tab Sent to the current client when the opened (@pxref{OPEN}) file does not
489 exist on the file-system.
493 @tab @code{<sent> <total>}
494 @tab Sent to the current client when transferring data. It has two space
495 delimited arguments. The first being the current amount of bytes transferred
496 and the other being the total bytes to be transferred.
499 @c Node, Next, Previous, Up
500 @node Target Attribute, Concept Index, Status Messages, Top
501 @chapter The @code{target} attribute
502 @cindex target attribute
503 A @emph{case sensitive} attribute named @code{target} is treated specially
504 when found in each element of an element path. This attribute, like other
505 element attributes, is created or modified with the @code{ATTR} command
506 (@pxref{ATTR}). The value of this attribute is an existing element path
507 somewhere in the document. If you are familiar with @abbr{XML} entities or
508 maybe the @abbr{HTML} @code{id} or @code{target} attributes or a symbolic link
509 in a file-system, you may find this attribute behaves similar to any of those.
511 To create a @code{target} attribute use the following syntax:
514 ATTR SET target [!]element[@key{TAB}[!]child[..]] [!]element[@key{TAB}[!]child[..]]
517 Note the single space between the two element paths. The first element path is
518 where the @code{target} attribute will be created. If the element path does
519 not exist then it will be created. This is the only time the @code{ATTR}
520 (@pxref{ATTR}) command will create elements. The attribute is created in the
521 final element of the element path.
523 The second element path is the destination of where you want the first element
524 path to resolve to. When an element path is passed to a protocol command
525 @command{pwmd} looks for a @code{target} attribute when resolving each element
526 and if found, "jumps" to the attribute value and continues resolving any
527 remaining elements. When you want to avoid the @code{target} attribute for
528 any element of an element path then prefix the element with the literal
529 element character @samp{!}.
531 When an element of a element path is removed that a @code{target} attribute
532 resolves to then an error will occur. You may need to either update the
533 @code{target} attribute value with a new element path or remove the attribute
534 entirely. Remember that since the element contains the @code{target} attribute
535 it will need to be prefixed with the literal element character @samp{!} when
536 specifying the element path. For example, to remove a @code{target}
537 attribute for an element containing it:
540 ATTR DELETE target path@key{TAB}to@key{TAB}!element
543 Clients should be careful of creating @code{target} loops, or targets that
544 resolve to themselves. See the @var{recursion_depth} (@pxref{Configuration})
545 configuration parameter for details.
547 The @code{REALPATH} command (@pxref{REALPATH}) can be used to show the element
548 path after resolving all @code{target} attributes.
551 @c Node, Next, Previous, Up
552 @node Concept Index, , Target Attribute, Top
553 @unnumbered Concept Index