pwmd man page

pwmd — a univeral data server


pwmd [options] [file1] [...]


pwmd or Password Manager Daemon is a server that applications connect to and send commands to store and retrieve data that is saved in an 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 the error source set as GPG_ERR_SOURCE_USER_1.

It is recommended to read the texinfo documentation of pwmd since it contains protocol commands and syntax and other details not found here.


When pwmd is started with the --use-agent command line option then pwmd will use gpg-agent for key generation, decryption, signing and caching of passphrases as the default rather than symmetrically encrypted data files. gpg-agent must be running prior to pwmd startup when this option is enabled. The ‘GPG_AGENT_INFO’ environment variable is set by gpg-agent and pwmd uses this variable to determine where the gpg-agent socket is listening for connections.

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.

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.

The following command line options are supported:

--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’.
Enable the use of gpg-agent and add support for data files encrypted with a keypair. Files previously handled by gpg-agent when this option is not specified will no longer be able to be opened and new data files are symmetrically or conventionally encrypted and without a public and private key. If specified, both data file types are supported.
--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 S-expression
The key parameters to use when generating a new key pair while importing an XML file or when converting a version 2 data file. The argument must be a valid S-expression (S-expressions,, gcrypt).
--keygrip hexstring
Specifies the hexadecimal encoded public key-grip to use for encryption when importing or converting. When not specified a new key-pair will be created.
--sign-keygrip hexstring
Specifies the hexadecimal encoded public key-grip to use for signing of the data file when importing or converting. When not specified the generated public key or the key specified with the --keygrip option will be used.
--passphrase-file, -k filename"
Obtain the passphrase from the specified filename.
--s2k-count iterations
The number of times to hash the passphrase when importing or converting. The default is the gpg-agent calibrated value of the machine. When less than '65536' the default will be used.
--cipher-iterations iterations
The number of symmetric encryption iterations. The value is actually N+1. The default is 0+1.
--cipher algo
When importing, the cipher to use for data encryption. See the cipher configuration parameter (see: [Configuration]) for available ciphers. The default is 'aes256'.
--convert, -C filename
Converts a pwmd version 2 data file to a version 3 data file. If encrypted, you will be prompted for a passphrase to use for decryption unless --passphrase-file was specified. The converted data file will be saved to the filename specified with --outfile. All --import related options may also be used when converting.
--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.
--debug-level keyword,keyword,...
Output libassuan Top,,assuan protocol IO with the comma separated list of output keywords. Valid keywords are: init, ctx, engine, data, sysio and control.
Show the version, copyright and compile time features and exit.
Print a summary of options.

Configuration File

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 a '[global]' section and are the default options for new or unspecified files.

A tilde ~ will be expanded to the home directory of the invoking user 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.
allowed = [-]user,[-]@group,...

A comma separated list of local user names or group names allowed to connect to the socket. Groups should be prefixed with a '@'. When not specified only the invoking user may connect. A username or group name may also be prefixed with a - to prevent access to a specific user or group in the list. The order of the list is important since a user may be of multiple groups.

This parameter may also be specified in a filename section to allow or deny a local user to OPEN (see: [OPEN]) a data file and has the same default to allow only the invoking user.

The following example would deny all users in group primary but allow username who is a member of primary:

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.
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, client commands are also logged. When 2, the command arguments are also logged. The default is 0.
use_agent = boolean
When true, enable gpg-agent support (see: [Invoking]).
agent_env_file = filename
A file containing the ‘GPG_AGENT_INFO’ environment variable and value as output by the gpg-agent --write-env-file command line option.
kill_scd = boolean
Kill scdaemon after each OPEN (see: [OPEN]) or SAVE (see: [SAVE]) command.
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.
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 the passphrase or passphrase_file parameters in a matching file section.
priority = integer
The priority, or niceness, of the server. The default is inherited from the parent process.
cipher = algorithm
The default cipher to use for data encryption. The algorithm must be one of: aes128, aes192, aes256, serpent128, serpent192, serpent256, camellia128, camellia192, camellia256, 3des, cast5, blowfish, twofish128 or twofish256. The default is aes256.
cipher_iterations = integer
The number of times to encrypt the XML data. This differs from the s2k_count parameter which specifies the number of times to hash the passphrase used to encrypt the data. The default is 0 although 1 iteration is still done.
cipher_progress = integer
Send a progress message to the client after the specified amount of encryption or decryption iterations have been done. The default is 2000.
keyparam = s-expression
The default key paramaters to use when generating a new key-pair. The default is RSA with 2048 bits. Note that only RSA as the encryption algorithm is supported at the moment. Both RSA and DSA keys may be used for signing.
pinentry_path = /path/to/pinentry
The location of the pinentry binary. This program is used to prompt for a passphrase when not using gpg-agent. The default is specified at compile time.
pinentry_timeout = seconds

The number of seconds to wait for a pinentry before giving up and returning an error. This timeout value is used for both waiting for another pinentry to complete and for the pinentry waiting for user input.

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.

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 = string
The passphrase to use for this file. If specified in the 'global' section then 'global' is treated as a data filename and not a default for other files. Note that if a client changes the passphrase for this data file then this value is not modified and will need to be updated.
passphrase_file = /path/to/file
Same as the passphrase parameter above but obtains the passphrase from the specified filename.
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,...
Same parameter value as the allowed parameter mentioned above in the 'global' section but grants or denies a local user from opening a specific data file. The default is to allow only the invoking user.

Remote connections can also be made to pwmd over TLS. Authentication is done by using X509 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 on 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.
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.

Note that the SAVE command (see: [SAVE]) may take a longer time to complete than other commands since key generation may need to be done or do to a large --cipher-iterations setting.

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.
tls_access = [+][!-]string[,[!-]string,...]

A comma separated list of client X509 certificate fingerprints in SHA-1 format that will be allowed to connect or open a file. If prefixed with ! or - then access is denied for the fingerprint. When ! or - is found by itself in the list it is treated as a default for remaining fingerprints in the list. The + prefix behaves the same but allows access. The order of the list is important meaning that if one or more fingerprints is of the same SHA-1 hash, only the final in the list is considered.

The access control is two fold: when the client connects its SHA-1 fingerprint is matched against the list of allowed fingerprints in the 'global' section. When allowed in the 'global' section the connection is established and the client may proceed to OPEN (see: [OPEN]) a data file. During the OPEN, CLEARCACHE and CACHETIMEOUT commands, the fingerprint is checked again in a 'filename' section. When this parameter is not found in a 'filename' section then access is granted.

tcp_require_key = boolean
When true, require the remote client to provide the key or passphrase to open a data file even if the file is cached. Note that the cache entry is cleared during the see: [OPEN] command and the passphrase will be retrieved from the client via a server INQUIRE. 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.


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 client to tell pinentry about the terminal or X11 display before requiring the input. This is done by using the pwmd OPTION (see: [OPTION]) protocol command. It need be done only once per client connection. To avoid the use of pinentry entirely, use the OPTION (see: [OPTION]) --disable-pinentry protocol command.


Sending the SIGHUP signal to a pwmd process will reload the configuration file and sending SIGUSR1 will clear the entire file cache.

See Also



Explore man page connections for pwmd(1).