docs: Update to add LIST --sexp.

[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.1 protocol commands and
their syntax.
@end ifinfo 
 
@menu 
* Introduction::          Overview of pwmd.
* Access Control::        ACL of a single XML element.
* Cache Control::         Key and data file cache handling.
* Invoking::              Command line options.
* Configuration::         Configuration file options.
* Commands::              Protocol commands.
* Bulk Commands::         Running multiple commands in sequence.
* Status Messages::       Status lines and their meaning.
* Target Attribute::      A kind of symbolic link.
* Other Attributes::      Other attributes specially handled by pwmd.
* Key Expiration::        What to do when a key expires.
* 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 universal 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 OpenPGP encrypted @acronym{XML} document. It mimics a filesystem in a
lot of ways including per element @acronym{ACL}'s, but also has the advantage
of remote connections over @acronym{TLS} and a document cache. The document cache is
needed for a data file encrypted with secret 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}, @command{gpgme}
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 @acronym{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 @acronym{XML} document uses the following @acronym{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 @acronym{XML} parsing errors for commonly used
characters.  A @acronym{URL} for example would be an invalid @acronym{XML}
element since the @acronym{URI} contains a @samp{:} which is also the
@acronym{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 @acronym{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, Cache Control, Introduction, Top 
@chapter Access Control

Like a filesystem has an @acronym{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 @acronym{TLS} connection to a specific element path. This is done
by storing an @acronym{ACL} in the element attribute @var{_acl}. Its syntax is
similar to the @var{allowed} configuration parameter (@pxref{Configuration})
with the exception that a @acronym{TLS} fingerprint hash is prefixed with a
@code{#}.

Access is denied for any user that is not in the @acronym{ACL} of an element
with the exception of an invoking user (see the @var{invoking_user}). The
connected client must be in the @acronym{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
@acronym{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 @acronym{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 
@acronym{ACL}.

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

@mancont
@mansect cache notes
While @command{pwmd} has its own cache settings for an @acronym{XML} document,
@command{gpg-agent} has cache settings for the keys used for crypto operations
of a data file. Specifically the @option{ignore-cache-for-signing},
@option{default-cache-ttl} and @option{max-cache-ttl} options. These
@command{gpg-agent} options may need to be adjusted depending on your usage
needs. For example, the @code{OPEN} command may not require a passphrase to
open a data file due to the gpg-agent having a cached key even though the
@code{ISCACHED} command returns an error indicating the data file is not
cached; which usually means a passphrase would be required. Keys for symmetric
data files are never kept in the @command{gpg-agent} cache regardless of
@command{gpg-agent} cache settings.

A copy-on-write operation is done for commands that modify the document; the
client that invoked the command will work on a copy of the in-memory document.
The first client to @code{SAVE} the changes to disk will require other clients
to reopen the data file due to the checksum being updated.

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

@mansect options
@command{pwmd} uses GpgME for encryption, decryption and signing of the
OpenPGP data file. GpgME itself makes use of @command{gpg} for these
operations so some configuration of @command{gpg} may be needed.  Pwmd spawns
a separate @command{gpg-agent} process when @var{gpg_homedir}
(@pxref{Configuration}) is not set to an instance of an already running
gpg-agent. Any @command{gpg} configuration options that you need set should be
put in @var{~/.pwmd/.gnupg/gpg.conf} or the @var{gpg.conf} file located in
@var{gpg_homedir}. The same is true for the @var{gpg-agent.conf} file to set
any required @command{gpg-agent} options.

It is recommended to pass the @option{--allow-preset-passphrase}
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 is the default
as of gnupg-2.1.15). This option allows a passphrase to be inquired from
@command{pwmd} when a @command{pinentry} is unavailable to the client
(@pxref{TLS}).

If you would like to use a keypair from your default gnupg keyring located in
~/.gnupg, but would still like to use a separate gpg-agent process (the
default), you would need to first export the public key from the default
keyring then import it into the keyring that pwmd uses. You can do this by
first exporting the public key, then use the @option{--homedir ~/.pwmd/.gnupg}
option of @command{gpg} to import it into the new keyring. For private keys,
you would need to copy the private key associated with the exported public key
to @var{~/.pwmd/.gnupg/private-keys-v1.d}. If the private key is stored on
a smartcard you can also use the @code{KEYINFO --learn} command
(@pxref{KEYINFO}).

@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 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 the @acronym{XML} @var{filename}. When @var{filename} is @code{-} the
@acronym{XML} is read from @code{stdin}. The @acronym{XML} file should be in conformance to
the @command{pwmd} @acronym{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 --output, -o filename|-
When importing, write the encrypted data file to @var{filename}. When
@var{filename} is @code{-} output will be written to @code{stdout}.

@item --passphrase-file, -k filename"
Obtain the passphrase to use when importing from the specified @var{filename}.

@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
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 --userid string
When importing, the user id used to identify the generated key. This should be
in the form @code{First Last <email>}.

@item --algo string
When importing, the algorithm to use when generating the new key pair. The
default is determined by @command{gpg}.

@item --expire seconds
When importing, the time, in seconds since epoch, when the generated key will
expire. Specifying @code{0} will never expire the key. The default is three
years.

@item --no-passphrase
When importing, don't require a passphrase for the generated key.

@item --disable-dump
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 --force
Ignore cache pushing failures on startup. By default, @command{pwmd} will exit
if an error occurred due 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 changed
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 backlog = integer
The number of connections to queue. When this limit is reached then new
connections will be refused. The default is @code{128}.

@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 @acronym{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_open = boolean
When @code{true}, disallow creation of a new data file when the current client
is not an @code{invoking_user}. The default is @code{false}.

@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 @acronym{TLS} fingerprint of
the current client and when not an @code{invoking_user}. The default us
@code{false}.

@item allowed = [-!]user,[-!]@@group,[-!]/path/to/exec,[+,][-!]#SHA-256,...
A comma separated list of local user names, group names or @acronym{TLS}
fingerprint SHA-256 hashes (in the case of a remote client) which are
allowed to connect.  Groups should be prefixed with a @samp{@@}. When not
specified only the user who started @command{pwmd} may connect. An entry in
the list may be prefixed with a @code{-} or @code{!} to prevent access. The
order of the list is important since a user may be a member of multiple
groups, for example.

Connections from local clients may also be limited by command name. A command
name is the full path to the execuatble on the filesystem. The command check
is done after all other user and group name checks. When no command is
specified all commands are allowed. When the connecting client is not of the
same @acronym{UID} as the user that invoked @command{pwmd} this feature is
ignored.

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 client
allowed to connect may also open any filename provided they can decrypt it.
Note that when specified in a file section that any @var{allowed} parameter in
the @code{global} seciton is not considered.

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 @acronym{TLS} client except for the client with @acronym{TLS}
fingerprint hash @code{#ABCDEF}. For local connections, the connecting client
must be using the /usr/bin/pwmc program:

@example
allowed=-@@primary,username,+,!#ABCDEF,/usr/bin/pwmc
@end example

@item allowed_file = filename
A file containing one entry per line. An entry has the same syntax as the
@code{allowed} parameter except that a line beginning with a semicolon is
ignored. 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
Attempt to kill @command{scdaemon} after a client disconnects.  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 to be cached 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 while waiting for a
file lock and returning an error. The default is @code{50}.

@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 regardless 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 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
In addition to connecting to @command{pwmd} via a Unix Domain Socket, remote
connections can also be made to @command{pwmd} over @acronym{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
@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 @acronym{TLS} configuration options are available:

@table @samp 
@item enable_tcp = boolean
Whether to enable @acronym{TCP}/@acronym{TLS} server support. If enabled, both @acronym{TCP} and the local
unix domain socket will listen for connections. The default is
@code{false}.

@item tcp_port = integer
The @acronym{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
@acronym{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 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:-VERS-TLS1.1:-AES-128-CBC:-AES-256-CBC}.

@item tls_dh_params_file = filename
The PEM encoded filename containing DH parameters. If not specified
then DH algorithms will not be available to the client. See the
@command{openssl dhparam} or @command{certtool} manual pages for details about
generating this file.

Note that SIGHUP will not reload this file once @acronym{TLS} support has been enabled.
You will need to restart @command{pwmd} for changes to take effect.

@item tls_use_crl = boolean
When @code{true}, enabling reading of @file{~/.pwmd/crl.pem}. This
file is an X.509 Certificate Revocation List and can be used to deny clients
by adding client certificates to it. The default is @code{false}.
@command{pwmd} will need to be restarted to recognize any changes to this
file.
@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; 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, Bulk Commands, Pinentry, Top
@chapter Protocol commands and their syntax
@include menu.texi
@include commands.texi

@c    Node,     Next,    Previous, Up
@node Bulk Commands, Status Messages, Commands, Top
@chapter Running multiple commands in sequence
Multiple commands may be run in sequence by using the @code{BULK} command
(@pxref{BULK}). Using this feature may speed up remote connections since less
socket IO is needed. The @code{BULK} command uses an @emph{INQUIRE} to obtain
an canonical s-expression of commands to be run. The s-expression syntax is as
follows:

@example
(2:id<I>:<id> <P>:<prot><D>:[<data>] [2:rc<R>:<code>[|<code>...](2:id...) | 2:id...])
@end example

Each token is prefixed with an unsigned integer that specifies the length of
the token, followed by a colon '@code{:}', followed by the token itself. Pwmd
uses token pairs to create a @emph{name=value} relationship. Whitespace is
allowed between token pairs. For example, the following is valid:

@example
( 2:id 7:FirstID 4:LIST0: 2:rc 1:0 (2:id6:Second 7:GETINFO7:version))
@end example

The @code{id} token begins a new command and requires an @var{<id>} token
of length @var{<I>} to uniquely identify this command. The next token pair is
the protocol command name, without any command arguments, of length @var{<P>}
to run followed by a colon '@code{:}', followed by the command @var{<prot>}
itself, followed by the length @var{<D>} of both command arguments and data,
followed by a colon '@code{:}' and finally the @var{<data>} itself.  If no
arguments or data are needed for the command, set the length of the data
@var{<D>} to @code{0} and append the required colon '@code{:}'.

A new command enclosed in parentheses may be run when the previous command
returns an error code that matches the @var{<code>} token of length @var{<R>}
by appending @var{rc} tokens to the end of the previous commands @var{<data>}
token. You may also test another return code for the previous command by
placing the next @var{rc} token at the end of the closing parentheses of the
previous return code command.

Multiple @code{rc} @var{code}'s may be specified for a single command by
separating them with a pipe @code{|} character. This lets you specify an
@emph{if-this-and-that} expression for a commands return code.

If another command is to be run after the previous and does not specify an
@var{rc} token, the return value is ignored for the previous command and the
next command is run.  There is no limit on the number of commands or
sub-commands except for system memory.

After inquiring the commands to be run, @code{BULK} will run each command with
@var{<data>} as its argument and store the result code and data of the command
in a @code{bulk-result} canonical s-expression of the syntax:

@example
(11:bulk-result2:id<I>:<id>2:rc<R>:<code><D>:[<data>][2:id...])
@end example

The @code{11:bulk-result} token begins the result of all commands. The
@var{<id>} token of length @var{<I>} is the same that was associated with the
command from the @emph{INQUIRE}'d syntax and is prefixed with @code{2:id}. The
return code of the command is prefixed with @code{2:rc} followed by the length
@var{<R>} of the unsigned integer @var{<code>} then the return @var{<code>}
itself.  If the command returned any @var{<data>}, it is prefixed with a
length @var{<D>} and immediately following the return @var{<code>}. Otherwise,
@var{<D>} will be @code{0} and followed by a colon '@code{:}'.


@c    Node,     Next,    Previous, Up 
@node Status Messages, Target Attribute, Bulk 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. Note that since version
@code{3.1.1} of @command{pwmd} this status message is sent only once and
before the transfer begins with the @var{total} argument set to the size of the
data and the @var{sent} argument set to @code{0} leaving it to the client to
determine the progress of the transfer as the data is received.

@item STATE
@cindex STATE
@tab @code{<client_id> <state>}
@tab Sent to each client to indicate that @var{client_id} has changed to
@var{state} (@pxref{GETINFO} for client states). For a client to receive
another clients state the option @var{CLIENT-STATE} must be set.
@xref{OPTION} command.

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

@item REHANDSHAKE
@cindex REHANDSHAKE
@tab
@tab Sent to each @acronym{TLS} client just before performing a cipher renegotiation
after a SIGHUP signal was received.

@item BULK
@cindex BULK
@tab @code{BEGIN|END <command id>}
@tab Sent to the current client before and after the @code{BULK} command
(@pxref{BULK}) runs each command. The @var{<command id>} is the same that was
associated with the command in the s-expression syntax.
@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 @acronym{XML} entities or
maybe the 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, Key Expiration, 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. Neither of
these attributes may be modified by the client. 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{_age} attribute is added to the
current time and the @code{_expire} attribute value is updated.  When no
@code{_age} attribute is found, no modification is done of the @code{_expire}
attribute.


@c    Node,     Next,    Previous, Up 
@node Key Expiration, Signals, Other Attributes, Top
@chapter Key Expiration
@cindex key expiration
When a key used for signing a data file has expired there is no indication
until the next @code{SAVE} command is sent. The command will fail since one
cannot sign the data file with an expired key. The client will need to either
use a different key for signing by either specifying an existing non-expired
key, generate a new key, or change the expire time of the existing key with
@command{gpg}.

To change the expiration of the currently used signing key with @command{gpg},
use the @code{KEYINFO} command (@pxref{KEYINFO}) to obtain the fingerprint of
the signing key of the current data file, then change the expire time with
@command{gpg}:

@example
gpg --homedir ~/.pwmd/.gnupg --edit-key <fingerprint>
@end example

Then use the @code{expire} command to set the new key expire date. When
finished, use the @code{save} command to save your changes.


@c    Node,     Next,    Previous, Up
@node Signals, Concept Index, Key Expiration, 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 gpg (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