Update copyright header.

[pwmd.git] / doc / pwmd.1.in

.\" Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012
.\" Ben Kibbey <bjk@luxsci.net>
.\" 
.\" This file is part of pwmd.
.\" 
.\" Pwmd is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" Pwmd is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with Pwmd.  If not, see <http://www.gnu.org/licenses/>.
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH PWMD 1 "06 Oct 2011" "Password Manager Daemon" "Password Manager Daemon"
.SH NAME

pwmd \- a universal data server
.SH SYNOPSIS
.B pwmd
[options] [file1] [...]

.SH DESCRIPTION
.B pwmd
is a daemon the listens on a local UNIX domain socket.  Clients connect and
send commands to send and retrieve data that is stored in an encrypted XML
data file. \fBpwmd\fP uses
.BR gpg-agent (1)
for keypair generation, decryption and signing of the data file.  See the
section \fBGPG-AGENT\fP for further information.

.SH OPTIONS
The following are the available command line options. Remaining arguments are
files to add to the cache on startup.
.TP
.I "\-\-rcfile, \-f rcfile"
Specify an alternate configuration file. The default is \fI~/.pwmd/config\fR.

.TP
.I "\-\-import, \-I filename \-\-outfile filename"
Imports an XML file. The XML file should be in conformance to the pwmd DTD.
See \fBCOMMANDS\fP contained in the distributed pwmd archive for details. You
will be prompted for a passphrase to encrypt with. The output is written to
the filename specified with \fI\-\-outfile\fP. To make use of the imported
data, place the resulting file in the data directory (\fI~/.pwmd/data\fP).

.TP
.I "\-\-keyparam <s-exp>"
The key parameters to use when generating a new key pair when importing or
converting. The argument must be a valid S-expression.

.TP
.I "\-\-keygrip hexstring"
Specifies the public keygrip to use for encryption when importing or
converting. When not specified a new keypair will be created.

.TP
.I "\-\-passphrase-file, \-k filename"
Obtain the passphrase from the specified filename.

.TP
.I "\-\-no-passphrase-file
When converting and \fB--passphrase-file\fP was specified, do not use the
passphrase obtained from the file when generating the new keypair.

.TP
.I "\-\-cipher string"
When importing, the cipher to use for data encryption.  See the
.B cipher
configuration file setting below for available ciphers. The default is
\fIaes-256\fP.

.TP
.I "\-\-s2k-count N
The number of passphrase hashing iterations to use when importing or
converting. The default is the gpg-agent calibrated value for the machine.
Must be 65536 or greater.

.TP
.I "\-\-cipher\-iterations N
The number of times to encrypt the XML data. The value is actually N+1. The
default is 0.

.TP
.I "\-\-convert, \-C filename \-\-outfile filename"
Converts a \fBpwmd\fP version 2 data file to a version 3 data file. If
encrypted, you will be prompted for a passphrase to use for decryption unless
a \fI\-\-passphrase-file\fP was specified. The converted data file will be
saved to the filename specified with \fI\-\-outfile\fP. All \fI\-\-import\fP
related options may also be used when converting.

.TP
.I "\-\-disable\-dump, \-D"
Disable the \fBXPATH\fP, \fBLIST\fP and \fBDUMP\fP protocol commands. This
overrides any \fIdisable_list_and_dump\fP configuration parameter.

.TP
.I "\-\-no\-fork, \-n"
Run as a foreground process and do not fork into the background.

.TP
.I "\-\-ignore"
Ignore cache pushing failures on startup. By default, \fBpwmd\fP will exit if
an error occured do to an invalid passphrase or some other access error.

.TP
.I "\-\-debug-level keyword,keyword,..."
Output assuan protocol IO with the comma separated list of output keywords.
Valid keywords are: \fBinit\fP, \fBctx\fP, \fBengine\fP, \fBdata\fP,
\fBsysio\fP and \fBcontrol\fP.

.TP
.I "\-\-version"
Version information.

.TP
.I "\-\-help"
Help text.

.SH CONFIGURATION FILE
Blank lines and lines beginning with '#' are ignored. Some options can 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., \fI[filename]\fP).
Global options may be specified in a \fI[global]\fP section and are the
default options for new or unspecified files. When the first character of a
filename is a tilde then it will be expanded to your home directory. First the
\fBglobal\fP options:
.TP
.I "socket_path=<string>"
Listen on the specified socket. The default is \fI~/.pwmd/socket\fR.

.TP
.I "socket_perms=<integer>"
Permissions to set after creating the socket. This will override any
.BR umask (2)
setting.

.TP
.I "allowed=<user,@group,...>"
A comma separated list of local usernames or group names allowed to connect to
the socket. Groups should be prefixed with a '\fB@\fP'. When not specified
only the invoking user may connect. The connecting username is obtained via
\fBSO_PEERCRED\fP.

.TP
.I "disable_mlockall=<boolean>"
When set to \fIfalse\fP,
.BR mlockall (2)
will be called after the client connects. This will use more physical memory
but may also be more secure since no swapping to disk will occur.

.TP
.I "log_path=<string>"
Logs informational messages to the specified file. The default is
\fI~/.pwmd/log\fR.

.TP
.I "enable_logging=<boolean>"
Enable or disable logging to \fIlog_path\fR. The default is \fIfalse\fR.

.TP
.I "syslog=<boolean>"
Enable logging to
.BR syslog (8)
with facility \fBLOG_DAEMON\fP and priority \fBLOG_INFO\fP. The default is
\fIfalse\fR.

