1PWMD(1) Password Manager Daemon PWMD(1)
2
6 pwmd - a univeral data server
7
9 pwmd [options] [file1] [...]
10
13 Password Manager Daemon (or pwmd) is a server that applications connect
14 to and send commands to store and retrieve data that is saved in an
15 OpenPGP encrypted XML document.
16 The server uses the Assuan protocol (Implementation,,assuan) which is
18 the same used by gpg-agent, pinentry and scdaemon. It also uses libgpg-
19 error for error reporting with GPG_ERR_SOURCE_USER_1 being the error
20 source.
21 It is recommended to read the texinfo documentation of pwmd since it
23 contains protocol commands and syntax and other details not found here.
24
26 pwmd uses GpgME for encryption, decryption and signing of the OpenPGP
27 data file. GpgME itself makes use of gpg2 for these operations so some
28 configuration of gpg2 may also be needed.
29 It is recommended to pass the --allow-preset-passphrase command line
31 option to gpg-agent. Doing so allows pwmd cache pushing on startup. It
32 is also recommended to pass the --allow-loopback-pinentry to gpg-agent.
33 This option allows a passphrase to be inquired from pwmd when a pinen‐
34 try is unavailable to the client (see: [TLS]). see: [Configuration] for
35 details about the gpg_homedir parameter.
36 pwmd is executed as follows:
38 pwmd options [ file1 ] [ ]
40 Non-option arguments are data files to cache on startup. When the data
42 file requires a passphrase for decryption a pinentry will prompt either
43 on the current TTY or from an X11 window when the ‘DISPLAY’ environment
44 variable is set. see: [Pinentry].
45 The following command line options are supported:
47 --debug protocol:level[,protocol:level]
50 Enable debugging output. This option can output sensitive infor‐
51 mation such as passphrases and secret keys so care should be
52 taken where the output gets written to. The protocol is a single
53 character representing the protocol to log. Use a for libassuan
54 with level being one or more character flags: i for init, x for
55 context, e for engine, d for data, s for system IO or c for con‐
56 trol. To debug gpgme use g as the protocol with level being an
57 integer from 1 to 9. To enable TLS debugging output use t as the
58 protocol with level being an integer from 1 to 9. A value over
59 10 will enable all TLS debugging output with 1 being the
60 default.
61 --homedir directory
64 The root directory where pwmd will store its data and temporary
65 files. The default is ‘~/.pwmd’.
66 --rcfile, -f rcfile
69 Specify an alternate configuration file. The default is
70 ‘~/.pwmd/config’.
71 --kill Terminate an existing instance of pwmd. The process to terminate
74 is determined from the --homedir and --rcfile options.
75 --import, -I filename
78 Imports an XML file. The XML file should be in conformance to
79 the pwmd DTD (see: [Introduction]). You will be prompted for a
80 passphrase to encrypt with. The output is written to the file‐
81 name specified with --outfile. To make use of the imported data,
82 place the output file in ‘~/.pwmd/data’.
83 --keyparam filename
86 The key parameters to use when generating a new key pair while
87 importing an XML file. The file contents must be in GnuPG XML
88 format.
89 --keyid fingerprint[,<fingerprint>]
92 Specifies the fingerprint of the encryption key to use as a
93 recipient when importing. When not specified a new key-pair will
94 be created.
95 --sign-keyid fingerprint[,<fingerprint>]
98 Specifies the fingerprint of the signing key to use for signing
99 of the data file when importing. When not specified the signing
100 key of the generated key-pair or the signing key of the --keyid
101 option will be used.
102 --symmetric, -s
105 Use symmetric or conventional encryption rather than pubic key
106 encryption when importing. Signing is still possible by using
107 the --sign-keyid option. No signing is done by default when
108 specifying this option.
109 --passphrase-file, -k filename"
112 Obtain a passphrase from the specified filename.
113 --disable-dump, -D
116 Disable the XPATH, XPATHATTR, LIST and DUMP protocol commands
117 (see: [Commands]). This overrides any disable_list_and_dump con‐
118 figuration parameter (see: [Configuration]).
119 --no-fork, -n
122 Run as a foreground process and do not fork into the background.
123 --ignore, --force
126 Ignore cache pushing failures on startup. By default, pwmd will
127 exit if an error occurred do to an invalid passphrase or other
128 error.
129 --version
132 Show the version, copyright and compile time features and exit.
133 --help Print a summary of options.
136
139 If no configuration file is specified with the pwmd -f command line
140 option, pwmd will read ‘~/.pwmd/config’ if it exists, and if not, will
141 use defaults. Blank lines and lines beginning with '#' are ignored.
142 Some parameters may have data file specific settings by placing them in
143 a file section. A file section is declared by surrounding the filename
144 with braces (i.e., '[filename]'). Global options may be specified in
145 the global section 'e.g., [global]' and are the default options for new
146 or unspecified file sections.
147 A tilde ~ will be expanded to the home directory of the user starting
149 pwmd when contained in a parameter whose value is a filename.
150 The configuration file can be reloaded by sending the SIGHUP signal to
152 a pwmd process.
153 The following options are only for use in the [global] section:
155 socket_path = /path/to/socket
158 Listen on the specified socket. The default is ‘~/.pwmd/socket’.
159 socket_perms = octal_mode
162 Permissions to set after creating the socket. This will override
163 any umask(2) setting.
164 invoking_user = [-!]user,[-!]@group,[-!]#SHA-256,...
167 This parameter is not to be confused with setuid or setguid upon
168 startup. It's syntax is the same as the allowed parameter except
169 that it is a list of local usernames, group names and TLS fin‐
170 gerprint hashes that may use the XPATH, XPATHATTR and DUMP com‐
171 mands (except when disabled with the disable_list_and_dump
172 option) and also who may modify elements that have no _acl
173 attribute or is not listed in an _acl. It is similar to the sys‐
174 tem administrator root account but for a data file and element
175 paths (see: [Access Control]). The default is the user the exe‐
176 cutes pwmd.
177 invoking_file = filename
180 A file containing one entry per line. An entry has the same syn‐
181 tax as the invoking_user parameter. When both this parameter and
182 the invoking_user parameter are specified then the invoking_file
183 entries will be appended to the invoking_user parameter value.
184 strict_kill = boolean
187 When false, the KILL command (see: [KILL]) will allow killing
188 another client that is not of the same UID or TLS fingerprint of
189 the current client and when not the invoking_user. The default
190 us false.
191 allowed = [-!]user,[-!]@group,[+,][-!]#SHA-256,...
194 A comma separated list of local user names, group names or TLS
195 fingerprint SHA-256 hashes (in the case of a remote client) who
196 are allowed to connect. Groups should be prefixed with a '@'.
197 When not specified only the invoking user may connect. A user‐
198 name, group name or hash may also be prefixed with a - or ! to
199 prevent access to a specific user or group in the list. The
200 order of the list is important since a user may be a member of
201 multiple groups.
202 This parameter may also be specified in a filename section to
204 allow or deny a client to OPEN (see: [OPEN]) a data file. It
205 also affects the cache commands CLEARCACHE (see: [CLEARCACHE])
206 and CACHETIMEOUT (see: [CACHETIMEOUT]). When not specified in a
207 file section any user that can connect may also open any file‐
208 name.
209 The following example would deny all users in group primary but
211 allow username who may be a member of primary. It will also
212 allow any TLS client except for the client with TLS fingerprint
213 hash #ABCDEF:
214 allowed=-@primary,username,+,!#ABCDEF
216 allowed_file = filename
219 A file containing one entry per line. An entry has the same syn‐
220 tax as the allowed parameter. When both this parameter and the
221 allowed parameter are specified then the allowed_file entries
222 will be appended to the allowed parameter value.
223 encrypt_to = boolean
226 When true and SAVE'ing a data file, allow gpg2 to append it's
227 configured key to the list of recipients. The default is false
228 meaning that only keys specified with SAVE --keyid are recipi‐
229 ents.
230 always_trust = boolean
233 When true, allow encrypting to untrusted recipients or public
234 encryption keys. The default is false.
235 gpg_homedir = path
238 The location where gpg2 will store its public and private keys
239 and configuration. The default is ‘HOMEDIR/.gnupg’ where HOMEDIR
240 is the default (‘~/.pwmd’) or the value specified on the command
241 line (see: [Invoking]). If you want to use your standard gpg2
242 keyring then set this to ‘~/.gnupg’. Note that a new instance of
243 gpg-agent will be started when not using the standard keyring
244 and that any configuration options for gpg-agent will need to
245 placed in ‘HOMEDIR/.gnupg/gpg-agent.conf’.
246 disable_mlockall = boolean
249 When set to false, mlockall(2) will be called on startup. This
250 will use more physical memory but may also be more secure since
251 no swapping to disk will occur. The default is true. If possi‐
252 ble, use an encrypted swap file or partition and leave this set
253 to true.
254 log_path = /path/to/logfile
257 Logs informational messages to the specified file. The default
258 is ‘~/.pwmd/log’.
259 enable_logging = boolean
262 Enable or disable logging to log_path. The default is false.
263 log_keepopen = boolean
266 When set to false, the log file specified with log_path will be
267 closed after writing each line. The default is true.
268 syslog = boolean
271 Enable logging to syslog(8) with facility LOG_DAEMON and prior‐
272 ity LOG_INFO. The default is false.
273 log_level = level
276 When 0, only connections and errors are logged. When 1, data
277 file recipients and signers are logged during OPEN (see: [OPEN])
278 and SAVE (see: [SAVE]). When 2, client commands are also logged.
279 The default is 0.
280 kill_scd = boolean
283 Kill scdaemon after each OPEN (see: [OPEN]), SAVE (see: [SAVE])
284 or PASSWD (see: [PASSWD]) command. The default is false.
285 disable_list_and_dump = boolean
288 When true, the XPATH, XPATHATTR, LIST and DUMP protocol commands
289 (see: [Commands]) will be disabled.
290 cache_push = file1,file2
293 A comma separated list of filenames that will be pushed into the
294 file cache upon startup. pwmd will prompt for the passphrase for
295 each file unless specified with passphrase_file parameter in a
296 matching file section.
297 priority = integer
300 The priority, or niceness, of the server. The default is inher‐
301 ited from the parent process.
302 lock_timeout = integer
305 The default timeout in tenths of a second before giving up wait‐
306 ing for a file lock and returning an error. The default is 50.
307 send_state = integer
310 Whether to send client state changes of the current client to
311 all connected clients. When 0 no client state changes will be
312 sent although a client state may be obtained with the GETINFO
313 command (see: [GETINFO]). When 1 a status message will be sent
314 to all connected clients. When 2 the status message will be
315 sent only to the invoking_user (see: [Configuration]). The
316 default is 2. Disabling this option can significantly increase
317 the performance of pwmd when there are many connected clients.
318 The following options are defaults for new files when specified in the
323 'global' section. When placed in a data file section they are options
324 specific to that data file only.
325 require_save_key = boolean
328 Require the passphrase needed to open a data file before writing
329 changes of the documment to disk reguardless of the key cache
330 status. The default is true.
331 backup = boolean
334 Whether to create a backup of the data file when saving. The
335 backup filename has the ‘.backup’ extension appended to the
336 opened file. The default is true.
337 cache_timeout = seconds
340 The number of seconds to keep the cache entry for this file. If
341 -1, the cache entry is kept forever. If 0, each time an
342 encrypted file is OPENed (see: [OPEN]) a passphrase will be
343 required. The default is 600 or 10 minutes.
344 xfer_progress = bytes
347 Commands that send data lines to the client will also send the
348 XFER status message (see: [Status Messages]) after the specified
349 number of bytes have been sent. The number of bytes is rounded
350 to ASSUAN_LINELENGTH or 1002 bytes. The default is 8196.
351 passphrase_file = /path/to/filename
354 Obtain the passphrase to open the data file from filename. If
355 specified in the 'global' section then the passphrase_file is a
356 default for all data files. Note that if a client changes the
357 passphrase for this data file then the passphrase_file will need
358 to be updated.
359 recursion_depth = integer
362 The maximum number of times to resolve a target attribute for an
363 element in an element path (see: [Target Attribute]). An error
364 is returned when this value is exceeded. The default is 100 but
365 can be disabled by setting to 0 (not recommended).
366 allowed = [-]user,[-]@group,[!]#TLSFINGERPRINT,...
369 Same parameter value as the allowed parameter mentioned above in
370 the '[global]' section but grants or denies a user from opening
371 a specific data file. The default is to allow any user that is
372 allowed to connect.
373 Remote connections can also be made to pwmd over TLS. Authentication
378 is done by using X.509 client certificates that are signed with the
379 same Certificate Authority (CA) as the server certificate.
380 The CA certificate is expected to be found in ‘~/.pwmd/ca-cert.pem’
382 while the pwmd server certificate and key file should be put in
383 ‘~/.pwmd/server-cert.pem’ and ‘~/.pwmd/server-key.pem’, respectively.
384 See the documentation of certtool or openssl for details about creating
386 self-signed certificates.
387 The following TLS configuration options are available:
389 enable_tcp = boolean
392 Whether to enable TCP/TLS server support. If enabled, both TCP
393 and the local unix domain socket will listen for connections.
394 The default is false.
395 tcp_port = integer
398 The TCP port to listen on when enable_tcp is true. The default
399 is 6466.
400 tcp_bind = string
403 The internet protocol to listen with. Must be one of ipv4, ipv6
404 or any to listen for both IPv4 and IPv6 connections. The default
405 is any.
406 tcp_interface = string
409 Only useful if running as root.
410 tls_timeout = seconds
413 The number of seconds to wait for a read() or write() call on a
414 TLS client file descriptor to complete before returning an
415 error. The default is 300.
416 keepalive_interval = seconds
419 Send a keepalive status message to an idle remote client. An
420 idle client is one who is not in a command. The purpose of this
421 status message is to disconnect a hung remote client and release
422 any file mutex locks so another client may open the same data
423 file. The default is 60.
424 tcp_require_key = boolean
427 When true, require the remote client to provide the passphrase
428 to open a data file even if the file is cached. This option is
429 a default for all files when specified in the '[global]' sec‐
430 tion. The default is false.
431 tcp_wait = integer
434 The time in tenths of a second to wait between TCP connections.
435 Setting to 0 will disable waiting. The default is 3.
436 tls_cipher_suite = string
439 The GnuTLS cipher suite and protocol to use. See the GnuTLS doc‐
440 umentation for information about the format of this string. The
441 default is SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-
442 TLS1.0.
443 tls_dh_level = string
446 The security level (bits) of the generated key exchange parame‐
447 ters. Possible values are low, medium or high. The default is
448 medium.
449
453 The pinentry program is used to prompt the user for passphrase input or
454 as a confirmation dialog; it needs to know where to prompt for the
455 input, beit from a terminal or an X11 display.
456 It is the responsibility of the user to tell pinentry about the termi‐
458 nal or X11 display before requiring the input. This is done by using
459 the gpg-connect-agent program. Please read it's documentation about the
460 UPDATESTARTUPTTY command.
461
464 Sending the SIGHUP signal to a pwmd process will reload the configura‐
465 tion file and sending SIGUSR1 will clear the entire file cache.
466
469 gpg-agent(1) , pinentry(1) , gpg2(1)
4703.1.0-dev 2015-10-17 PWMD(1)