1PWMD(1)                     Password Manager Daemon                    PWMD(1)
2
3
4

NAME

6       pwmd - a univeral data server
7

SYNOPSIS

9       pwmd [options] [file1] [...]
10
11

DESCRIPTION

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
17       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
22       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

OPTIONS

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
30       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
37       pwmd is executed as follows:
38
39         pwmd options [ file1 ] [  ]
40
41       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
46       The following command line options are supported:
47
48
49       --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
62
63       --homedir directory
64              The  root directory where pwmd will store its data and temporary
65              files.  The default is ‘~/.pwmd’.
66
67
68       --rcfile, -f rcfile
69              Specify  an  alternate  configuration  file.  The   default   is
70~/.pwmd/config’.
71
72
73       --kill Terminate an existing instance of pwmd. The process to terminate
74              is determined from the --homedir and --rcfile options.
75
76
77       --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
84
85       --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
90
91       --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
96
97       --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
103
104       --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
110
111       --passphrase-file, -k filename"
112              Obtain a passphrase from the specified filename.
113
114
115       --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
120
121       --no-fork, -n
122              Run as a foreground process and do not fork into the background.
123
124
125       --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
130
131       --version
132              Show the version, copyright and compile time features and exit.
133
134
135       --help Print a summary of options.
136
137

CONFIGURATION FILE

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
148       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
151       The configuration file can be reloaded by sending the SIGHUP signal  to
152       a pwmd process.
153
154       The following options are only for use in the [global] section:
155
156
157       socket_path = /path/to/socket
158              Listen on the specified socket. The default is ‘~/.pwmd/socket’.
159
160
161       socket_perms = octal_mode
162              Permissions to set after creating the socket. This will override
163              any umask(2) setting.
164
165
166       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
178
179       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
185
186       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
192
193       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
203              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
210              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
215         allowed=-@primary,username,+,!#ABCDEF
216
217
218       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
224
225       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
231
232       always_trust = boolean
233              When true, allow encrypting to untrusted  recipients  or  public
234              encryption keys. The default is false.
235
236
237       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
247
248       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
255
256       log_path = /path/to/logfile
257              Logs informational messages to the specified file.  The  default
258              is ‘~/.pwmd/log’.
259
260
261       enable_logging = boolean
262              Enable or disable logging to log_path. The default is false.
263
264
265       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
269
270       syslog = boolean
271              Enable logging to syslog(8) with facility LOG_DAEMON and  prior‐
272              ity LOG_INFO. The default is false.
273
274
275       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
281
282       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
286
287       disable_list_and_dump = boolean
288              When true, the XPATH, XPATHATTR, LIST and DUMP protocol commands
289              (see: [Commands]) will be disabled.
290
291
292       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
298
299       priority = integer
300              The  priority, or niceness, of the server. The default is inher‐
301              ited from the parent process.
302
303
304       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
308
309       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
319
320
321
322       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
326
327       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
332
333       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
338
339       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
345
346       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
352
353       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
360
361       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
367
368       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
374
375
376
377       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
381       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
385       See the documentation of certtool or openssl for details about creating
386       self-signed certificates.
387
388       The following TLS configuration options are available:
389
390
391       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
396
397       tcp_port = integer
398              The  TCP  port to listen on when enable_tcp is true. The default
399              is 6466.
400
401
402       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
407
408       tcp_interface = string
409              Only useful if running as root.
410
411
412       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
417
418       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
425
426       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
432
433       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
437
438       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
444
445       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
450
451

PINENTRY

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
457       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
462

SIGNALS

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
467

SEE ALSO

469       gpg-agent(1) , pinentry(1) , gpg2(1)
470
471
472
473
4743.1.0-dev                         2015-10-17                           PWMD(1)
Impressum