.TP
.I "log_level=<integer>"
When \fI0\fP, only connections and errors are logged. When \fI1\fP, client
commands, options and the return code are also logged. The default is \fI0\fP.

.TP
.I "agent_env_file=<filename>"
A file containing the \fBGPG_AGENT_INFO\fP environment variable and value as
output by the \fB--write-env-file\fP option of \fBgpg-agent\fP.

.TP
.I "kill_scd=<boolean>"
Kill the smartcard daemon after each OPEN or SAVE command.  This option
requires libassuan 2.0.3 or later at compile time.

.TP
.I "disable_list_and_dump=<boolean>"
When \fItrue\fP, the \fBXPATH\fP, \fBLIST\fP and \fBDUMP\fP protocol commands
will be disabled.

.TP
.I "cache_push=<list>"
A comma separated list of filenames that will be pushed into the file cache
upon startup. \fBpwmd\fP will prompt for the passphrase for each file unless
specified with the \fIpassphrase\fP or \fIpassphrase_file\fP parameters in a
matching file section.

.TP
.I "priority=<integer>"
The priority, or niceness, of the server. The default is inherited from the
parent process.

.TP
.I "cipher=<string>"
The default cipher to use for data encryption. Should be one of:
\fIaes128\fP, \fIaes192\fP, \fIaes256\fP, \fIserpent128\fP, \fIserpent192\fP,
\fIserpent256\fP, \fIcamellia128\fP, \fIcamellia192\fP, \fIcamellia256\fP,
\fI3des\fP, \fIcast5\fP, \fIblowfish\fP, \fItwofish128\fP or
\fItwofish256\fP. The default is \fIaes256\fP.

.PP
Below are options that can be specified in the \fB[global]\fP or
\fB[filename]\fP section. If in both then \fB[filename]\fP will have
precedence.
.TP
.I "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
\fItrue\fP. 

.TP
.I "cache_timeout=<integer>"
The number of seconds to keep the cache entry for this file. If \fI-1\fP, the
cache entry is kept forever. If \fI0\fP, each time an encrypted file is OPEN'd
passphrase will be required. The default is \fI-1\fP.

.TP
.I "xfer_progress=<integer>"
Commands that send data lines to the client will send the XFER status message
after the specified number of bytes have been sent. The number of bytes is
rounded to ASSUAN_LINELENGTH or 1002 bytes. The default is \fI8196\fP.

.TP
.I "passphrase=<string>"
The initial passphrase to use for this file. If specified in the
\fBglobal\fP section then "\fIglobal\fP" 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.

.TP
.I "passphrase_file=<string>"
Same as the \fIpassphrase\fP parameter above but obtains the passphrase from
the specified filename. Note that if the cache entry for a data file using a
\fIpassphrase_file\fP is removed then the only way to add it again is to
restart \fBpwmd\fP or to re-read the configuration file.

.TP
.I "recursion_depth=<integer>"
The maximum number of times to resolve a "target" attribute for an element in
an element path. An error is returned when this value is exceeded.  The
default is \fI100\fP but can be disabled by setting to \fI0\fP (not
recommended).

.SH GPG-AGENT
Since \fBpwmd\fP uses
.BR gpg-agent (1)
for public and private key operations, \fBgpg-agent\fP needs to be running and
have set the \fBGPG_AGENT_INFO\fP environment variable before \fBpwmd\fP has
started up.
.BR gpg-agent (1)
uses
.BR pinentry (1)
to prompt for a passphrase, or a PIN code if using a smartcard, when a secret
key needs to be unlocked. It is up to the client to tell \fBpwmd\fP where to
have the pinentry prompt for input. \fBpwmd\fP will then pass this information
to
.BR gpg-agent (1)
as needed.

.PP
.B pwmd
will only keep track of keygrips for keypairs that it knows about when
caching. It will not do anything with secret keys outside of \fBpwmd\fP unless
a key is shared with a \fBpwmd\fP data file. The \fBpwmd\fP cache is cleared
when exiting. This will also clear \fBgpg-agent\fP cache entries that were
added by \fBpwmd\fP. This may have undesirable effects when using a keypair
for a data file that is also used outside of \fBpwmd\fP.

.PP
Note that for passphrase caching on startup or a passphrase obtained via a
server inquire in the \fBOPEN\fP command, the
\fI\-\-allow-preset-passphrase\fP option must be passed to
.BR gpg-agent (1)
for these features to work.

.SH SIGNALS
.TP
.B SIGUSR1
Clears the entire file cache. If there are any clients connected, a passphrase
may be required for the next \fBOPEN\fP command.
.TP
.B SIGHUP
Reloads the configuration file. Any files specified in the \fIcache_push\fP
configuration parameter are added to the cache when no passphrase is required.
.TP
.B SIGTERM and SIGINT
Disallows new connections and waits for all clients to disconnect before
terminating. Sending this signal again will terminate without waiting.

.SH FILES
.TP
.B ~/.pwmd/config
Default configuration file.
.TP
.B ~/.pwmd/data
Default data directory.
.TP
.B ~/.pwmd/socket
Default listening socket.
.TP
.B ~/.pwmd/log
Default log file when logging is enabled.

.SH AUTHOR
Ben Kibbey <bjk@luxsci.net>
.br
.URL "http://pwmd.sourceforge.net/" "PWMD Homepage" .

.SH "SEE ALSO"
.BR gpg-agent (1), pinentry (1)

Also see the pwmd.info documentation which is more complete.