Test for error from cache_iscached().

[pwmd.git] / doc / pwmd.texi

\input texinfo @c -*-texinfo-*- 
@c %**start of header 
@setfilename pwmd.info 
@settitle PWMD Manual

@macro manpage {a}
@end macro
@macro mansect {a}
@end macro
@macro manpause
@end macro
@macro mancont
@end macro
@c %**end of header

@dircategory Miscellaneous
@direntry
* pwmd: (pwmd).         Password Manager Daemon
@end direntry

@titlepage 
@title PWMD Manual
@subtitle Commands and syntax
@author by Ben Kibbey
@end titlepage

@c    Node, Next, Previous, Up 
@node Top ,     ,         , (dir) 
 
@ifinfo 
This manual documents @command{pwmd} version 3.0 protocol commands and
their syntax.
@end ifinfo 
 
@menu 
* Introduction::          Overview of pwmd.
* Invoking::              Command line options.
* Configuration::         Configuration file options.
* Commands::              Protocol commands.
* Status Messages::       Status lines and their meaning.
* Target Attribute::      A kind of symbolic link.
* Signals::               Signals known to pwmd.
* Concept Index::         Index of concepts.
@end menu

@c    Node,     Next,    Previous, Up 
@node Introduction, Invoking,        , Top 
@chapter Overview of @command{pwmd} 

@manpage pwmd.1
@ifset manverb
.B pwmd
\- a univeral data server
@end ifset

@mansect synopsis
@ifset manverb
.B pwmd
[options] [file1] [...]
@end ifset

@mansect description
@command{pwmd} or @dfn{Password Manager Daemon} is a server that
applications connect to and send commands to store and retrieve data
that is saved in an encrypted @abbr{XML} document.

The server uses the Assuan protocol (@inforef{Implementation,,assuan}) which
is the same used by @command{gpg-agent}, @command{pinentry} and
@command{scdaemon}. It also uses @cite{libgpg-error} for error reporting with
the error source set as @var{GPG_ERR_SOURCE_USER_1}.
@ifset isman
.P
It is recommended to read the texinfo documentation of @command{pwmd}
since it contains protocol commands and syntax and other details not
found here.
@end ifset
@manpause

The @abbr{XML} document uses the following @abbr{DTD}:

@example
    <?xml version="1.0"?>
    <!DOCTYPE pwmd [
    <!ELEMENT pwmd (element*)>
    <!ATTLIST element _name CDATA #REQUIRED>
    ]>
@end example

The @code{pwmd} element is the document root node while all other elements
of the document have the name @code{element} with an attribute @code{_name}
whose value uniquely identifies the element at the current element tree depth.
It is done this way to avoid @abbr{XML} parsing errors for commonly used
characters.  A @abbr{URL} for example would be an invalid @abbr{XML} element
since the @abbr{URI} contains a @samp{:} which is also the @abbr{XML}
namespace separator.

As mentioned, an element name must be unique for the current element tree
depth. You cannot have two elements containing the same @code{_name} attribute
value. @command{pwmd} will stop searching for an element of an @emph{element
path} at the first match then continue searching for the next element of the
element path beginning at the child node of the matched element.

An @emph{element path} is a @key{TAB} delimited character string where each
@key{TAB} separates each element in the path.  For example, the element path
@code{a@key{TAB}b@key{TAB}c} has the following @abbr{XML} document structure:

@example
        <pwmd>
            <element _name="a">
                <element _name="b">
                    <element _name="c">
                        [... element value or content ...]
                    </element>
                </element>
            </element>
        </pwmd>
@end example

The only restriction of an element name is that it contain no whitespace
characters. It also cannot begin with a @samp{!} since this character is
reserved for the @code{target} attribute. @xref{Target Attribute}.

@c    Node,     Next,    Previous, Up 
@node Invoking, Configuration, Introduction, Top 
@chapter Invoking @command{pwmd} 

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

It is recommended to pass the @option{--allow-preset-passphrase}
command line option to @command{gpg-agent}. Doing so allows @command{pwmd}
cache pushing on startup. It is also recommended to pass the
@option{--allow-loopback-pinentry} to @command{gpg-agent}. This option allows
a passphrase to be inquired from @command{pwmd} when a @command{pinentry} is
unavailable to the client.

