pwmd-dump: Use gpgrt_init() and custom allocator.

[libpwmd.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.1 protocol commands and
their syntax.
@end ifinfo 
 
@menu 
* Introduction::          Overview of pwmd.
* Access Control::        ACL of a single XML element.
* 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.
* Other Attributes::      Other attributes specially handled by pwmd.
* Signals::               Signals known to pwmd.
* Concept Index::         Index of concepts.
@end menu

@c    Node,     Next,    Previous, Up 
@node Introduction, Access Control,        , 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
@dfn{Password Manager Daemon} (or @command{pwmd}) is a server that
applications connect to and send commands to put and get data
that is stored in an @abbr{OpenPGP} encrypted @abbr{XML} document. It mimics a
filesystem in a lot of ways including per element @abbr{ACL}'s, but also has
the advantage of remote connections over @abbr{TLS} and a document cache. The
document cache is needed for a data file encrypted with keys stored on a
smartcard.

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
@var{GPG_ERR_SOURCE_USER_1} being the error source.
@ifset isman
.P
You can import an existing @command{pwmd} version @var{3.0.x} data file by
dumping the raw @abbr{XML} data with
.BR pwmd-dump(1)
to a file, then
importing that file by using @command{pwmd}'s @option{--import} command line
option. Please
see the
.BR pwmd-dump(1)
manual page for details.

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 @code{TAB} delimited character string where each
@code{TAB} separates each element in the path.  For example, the element path
@code{a@code{TAB}b@code{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.

@c    Node,     Next,    Previous, Up 
@node Access Control, Invoking, Introduction, Top 
@chapter Access Control

Like a filesystem has an @abbr{ACL} to grant or limit access to directories or
files for a specific user or group, @command{pwmd} can limit a local user,
group or a @abbr{TLS} connection to a specific element path. This is done by
storing an @abbr{ACL} in the element attribute @var{_acl}. Its syntax is
similar to the @var{allowed} configuration parameter (@pxref{Configuration})
with the exception that a @abbr{TLS} fingerprint hash is prefixed with a
@code{#}.

Access is denied for all users that are not in the @abbr{ACL} of an element
with the exception of an invoking user (see the @var{invoking_user}). The
connected client must be in the @abbr{ACL} for each element in an element path
otherwise an error is returned.  As an example:

@example
<element _name="test" _acl="username,-@@wheel,root,#ABCDEF">
        <element _name="child"/>
</element>
@end example

The user @code{username} would be allowed access to the @code{test} element
but not if it is a member of the @code{wheel} group although, the @code{root}
user, who may be a member of the @code{wheel} group, is allowed. The SHA-256
TLS fingerprint hash @code{#ABCDEF} is also allowed.  No users other than an
@var{invoking_user} are allowed access to the @code{child} element.

The first user listed in the @abbr{ACL} is considered the owner of the
element. This determines which clients may modify an @var{_acl} attribute and
store content for an element. An @var{invoking_user} may always modify an 
@abbr{ACL}.

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

@mancont
@mansect options
@command{pwmd} uses @abbr{GpgME} for encryption, decryption and signing of the
@abbr{OpenPGP} data file. @abbr{GpgME} itself makes use of @command{gpg} for
these operations so some configuration of @command{gpg} may also be needed.

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 (@pxref{TLS}). @xref{Configuration} for details
about the @var{gpg_homedir} parameter.

@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 upon 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. @xref{Pinentry}.

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

@cindex Getting help 
@table @samp 
@item --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 @var{protocol} is a single character representing the protocol
to log. Use @code{a} for @code{libassuan} with @var{level} being one or more
character flags: @code{i} for init, @code{x} for context, @code{e} for engine,
@code{d} for data, @code{s} for system IO or @code{c} for control.  To debug
@code{gpgme} use @code{g} as the @var{protocol} with @var{level} being an
integer from @code{1} to @code{9}. To enable @acronym{TLS} debugging output
use @code{t} as the @var{protocol} with @var{level} being an integer from
@code{1} to @code{9}. A value over @code{10} will enable all @acronym{TLS}
debugging output with @code{1} being the default.

@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 --kill
Terminate an existing instance of pwmd. The process to terminate is determined
from the @option{--homedir} and @option{--rcfile} options.

@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 filename
The key parameters to use when generating a new key pair while importing an
@abbr{XML} file. The file contents must be in @abbr{GnuPG} @abbr{XML} format.

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

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

@item --symmetric, -s
Use symmetric or conventional encryption rather than pubic key encryption when
importing.  Signing is still possible by using the @option{--sign-keyid}
option. By default no signing is done when specifying this option.

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

@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, --force
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 --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 the @code{global} section @samp{e.g., [global]} and are the
default options for new or unspecified file sections.

A tilde @code{~} will be expanded to the home directory of the user starting
@command{pwmd} 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. Some security sensitive settings may not be used
until @command{pwmd} is restarted.

@cindex Global configuration options
The following options are only for use in the @code{[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 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 @code{allowed} parameter except that it is a list of
local usernames, group names and TLS fingerprint hashes that may use the
@command{XPATH}, @command{XPATHATTR} and @command{DUMP} commands (except when
disabled with the @code{disable_list_and_dump} option) and also who may modify
elements that have no @code{_acl} attribute or is not listed in an
@code{_acl}. It is similar to the system administrator root account but for a
data file and element paths (@pxref{Access Control}). The default is the user
the executes @command{pwmd}.

@item invoking_file = filename
A file containing one entry per line. An entry has the same syntax as the
@code{invoking_user} parameter. When both this parameter and the
@code{invoking_user} parameter are specified then the @code{invoking_user}
parameter will behave as if the @code{invoking_file} entries have been
appended to the @code{invoking_user} parameter value.

@item strict_kill = boolean
When @code{false}, the @code{KILL} command (@pxref{KILL}) will allow killing
another client that is not of the same @code{UID} or @abbr{TLS} fingerprint of
the current client and when not the @code{invoking_user}. The default us
@code{false}.

@item allowed = [-!]user,[-!]@@group,[+,][-!]#SHA-256,...
A comma separated list of local user names, group names or @abbr{TLS}
fingerprint @abbr{SHA}-256 hashes (in the case of a remote client) who are
allowed to connect.  Groups should be prefixed with a @samp{@@}. When not
specified only the user who started @command{pwmd} may connect. A username,
group name or hash may also be prefixed with a @code{-} or @code{!} 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 @code{OPEN} (@pxref{OPEN}) a data file. It also affects the cache
commands @code{CLEARCACHE} (@pxref{CLEARCACHE}) and @code{CACHETIMEOUT}
(@pxref{CACHETIMEOUT}). When not specified in a file section, any user that
can connect may also open any filename (provided they can decrypt it).

The following example would deny all users in group @code{primary} but
allow @code{username} who may be a member of @code{primary}. It will also
allow any TLS client except for the client with @abbr{TLS} fingerprint hash
@code{#ABCDEF}:

@example
allowed=-@@primary,username,+,!#ABCDEF
@end example

@item allowed_file = filename
A file containing one entry per line. An entry has the same syntax as the
@code{allowed} parameter. When both this parameter and the @code{allowed}
parameter are specified then the @code{allowed_file} entries will be appended
to the @code{allowed} parameter value.

@item encrypt_to = boolean
When @code{true} and @command{SAVE}'ing a data file, allow @command{gpg} to
append it's configured key to the list of recipients. The default is
@code{false} meaning that only keys specified with @command{SAVE}
@option{--keyid} are recipients.

@item always_trust = boolean
When @code{true}, allow encrypting to untrusted recipients or public
encryption keys. The default is @code{false}.

@item gpg_homedir = path
The location where @command{gpg} will store its public and private keys and
configuration. The default is @file{HOMEDIR/.gnupg} where @var{HOMEDIR} is the
default (@file{~/.pwmd}) or the value specified on the command line with the
@option{--homedir} command line option (@pxref{Invoking}). If you want to use
your standard @command{gpg} keyring then set this to @file{~/.gnupg}. Note
that a new instance of @command{gpg-agent} will be started when @emph{not}
using the standard keyring and that any configuration options for
@command{gpg-agent} will need to placed in
@file{HOMEDIR/.gnupg/gpg-agent.conf}.

@item disable_mlockall = boolean
When set to @code{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}. If possible, use an encrypted swap
file or partition and leave this set to @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 log_keepopen = boolean
When set to @code{false}, the log file specified with @var{log_path} will be
closed after writing each line. The default is @code{true}.

@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}, data
file recipients and signers are logged during @code{OPEN} (@pxref{OPEN}) and
@code{SAVE} (@pxref{SAVE}). When @code{2}, client commands are also logged.
The default is @code{0}.

@item kill_scd = boolean
Kill @command{scdaemon} after each @code{OPEN} (@pxref{OPEN}),
@code{SAVE} (@pxref{SAVE}) or @code{PASSWD} (@pxref{PASSWD}) command. The
default is @code{false}.

@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 @var{passphrase_file} parameter in a matching file
section.

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

@item 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 @code{50}.

@item send_state = integer
Whether to send client state changes of the current client to all connected
clients. When @code{0} no client state changes will be sent although a client
state may be obtained with the @code{GETINFO} command (@pxref{GETINFO}). When
@code{1} a status message will be sent to all connected clients.  When
@code{2} the status message will be sent only to an @code{invoking_user}
(@pxref{Configuration}). The default is @code{2}.  Disabling this option can
significantly increase the performance of @command{pwmd} when there are many
connected clients.

@end table

@cindex Data file configuration options
@ifset manverb
.P
@end ifset
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 require_save_key = boolean
Require the passphrase needed for signing before writing changes of the
document to disk reguardless of the key cache status. The default is
@code{true}. This option compliments @command{gpg-agent} option
@option{--ignore-cache-for-signing} and is used as a fail-safe.

@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{600} or 10 minutes.

@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_file = /path/to/filename
Obtain the passphrase to open the data file from @var{filename}. If specified
in the @samp{global} section then the @var{passphrase_file} is a default for
all data files. Note that if a client changes the passphrase for this data
file then the @var{passphrase_file} will need to be updated with the new
passphrase.

@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}).

@item allowed = [-]user,[-]@@group,[!]#TLSFINGERPRINT,...
Same parameter value as the @code{allowed} parameter mentioned above in
the @samp{[global]} section but grants or denies a client from opening a
specific data file. The default is to allow any client that is allowed to
connect.

@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 X.509 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
about 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. The default is
@code{any}.

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

@item keepalive_interval = seconds
Send a keepalive status message to an idle remote client.  An idle
client is one that 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 @code{60}.

@item tcp_require_key = boolean
When @code{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 @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:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0}.

@item tls_dh_level = string
The security level (bits) of the generated key exchange parameters. Possible
values are @code{low}, @code{medium} or @code{high}. The default is
@code{medium}.

@item tls_regen_interval = seconds
The interval in seconds to generate new @abbr{TLS} key exchange material. Note
that if a remote @abbr{TLS} client is connected when the interval expires then
new key generation won't happen until all remote clients have disconnected.
@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 with the
@command{OPTION} command (@pxref{OPTION}) to either set or unset needed
@command{pwmd} environment variables and by using the
@command{gpg-connect-agent} program. Please read it's documentation about the
@emph{UPDATESTARTUPTTY} 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 may depend on
configuration settings (@pxref{Configuration}).

@multitable @columnfractions .20 .25 .55
@headitem Message @tab Parameters @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
@tab Sent to the current client during a decrypt operation. How often this
status message is sent is determined by the @code{keepalive_interval}
(@pxref{Configuration}) setting.

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

@item GENKEY
@cindex GENKEY
@tab @code{[<sigkey_fpr> <pubkey_fpr>]}
@tab Sent to the current client during key generation. How often this
status message is sent is determined by the @code{keepalive_interval}
(@pxref{Configuration}) setting. The @var{sigkey_fpr} and @var{pubkey_fpr}
parameters are added when key generation has completed.

@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. How often this status message is sent is
determined by the @code{keepalive_interval} (@pxref{Configuration}) setting.

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

@item STATE
@cindex STATE
@tab @code{<client_id> <state>}
@tab Sent to specific clients (@pxref{Configuration} and @var{send_state}) to
indicate that @var{client_id} has changed to @var{state} (@pxref{GETINFO} for
client states).

@item EXPIRE
@cindex EXPIRE
@tab @code{<epoch_seconds> <epoch_future>|0}
@tab Sent to the current client when @code{GET} (@pxref{GET}) encounters an
@code{expire} (@pxref{Other Attributes}) attribute that is in the past or when
@code{STORE} (@pxref{STORE}) updates the @code{expire} attribute from the
@code{expire_increment} attribute value. The second field will be @code{0}
when @code{GET} sends this status message.  Otherwise the second field is the
time the next expiry will be.

@item PASSPHRASE_HINT
@cindex PASSPHRASE_HINT
@tab <keyid> <userid>
@tab Forwarded from @code{GpgME}. Contains information that is useful in a
@command{pinentry}. Only sent when pinentry is disabled (@pxref{OPTION}).

@item PASSPHRASE_INFO
@cindex PASSPHRASE_INFO
@tab <flags> ...
@tab Forwarded from @code{GpgME}. Contains information that is useful in a
@command{pinentry}. Only sent when pinentry is disabled (@pxref{OPTION}).
@end multitable

@c    Node,     Next,    Previous, Up 
@node Target Attribute, Other Attributes, 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[@code{TAB}child[..]] element[@code{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 as an argument 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 a commands element path.

When an element of a element path is removed that a @code{target} attribute
resolves to then an error will occur when trying to access that element. You
may need to either update the @code{target} attribute value with a new element
path or remove the attribute entirely.

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.

@emph{Note that when setting this attribute any children of the element will
be removed.}


@c    Node,     Next,    Previous, Up 
@node Other Attributes, Signals, Target Attribute, Top
@chapter Other special attributes
@cindex special attributes
In addition to the @code{target} attribute (@pxref{Target Attribute}), there
are a few other attributes that are specially handled by @command{pwmd}. The
first is the @code{_ctime} attribute which is set to the current time when an
element is created. Next is the @code{_mtime} attribute which is created when
an element is created and also updated when an element is modified. Both of
these attributes may be removed but the @code{_mtime} attribute is
automatically added again since removing an attribute is considered modifying
an element. The @code{_acl} attribute controls access to the element, beit
modifying or accessing element content, or descending into child elements.
@xref{Access Control} for details. The @code{_name} attribute contains the
name of an element.

The above mentioned attributes are considered reserved attribute names.
Reserved attributes are treated specially when a @code{target} attribute is
found for the current element. The @code{ATTR LIST} command will show these
attribute values for the current element and not the attribute values for the
resolved @code{target} element. All other non-reserved attributes for the
resolved @code{target} are appended to the @code{ATTR LIST} command output.
Other @code{ATTR} commands (@pxref{ATTR}) behave as usual. You can, for example, @code{ATTR
DELETE} a non-reserved attribute for an element that contains a @code{target}
attribute. The resolved target elements' attribute will be removed rather than
the element containing the @code{target} attribute.

Another specially handled attribute is the @code{expire} attribute. This
attribute value, like the @code{_ctime} and @code{_mtime} attributes, is a
timestamp. But this timestamp is usually in the future and for use with the
@code{GET} (@pxref{GET}) and @code{STORE} (@pxref{STORE}) commands. When the
@code{GET} command is issued, it checks for an @code{expire} attribute an
compares its' value with the current time. If the @code{expire} timestamp is in
the past then a status message is sent (@pxref{Status Messages}) to inform the
client that the element content should be updated.  When the content for an
element containing an @code{expire} attribute is set when using the
@code{STORE} command, the value of the @code{expire_increment} attribute is
added to the current time and the @code{expire} attribute value is updated.
When no @code{expire_increment} attribute is found, no modification is done of
the @code{expire} attribute.


@c    Node,     Next,    Previous, Up
@node Signals, Concept Index, Other Attributes, 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 pwmd-dump (1)
,
.BR gpg-agent (1)
,
.BR pinentry (1)
,
.BR gpg2 (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