pwmd man page
pwmd — a univeral data server
pwmd [options] [file1] [...]
Password Manager Daemon (or pwmd) is a server that applications connect to and send commands to store and retrieve data that is saved in an OpenPGP encrypted XML document.
The server uses the Assuan protocol (Implementation,,assuan) which is the same used by gpg-agent, pinentry and scdaemon. It also uses libgpg-error for error reporting with GPG_ERR_SOURCE_USER_1 being the error source.
It is recommended to read the texinfo documentation of pwmd since it contains protocol commands and syntax and other details not found here.
pwmd uses GpgME for encryption, decryption and signing of the OpenPGP data file. GpgME itself makes use of gpg2 for these operations so some configuration of gpg2 may also be needed.
It is recommended to pass the --allow-preset-passphrase command line option to gpg-agent. Doing so allows pwmd cache pushing on startup. It is also recommended to pass the --allow-loopback-pinentry to gpg-agent. This option allows a passphrase to be inquired from pwmd when a pinentry is unavailable to the client (see: [TLS]). see: [Configuration] for details about the gpg_homedir parameter.
pwmd is executed as follows:
pwmd options [ file1 ] [ ]
Non-option arguments are data files to cache on startup. When the data file requires a passphrase for decryption a pinentry will prompt either on the current TTY or from an X11 window when the ‘DISPLAY’ environment variable is set. see: [Pinentry].
The following command line options are supported:
- --debug protocol:level[,protocol:level]
Enable debugging output. This option can output sensitive information such as passphrases and secret keys so care should be taken where the output gets written to. The protocol is a single character representing the protocol to log. Use a for libassuan with level being one or more character flags: i for init, x for context, e for engine, d for data, s for system IO or c for control. To debug gpgme use g as the protocol with level being an integer from 1 to 9. To enable TLS debugging output use t as the protocol with level being an integer from 1 to 9. A value over 10 will enable all TLS debugging output with 1 being the default.
- --homedir directory
The root directory where pwmd will store its data and temporary files. The default is ‘~/.pwmd’.
- --rcfile, -f rcfile
Specify an alternate configuration file. The default is ‘~/.pwmd/config’.
Terminate an existing instance of pwmd. The process to terminate is determined from the --homedir and --rcfile options.
- --import, -I filename
Imports an XML file. The XML file should be in conformance to the pwmd DTD (see: [Introduction]). You will be prompted for a passphrase to encrypt with. The output is written to the filename specified with --outfile. To make use of the imported data, place the output file in ‘~/.pwmd/data’.
- --keyparam filename
The key parameters to use when generating a new key pair while importing an XML file. The file contents must be in GnuPG XML format.
- --keyid fingerprint[,<fingerprint>]
Specifies the fingerprint of the encryption key to use as a recipient when importing. When not specified a new key-pair will be created.
- --sign-keyid fingerprint[,<fingerprint>]
Specifies the fingerprint of the signing key to use for signing of the data file when importing. When not specified the signing key of the generated key-pair or the signing key of the --keyid option will be used.
- --symmetric, -s
Use symmetric or conventional encryption rather than pubic key encryption when importing. Signing is still possible by using the --sign-keyid option. No signing is done by default when specifying this option.
- --passphrase-file, -k filename"
Obtain a passphrase from the specified filename.
- --disable-dump, -D
Disable the XPATH, XPATHATTR, LIST and DUMP protocol commands (see: [Commands]). This overrides any disable_list_and_dump configuration parameter (see: [Configuration]).
- --no-fork, -n
Run as a foreground process and do not fork into the background.
- --ignore, --force
Ignore cache pushing failures on startup. By default, pwmd will exit if an error occurred do to an invalid passphrase or other error.
Show the version, copyright and compile time features and exit.
Print a summary of options.
If no configuration file is specified with the pwmd -f command line option, pwmd will read ‘~/.pwmd/config’ if it exists, and if not, will use defaults. Blank lines and lines beginning with '#' are ignored. Some parameters may have data file specific settings by placing them in a file section. A file section is declared by surrounding the filename with braces (i.e., '[filename]'). Global options may be specified in the global section 'e.g., [global]' and are the default options for new or unspecified file sections.
A tilde ~ will be expanded to the home directory of the user starting pwmd when contained in a parameter whose value is a filename.
The configuration file can be reloaded by sending the SIGHUP signal to a pwmd process.
The following options are only for use in the [global] section:
- socket_path = /path/to/socket
Listen on the specified socket. The default is ‘~/.pwmd/socket’.
- socket_perms = octal_mode
Permissions to set after creating the socket. This will override any umask(2) setting.
- invoking_user = [-!]user,[-!]@group,[-!]#SHA-256,...
This parameter is not to be confused with setuid or setguid upon startup. It's syntax is the same as the allowed parameter except that it is a list of local usernames, group names and TLS fingerprint hashes that may use the XPATH, XPATHATTR and DUMP commands (except when disabled with the disable_list_and_dump option) and also who may modify elements that have no _acl attribute or is not listed in an _acl. It is similar to the system administrator root account but for a data file and element paths (see: [Access Control]). The default is the user the executes pwmd.
- invoking_file = filename
A file containing one entry per line. An entry has the same syntax as the invoking_user parameter. When both this parameter and the invoking_user parameter are specified then the invoking_file entries will be appended to the invoking_user parameter value.
- strict_kill = boolean
When false, the KILL command (see: [KILL]) will allow killing another client that is not of the same UID or TLS fingerprint of the current client and when not the invoking_user. The default us false.
- allowed = [-!]user,[-!]@group,[+,][-!]#SHA-256,...
A comma separated list of local user names, group names or TLS fingerprint SHA-256 hashes (in the case of a remote client) who are allowed to connect. Groups should be prefixed with a '@'. When not specified only the invoking user may connect. A username, group name or hash may also be prefixed with a - or ! to prevent access to a specific user or group in the list. The order of the list is important since a user may be a member of multiple groups.
This parameter may also be specified in a filename section to allow or deny a client to OPEN (see: [OPEN]) a data file. It also affects the cache commands CLEARCACHE (see: [CLEARCACHE]) and CACHETIMEOUT (see: [CACHETIMEOUT]). When not specified in a file section any user that can connect may also open any filename.
The following example would deny all users in group primary but allow username who may be a member of primary. It will also allow any TLS client except for the client with TLS fingerprint hash #ABCDEF:
- allowed_file = filename
A file containing one entry per line. An entry has the same syntax as the allowed parameter. When both this parameter and the allowed parameter are specified then the allowed_file entries will be appended to the allowed parameter value.
- encrypt_to = boolean
When true and SAVE'ing a data file, allow gpg2 to append it's configured key to the list of recipients. The default is false meaning that only keys specified with SAVE --keyid are recipients.
- always_trust = boolean
When true, allow encrypting to untrusted recipients or public encryption keys. The default is false.
- gpg_homedir = path
The location where gpg2 will store its public and private keys and configuration. The default is ‘HOMEDIR/.gnupg’ where HOMEDIR is the default (‘~/.pwmd’) or the value specified on the command line (see: [Invoking]). If you want to use your standard gpg2 keyring then set this to ‘~/.gnupg’. Note that a new instance of gpg-agent will be started when not using the standard keyring and that any configuration options for gpg-agent will need to placed in ‘HOMEDIR/.gnupg/gpg-agent.conf’.
- disable_mlockall = boolean
When set to false, mlockall(2) will be called on startup. This will use more physical memory but may also be more secure since no swapping to disk will occur. The default is true. If possible, use an encrypted swap file or partition and leave this set to true.
- log_path = /path/to/logfile
Logs informational messages to the specified file. The default is ‘~/.pwmd/log’.
- enable_logging = boolean
Enable or disable logging to log_path. The default is false.
- log_keepopen = boolean
When set to false, the log file specified with log_path will be closed after writing each line. The default is true.
- syslog = boolean
Enable logging to syslog(8) with facility LOG_DAEMON and priority LOG_INFO. The default is false.
- log_level = level
When 0, only connections and errors are logged. When 1, data file recipients and signers are logged during OPEN (see: [OPEN]) and SAVE (see: [SAVE]). When 2, client commands are also logged. The default is 0.
- kill_scd = boolean
Kill scdaemon after each OPEN (see: [OPEN]), SAVE (see: [SAVE]) or PASSWD (see: [PASSWD]) command. The default is false.
- disable_list_and_dump = boolean
When true, the XPATH, XPATHATTR, LIST and DUMP protocol commands (see: [Commands]) will be disabled.
- cache_push = file1,file2
A comma separated list of filenames that will be pushed into the file cache upon startup. pwmd will prompt for the passphrase for each file unless specified with passphrase_file parameter in a matching file section.
- priority = integer
The priority, or niceness, of the server. The default is inherited from the parent process.
- lock_timeout = integer
The default timeout in tenths of a second before giving up waiting for a file lock and returning an error. The default is 50.
- send_state = integer
Whether to send client state changes of the current client to all connected clients. When 0 no client state changes will be sent although a client state may be obtained with the GETINFO command (see: [GETINFO]). When 1 a status message will be sent to all connected clients. When 2 the status message will be sent only to the invoking_user (see: [Configuration]). The default is 2. Disabling this option can significantly increase the performance of pwmd when there are many connected clients.
The following options are defaults for new files when specified in the 'global' section. When placed in a data file section they are options specific to that data file only.
- require_save_key = boolean
Require the passphrase needed to open a data file before writing changes of the documment to disk reguardless of the key cache status. The default is true.
- backup = boolean
Whether to create a backup of the data file when saving. The backup filename has the ‘.backup’ extension appended to the opened file. The default is true.
- cache_timeout = seconds
The number of seconds to keep the cache entry for this file. If -1, the cache entry is kept forever. If 0, each time an encrypted file is OPENed (see: [OPEN]) a passphrase will be required. The default is 600 or 10 minutes.
- xfer_progress = bytes
Commands that send data lines to the client will also send the XFER status message (see: [Status Messages]) after the specified number of bytes have been sent. The number of bytes is rounded to ASSUAN_LINELENGTH or 1002 bytes. The default is 8196.
- passphrase_file = /path/to/filename
Obtain the passphrase to open the data file from filename. If specified in the 'global' section then the passphrase_file is a default for all data files. Note that if a client changes the passphrase for this data file then the passphrase_file will need to be updated.
- recursion_depth = integer
The maximum number of times to resolve a target attribute for an element in an element path (see: [Target Attribute]). An error is returned when this value is exceeded. The default is 100 but can be disabled by setting to 0 (not recommended).
- allowed = [-]user,[-]@group,[!]#TLSFINGERPRINT,...
Same parameter value as the allowed parameter mentioned above in the '[global]' section but grants or denies a user from opening a specific data file. The default is to allow any user that is allowed to connect.
Remote connections can also be made to pwmd over TLS. Authentication is done by using X.509 client certificates that are signed with the same Certificate Authority (CA) as the server certificate.
The CA certificate is expected to be found in ‘~/.pwmd/ca-cert.pem’ while the pwmd server certificate and key file should be put in ‘~/.pwmd/server-cert.pem’ and ‘~/.pwmd/server-key.pem’, respectively.
See the documentation of certtool or openssl for details about creating self-signed certificates.
The following TLS configuration options are available:
- enable_tcp = boolean
Whether to enable TCP/TLS server support. If enabled, both TCP and the local unix domain socket will listen for connections. The default is false.
- tcp_port = integer
The TCP port to listen on when enable_tcp is true. The default is 6466.
- tcp_bind = string
The internet protocol to listen with. Must be one of ipv4, ipv6 or any to listen for both IPv4 and IPv6 connections. The default is any.
- tcp_interface = string
Only useful if running as root.
- tls_timeout = seconds
The number of seconds to wait for a read() or write() call on a TLS client file descriptor to complete before returning an error. The default is 300.
- keepalive_interval = seconds
Send a keepalive status message to an idle remote client. An idle client is one who is not in a command. The purpose of this status message is to disconnect a hung remote client and release any file mutex locks so another client may open the same data file. The default is 60.
- tcp_require_key = boolean
When true, require the remote client to provide the passphrase to open a data file even if the file is cached. This option is a default for all files when specified in the '[global]' section. The default is false.
- tcp_wait = integer
The time in tenths of a second to wait between TCP connections. Setting to 0 will disable waiting. The default is 3.
- tls_cipher_suite = string
The GnuTLS cipher suite and protocol to use. See the GnuTLS documentation for information about the format of this string. The default is SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0.
- tls_dh_level = string
The security level (bits) of the generated key exchange parameters. Possible values are low, medium or high. The default is medium.
The pinentry program is used to prompt the user for passphrase input or as a confirmation dialog; it needs to know where to prompt for the input, beit from a terminal or an X11 display.
It is the responsibility of the user to tell pinentry about the terminal or X11 display before requiring the input. This is done by using the gpg-connect-agent program. Please read it's documentation about the UPDATESTARTUPTTY command.
Sending the SIGHUP signal to a pwmd process will reload the configuration file and sending SIGUSR1 will clear the entire file cache.
gpg-agent(1) , pinentry(1) , gpg2(1)