@cindex Running @command{pwmd} 
@command{pwmd} is executed as follows: 
 
@example 
pwmd @var{options} [ file1 ] [ @dots{  } ]
@end example

Non-option arguments are data files to cache on startup. When the data file
requires a passphrase for decryption a @command{pinentry} will prompt either
on the current @abbr{TTY} or from an X11 window when the @env{DISPLAY}
environment variable is set.

@cindex Options 
@cindex Arguments 
The following command line options are supported:

@cindex Getting help 
@table @samp 
@item --homedir directory
The root directory where pwmd will store its data and temporary files.  The
default is @file{~/.pwmd}.

@item --rcfile, -f rcfile
Specify an alternate configuration file. The default is
@file{~/.pwmd/config}.

@item --use-agent
Enable the use of @command{gpg-agent} and add support for data files
encrypted with a keypair. Files previously handled by
@command{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.

@item --import, -I filename
Imports an @abbr{XML} file. The @abbr{XML} file should be in conformance to
the @command{pwmd} @abbr{DTD} (@pxref{Introduction}). You
will be prompted for a passphrase to encrypt with.  The output is written to
the filename specified with @option{--outfile}. To make use of the imported
data, place the output file in @file{~/.pwmd/data}.

@item --keyparam S-expression
The key parameters to use when generating a new key pair while importing an
@abbr{XML} file or when converting a @emph{version 2} data file. The argument
must be a valid S-expression (@inforef{S-expressions,, gcrypt}).

@item --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.

@item --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 @option{--keygrip} option will be
used.

@item --passphrase-file, -k filename"
Obtain the passphrase from the specified filename.

@item --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
@samp{65536} the default will be used.

@item --cipher-iterations iterations
The number of symmetric encryption iterations. The value is actually N+1. The
default is 0+1.

@item --cipher algo
When importing, the cipher to use for data encryption.  See the @var{cipher}
configuration parameter (@pxref{Configuration}) for available ciphers. The
default is @samp{aes256}.

@item --convert, -C filename
Converts a @command{pwmd} @emph{version 2} data file to a @emph{version 3}
data file. If encrypted, you will be prompted for a passphrase to use for
decryption unless @option{--passphrase-file} was specified. The converted data
file will be saved to the filename specified with @option{--outfile}. All
@option{--import} related options may also be used when converting.

@item --disable-dump, -D
Disable the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and @code{DUMP}
protocol commands (@pxref{Commands}). This overrides any
@var{disable_list_and_dump} configuration parameter (@pxref{Configuration}).

@item --no-fork, -n
Run as a foreground process and do not fork into the background.

@item --ignore
Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
if an error occurred do to an invalid passphrase or other error.

@item --debug-level keyword,keyword,...
Output libassuan @inforef{Top,,assuan} protocol IO with the comma
separated list of output keywords.  Valid keywords are: @code{init},
@code{ctx}, @code{engine}, @code{data}, @code{sysio} and @code{control}.

@item --version
Show the version, copyright and compile time features and exit.

@item --help 
Print a summary of options.
@end table
@manpause

@c    Node,     Next,    Previous, Up 
@node Configuration, TLS, Invoking, Top 
@chapter @command{pwmd} configuration file options
@mancont
@mansect configuration file
If no configuration file is specified with the @command{pwmd} @option{-f}
command line option, @command{pwmd} will read @file{~/.pwmd/config} if it
exists, and if not, will use defaults.  Blank lines and lines beginning with
@samp{#} 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., @samp{[filename]}).  Global options may be
specified in a @samp{[global]} section and are the default options for new or
unspecified files.

A tilde @key{~} will be expanded to the home directory of the invoking user
when contained in a parameter whose value is a filename.

@cindex Reloading the configuration file
The configuration file can be reloaded by sending the @emph{SIGHUP} signal to
a @command{pwmd} process.

@cindex Global configuration options
The following options are only for use in the @samp{global} section:

@table @samp 
@item socket_path = /path/to/socket
Listen on the specified socket. The default is @file{~/.pwmd/socket}.

@item socket_perms = octal_mode
Permissions to set after creating the socket. This will override any
@cite{umask(2)} setting.

@item 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 @samp{@@}. When not specified
only the invoking user may connect.

@item disable_mlockall = boolean
When set to @var{false}, @cite{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 @var{true}.

@item log_path = /path/to/logfile
Logs informational messages to the specified file. The default is
@file{~/.pwmd/log}.

@item enable_logging = boolean
Enable or disable logging to @var{log_path}. The default is @code{false}.

@item syslog = boolean
Enable logging to @cite{syslog(8)} with facility @emph{LOG_DAEMON} and priority
@emph{LOG_INFO}. The default is @code{false}.

@item log_level = level
When @code{0}, only connections and errors are logged. When @code{1}, client
commands are also logged. When @code{2}, the command arguments are also logged.
The default is @code{0}.

@item use_agent = boolean
When true, enable @command{gpg-agent} support (@pxref{Invoking}).

@item agent_env_file = filename
A file containing the @env{GPG_AGENT_INFO} environment variable and value as
output by the @command{gpg-agent} @option{--write-env-file} command line
option.

@item kill_scd = boolean
Kill @command{scdaemon} after each @code{OPEN} (@pxref{OPEN}) or @code{SAVE}
(@pxref{SAVE}) command.

@item 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.

@item disable_list_and_dump = boolean
When @code{true}, the @code{XPATH}, @code{XPATHATTR}, @code{LIST} and
@code{DUMP} protocol commands (@pxref{Commands}) will be disabled.

@item cache_push = file1,file2
A comma separated list of filenames that will be pushed into the file cache
upon startup. @command{pwmd} will prompt for the passphrase for each file unless
specified with the @var{passphrase} or @var{passphrase_file} parameters in a
matching file section.

@item priority = integer
The priority, or niceness, of the server. The default is inherited from the
parent process.

@item cipher = algorithm
The default cipher to use for data encryption. The algorithm must be one of:
@code{aes128}, @code{aes192}, @code{aes256}, @code{serpent128},
@code{serpent192}, @code{serpent256}, @code{camellia128},
@code{camellia192}, @code{camellia256}, @code{3des}, @code{cast5},
@code{blowfish}, @code{twofish128} or @code{twofish256}. The default is
@code{aes256}.

@item cipher_iterations = integer
The number of times to encrypt the XML data. This differs from the
@var{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.

@item 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.

@item 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.

@item pinentry_path = /path/to/pinentry
The location of the @command{pinentry} binary. This program is used to
prompt for a passphrase when not using @command{gpg-agent}. The default
is specified at compile time.

@item 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.
@end table

@cindex Data file configuration options
The following options are defaults for new files when specified in the
@samp{global} section. When placed in a data file section they are options
specific to that data file only.

@table @samp 
@item backup = boolean
Whether to create a backup of the data file when saving. The backup filename
has the @file{.backup} extension appended to the opened file. The default is
@code{true}. 

@item cache_timeout = seconds
The number of seconds to keep the cache entry for this file. If @code{-1}, the
cache entry is kept forever. If @code{0}, each time an encrypted file is
@code{OPEN}ed (@pxref{OPEN}) a passphrase will be required. The default
is @code{-1}.

@item xfer_progress = bytes
Commands that send data lines to the client will also send the @code{XFER}
status message (@pxref{Status Messages}) after the specified number of bytes
have been sent. The number of bytes is rounded to @var{ASSUAN_LINELENGTH} or
@code{1002} bytes. The default is @code{8196}.

@item passphrase = string
The passphrase to use for this file. If specified in the @samp{global} section
then @samp{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.

@item passphrase_file = /path/to/file
Same as the @var{passphrase} parameter above but obtains the passphrase from
the specified filename.

@item recursion_depth = integer
The maximum number of times to resolve a @code{target} attribute for an
element in an element path (@pxref{Target Attribute}). An error is returned
when this value is exceeded.  The default is @code{100} but can be disabled by
setting to @code{0} (@emph{not recommended}).

@end table
@menu
* TLS::                   Remote connections over TLS.
* Pinentry::              Configuration file and defaults.
@end menu

@node TLS, Pinentry, Configuration, Configuration
@chapter Configuring remote connections over TLS.
@ifset manverb
.P
@end ifset
Remote connections can also be made to @command{pwmd} over @abbr{TLS}.
Authentication is done by using X509 client certificates that are signed with
the same Certificate Authority (@abbr{CA}) as the server certificate.

The @abbr{CA} certificate is expected to be found in
@file{~/.pwmd/ca-cert.pem} while the @command{pwmd} server certificate and key
file should be put in @file{~/.pwmd/server-cert.pem} and
@file{~/.pwmd/server-key.pem}, respectively.

See the documentation of @command{certtool} or @command{openssl} for details
on creating self-signed certificates.

The following TLS configuration options are available:

@table @samp 
@item 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
@code{false}.

@item tcp_port = integer
The TCP port to listen on when @var{enable_tcp} is @code{true}. The default is
@code{6466}.

@item tcp_bind = string
The internet protocol to listen with. Must be one of @code{ipv4}, @code{ipv6}
or @code{any} to listen for both IPv4 and IPv6 connections.

@item tcp_interface = string
Only useful if running as root.

@item tls_timeout = seconds
The number of seconds to wait for a read() or write() call on a
@abbr{TLS} client file descriptor to complete before returning an
error. The default is @var{300}.

Note that the @code{SAVE} command (@pxref{SAVE}) may take a longer time
to complete than other commands since key generation may need to be done
or do to a large @option{--cipher-iterations} setting.

@item 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.

@item 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
@code{!} then access is denied for the fingerprint. When @code{!} is
found by itself in the list it is treated as a default for remaining
fingerprints in the list. The @code{+} prefix behaves the same but
allows access.

The access control is two fold: when the client connects its SHA-1
fingerprint is matched against the list of allowed fingerprints in the
@samp{global} section. When allowed in the @samp{global} section the
connection is established and the client may proceed to @code{OPEN}
(@pxref{OPEN}) a data file. During the @code{OPEN} command the
fingerprint is checked again in a @samp{filename} section. When this
parameter is not found in a @samp{filename} section then access is granted.

@item tcp_require_key = boolean
When @code{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 @pxref{OPEN} command and the passphrase will be retrieved
from the client via a server @emph{INQUIRE}. This option is a default
for all files when specified in the @samp{global} section. The default
is @code{false}.

@item tcp_wait = integer
The time in tenths of a second to wait between TCP connections.  Setting to 0
will disable waiting. The default is @code{3}.

@item 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 @code{SECURE256}.
@end table

@node Pinentry, Commands, TLS, Configuration
@chapter Pinentry configuration
@mansect Pinentry
The @command{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 @command{pinentry} about
the terminal or X11 display before requiring the input. This is done by
using the @command{pwmd} @pxref{OPTION} protocol command. It need be
done only once per client connection. To avoid the use of
@command{pinentry} entirely, use the @code{OPTION} (@pxref{OPTION})
@option{--disable-pinentry} protocol command.

@ifclear isman
@c    Node,     Next,    Previous, Up
@node Commands, Status Messages, Pinentry, Top
@chapter Protocol commands and their syntax
@include menu.texi
@include commands.texi

@c    Node,     Next,    Previous, Up 
@node Status Messages, Target Attribute, Commands, Top 
@chapter Status messages and their meanings
Some commands send status messages to inform the client about certain
operations or as a progress indicator.  Status messages begin with a
@code{KEYWORD} followed by a status description for status messages that
require it. What status messages are sent, when, and how often depend on
configuration settings (@pxref{Configuration}). A status message sent from
@command{gpg-agent} (@inforef{Invoking GPG-AGENT,,gnupg}) is also forwarded to
the client.

@multitable @columnfractions .20 .25 .55
@headitem Message @tab Arguments @tab Description
@item CACHE
@cindex CACHE
@tab @code{<integer>}
@tab The number of cached documents. Sent to each client after connecting
(@pxref{GETINFO}) and after every cache modification.

@item CLIENTS
@cindex CLIENTS
@tab @code{<integer>}
@tab The number of connected clients (@pxref{GETINFO}). Sent to each client
when another client either connects or disconnects.

@item DECRYPT
@cindex DECRYPT
@tab @code{n} @code{total}
@tab Sent to the current client during a decrypt operation. How often this
status message is sent is determined by the @code{cipher_progress}
(@pxref{Configuration}) setting.

@item ENCRYPT
@cindex ENCRYPT
@tab @code{n} @code{total}
@tab Sent to the current client during an  encrypt operation. How often this
status message is sent is determined by the @code{cipher_progress}
(@pxref{Configuration}) setting.

@item GENKEY
@cindex GENKEY
@tab
@tab Sent once to the current client just before generating a new key-pair.

@item INQUIRE_MAXLEN
@cindex INQUIRE_MAXLEN
@tab @code{<bytes>}
@tab Sent to the client from @command{gpg-agent} when inquiring data. This
specifies the maximum number of bytes allowed for the client to send and
should not be exceeded.

@item KEEPALIVE
@cindex KEEPALIVE
@tab
@tab Sent to each idle client every @var{keepalive_interval}
(@pxref{Configuration}) seconds.

@item LOCKED
@cindex LOCKED
@tab
@tab Sent to the current client when another client is holding the lock for
the mutex associated with a file.

@item NEWFILE
@cindex NEWFILE
@tab
@tab Sent to the current client when the opened (@pxref{OPEN}) file does not
exist on the file-system.

@item XFER
@cindex XFER
@tab @code{<sent> <total>}
@tab Sent to the current client when transferring data. It has two space
delimited arguments. The first being the current amount of bytes transferred
and the other being the total bytes to be transferred.
@end multitable

@c    Node,     Next,    Previous, Up 
@node Target Attribute, Signals, Status Messages, Top 
@chapter The @code{target} attribute
@cindex target attribute
A @emph{case sensitive} attribute named @code{target} is treated specially
when found in each element of an element path. This attribute, like other
element attributes, is created or modified with the @code{ATTR} command
(@pxref{ATTR}). The value of this attribute is an existing element path
somewhere in the document.  If you are familiar with @abbr{XML} entities or
maybe the @abbr{HTML} @code{id} or @code{target} attributes or a symbolic link
in a file-system, you may find this attribute behaves similar to any of those.

To create a @code{target} attribute use the following syntax:

@example
ATTR SET target [!]element[@key{TAB}[!]child[..]] [!]element[@key{TAB}[!]child[..]]
@end example

Note the single space between the two element paths. The first element path is
where the @code{target} attribute will be created. If the element path does
not exist then it will be created.  This is the only time the @code{ATTR}
(@pxref{ATTR}) command will create elements. The attribute is created in the
final element of the element path.

The second element path is the destination of where you want the first element
path to resolve to. When an element path is passed to a protocol command
@command{pwmd} looks for a @code{target} attribute when resolving each element
and if found, "jumps" to the attribute value and continues resolving any
remaining elements.  When you want to avoid the @code{target} attribute for
any element of an element path then prefix the element with the literal
element character @samp{!}.

When an element of a element path is removed that a @code{target} attribute
resolves to then an error will occur. You may need to either update the
@code{target} attribute value with a new element path or remove the attribute
entirely. Remember that since the element contains the @code{target} attribute
it will need to be prefixed with the literal element character @samp{!} when
specifying the element path. For example, to remove a @code{target}
attribute for an element containing it:

@example
ATTR DELETE target path@key{TAB}to@key{TAB}!element
@end example

Clients should be careful of creating @code{target} loops, or targets that
resolve to themselves. See the @var{recursion_depth} (@pxref{Configuration})
configuration parameter for details.

The @code{REALPATH} command (@pxref{REALPATH}) can be used to show the element
path after resolving all @code{target} attributes.


@c    Node,     Next,    Previous, Up 
@node Signals, Concept Index, Target Attribute, Top
@chapter Recognized signals
@end ifclear
@mansect signals
Sending the @emph{SIGHUP} signal to a @command{pwmd} process will reload the
configuration file and sending @emph{SIGUSR1} will clear the entire file
cache.

@mansect see also
@ifset manverb
.BR gpg-agent (1), pinentry (1)
@end ifset

@ifclear isman
@c    Node,     Next,    Previous, Up 
@node Concept Index, , Signals, Top 
@unnumbered Concept Index


@c @printindex cp
@shortcontents 
@contents 
@end ifclear
@bye