The server uses a protocol provided by libassuan to communicate with the
client. An OK response is returned when a command succeeds or ERR along with
an error code and description, if not. When a command requests data for
retrieval (e.g., GET) the output is prefixed with D then a single SPACE then
the actual data followed by a response. Read the libassuan docs for more info
about the protocol.


PROTOCOL COMMANDS
-----------------
OPEN [--lock] [--inquire | --pinentry=[0|1]] [--base64] <filename> [<key>]
    Opens <filename> using <key>. When the filename is not found on the
    file-system a new document will be created. If the file is found, it is
    looked for in the file cache for an existing key. When found and no key
    was specified, the cached key will be used for decryption (if encrypted).
    When not found, pinentry(1) will be used to retrieve the key (see OPTIONS
    below).
    
    When the --lock option is passed then the file mutex will be locked as if
    the LOCK command had been sent after the file had been opened.

    The --inquire option disables pinentry usage and uses a server inquire to
    retrieve the filename and key arguments.

    Using pinentry for passphrase retrieval can be enabled or disabled by
    specifying the --pinentry option with the value 1 or 0 respectively. When
    no value is specified then the configuration file value will be used. If
    the passphrase is invalid then it is up to the client whether to retry or
    not.  To decrypt an encrypted file with an empty passphrase and avoid the
    pinentry dialog, use --pinentry=0.

    When a "key_file" configuration parameter has been set for the current
    file and there is no cache entry, then an --inquire must be used to
    retrieve the key.

    The --base64 option specifies that the key is Base64 encoded. It will be
    decoded before doing decryption. This allows for binary keys and may also
    be used with --inquire.


SAVE [--reset] [--inquire | --pinentry=[0|1]] [--cipher=[<string>]]
     [--iterations=[N]] [--base64] [<key>]
    Writes the XML document to disk. The file written to is the file that was
    opened using the OPEN command. If <key> is not specified then the
    currently cached key will be used. If the file is a new file or the file
    isn't found in the file cache then <key> will be used. If both <key> is
    not specified and the file is not cached then pinentry(1) will be used to
    retrieve the key (see below) unless the configured number of iterations is
    0 in which case the file will be saved unencrypted.

    Note that when both <key> is specified and the configured number of
    iterations is 0 the iterations for the current filename will be reset to
    1. This is to be on the safe side and prevent misuse.

    The --iterations option can be used to change the number of encryption
    iterations for the opened file. When 0 no encryption will be performed.
    When this option is either not passed or is specified without a value then
    previous setting obtained from the file header will be used.

    You can specify an alternate cipher to encrypt with by specifying a cipher
    string with the --cipher option. Omitting the string uses the current
    cipher of the opened file or the default if the file is a new one. The
    default is specified in the configuration file. See pwmd(1) for available
    ciphers.

    Using pinentry for passphrase retrieval can be enabled or disabled by
    specifying the --pinentry option with the value 1 or 0, respectively. When
    no value is specified then the configuration file value will be used.
    When enabled and the passphrase confirmation fails, the pinentry process
    is started over again until either the passphrases match or until the
    input is canceled by the user.  To save with encryption and with an empty
    passphrase, use --pinentry=0.

    When --reset is specified then the cached passphrase for the opened file
    will be cleared before doing the actual SAVE as if the CLEARCACHE command
    had been sent.

    The --inquire option disables pinentry usage and uses a server inquire to
    retrieve the key.

    When a "key_file" configuration parameter has been set for the current
    file and there is no cache entry, then an --inquire must be used to
    retrieve the key.

    The --base64 option specifies that the key is Base64 encoded. It will be
    decoded before doing encryption. This allows for binary keys and may also
    be used with --inquire.


ISCACHED <filename>
    An OK response is returned if the specified file is found in the file
    cache. If not found in the cache but exists on the filesystem,
    GPG_ERR_NOT_FOUND is returned. Otherwise a filesystem error is returned.


CLEARCACHE [<filename>]
    Clears a file cache entry. This will forget the timeout and key for all or
    the specified file. Always returns an OK response.


CACHETIMEOUT <filename> <seconds>
    Specify the number of seconds the specified file will be cached. -1 will
    keep the cache entry forever, 0 will require the key each time the OPEN or
    SAVE commands are used. Also see the "cache_timeout" configuration
    parameter. Returns ERR if the filename isn't cached or if the timeout is
    invalid. OK otherwise.


LIST [--no-recurse] [--verbose] [[!]element[<TAB>[!]element[...]]]
    If no element path is given then a newline separated list of root elements
    is returned with the data response. If given, then all reachable elements
    for the specified element path are returned unless the --no-recurse option
    is specified. If specified, only the child elements of the element path
    are returned without recursing into grandchildren. Each element in the
    path is prefixed with the literal '!' character when the element contains
    no "target" attribute. See THE TARGET ATTRIBUTE below.

    When the --verbose option is passed then each element path returned in the
    list will have a single space character followed by either a 0 or 1
    appended to it.  When 0, the element path has no children, otherwise it
    does have children.  When used with the --no-recurse option this may be
    useful to limit the amount of data transferred to the client.


REALPATH [!]element[<TAB>[!]element[...]]
    Resolves all "target" attributes of the specified element path and returns
    the result with a data response.


STORE [!]element[[<TAB>[!]element[...]]<TAB>[content]]
    Creates a new element tree or modifies the content of an existing element
    path. If only a single element is specified, a new root element is
    created. Otherwise, elements are TAB delimited and the content will be set
    to the last TAB delimited argument. If no content is specified after the
    last TAB then the content for the last specified element will be removed
    or empty when creating a new element.

    The only restriction of an element name is that it not contain whitespace
    or begin with the literal element character '!' unless specifying a
    literal element. There is no whitespace between the TAB delimited
    elements. It is recommended that the value or content be base 64 encoded
    when it contains control or TAB characters to prevent XML and pwmd parsing
    errors.

    PWMD reads the element path from the client via the Assuan INQUIRE
    protocol response: the STORE command is sent by itself without arguments,
    then the server responds with INQUIRE. The client then sends the element
    path prefixed with a "D " data response. The element path may extend
    multiple lines but each must be prefixed with the data "D " response. When
    finished, the client sends "END" on an empty line. This is needed so an
    element path and value can be more than 1000 bytes long, the Assuan
    protocol line limit.


RENAME [!]element[<TAB>[!]element[...]] <value>
    Renames the specified element to the new value. If an element of the same
    name as the value exists then it will be overwritten.


COPY [!]element[<TAB>[!]element[...]] [!]element[<TAB>[!]element[...]]
    Copies the entire element tree starting from the child node of the source
    element path, to the destination element path. If the destination element
    path doesn't exist then it is created; otherwise it is overwritten.

    Note that attributes from the source element path are merged into the
    destination element path when the destination element path exists. When an
    attribute of the same name exists in both the source and destination
    element paths then the destination attribute will be updated to the source
    attribute value.


MOVE [!]element[<TAB>[!]element[...]] [[!]element[<TAB>[!]element[...]]]
    Moves the source element path to the destination element path. If the
    destination is not specified then it will be moved to the root of the
    document. If the destination is specified and exists then it will be
    overwritten; otherwise it will be created.


DELETE [!]element[<TAB>[!]element[...]]
    Removes the specified element path from the XML document.


GET [!]element[<TAB>[!]element[...]]
    Retrieves the content or XML text node of the specified element path. The
    data is returned with a data response.


ATTR SET|GET|DELETE|LIST [<attribute>] [!]<arg1> [!][arg2]
    ATTR SET attribute [!]element[<TAB>[!]element[...]] [attribute_value]
	Stores or updates an attribute name and optional value of an element
        path.

    ATTR DELETE attribute [!]element[<TAB>[!]element[...]]
	Removes an attribute from an element path.

    ATTR LIST [!]element[<TAB>[!]element[...]]
	Gets a newline separated list of attributes from an element path.

    ATTR GET attribute [!]element[<TAB>[!]element[...]]
	Gets the value of an attribute from an element path.

    The "_name" attribute (case sensitive) cannot be removed with ATTR DELETE
    if the element path is the root element. Although it can be SET to change
    the element name but only if the destination element name doesn't exist.
    Use the RENAME command for that instead.

    There is another special attribute "_mtime" which is updated each time an
    element is modified: either by storing content, editing attributes or
    deleting a child element.

    Also see THE TARGET ATTRIBUTE below.


XPATH <expression>[<TAB>[value]]
    Evaluates an XPath expression. If no value argument is specified, it is
    assumed the expression is a request to return a result. Otherwise, the
    result is set to the value argument and the document is updated. If there
    is no value after the <TAB> character, the value is assumed to be empty
    and the document is updated.


XPATHATTR SET|DELETE <name> <expression>[<TAB>[<value>]]
    Like the XPATH command but operates on element attributes and won't return
    a result. For the SET operation the <value> is optional but the field is
    required in which case the value will be empty.


IMPORT <content>[<TAB>[!]element[<TAB>[!]element[...]]]
    Like the STORE command (an INQUIRE), but the content argument is raw XML
    data. The content is created as a child of the specified element path. If
    an element of the element path does not exist then it is created. If no
    element path is specified then the content must begin with an pwmd DTD
    root element.

    Note that the new content must begin with an XML element node. Also note
    that an existing child node of the same element name as the root node of
    the imported content will be overwritten.


DUMP
    Shows the in memory XML document with indenting. To dump a specific
    element tree, use the XPATH command.


LOCK
    Locks the mutex associated with the opened file. This prevents other
    clients from sending commands to the same opened file until the client
    that sent this command either disconnects or sends the UNLOCK command.


UNLOCK
    Unlocks the file mutex which was locked with the LOCK command.


GETPID
    Retrieves the process id of the server.


GETCONFIG [filename] <parameter>
    Returns the value of a pwmd configuration variable with a data response.
    If no file has been opened then the value for the specified file or the
    default from the "global" section will be returned. If a file has been
    opened and no filename is specified, the value previously set with the SET
    command, if any, will be returned.

    If there is no such configuration parameter defined, GPG_ERR_NO_VALUE is
    returned.


VERSION
    Returns the server version number with a data response.


SET <NAME>=<VALUE>
    Sets an option NAME to VALUE. See OPTIONS below for available options.


UNSET <NAME>
    Resets option NAME to the value specified in the server configuration
    file. Some options have no default and will be reset to NULL or 0
    depending on the type.


LS
    Lists the contents of the configured data_directory. The result is a
    newline separated list of filenames.


BYE
    Closes the connection disconnecting the client. Unless the SAVE command
    had been sent, any changes to the document will be lost.


OPTIONS
-------
Below are the available client options:

    NAME             |VALUE     |Description
    -----------------|----------|----------------------------------------------
    ENABLE_PINENTRY   0|1        When 0, disable use of pinentry. The default
                                 is 1.
				 * Deprecated. Use --pinentry instead.

    PINENTRY_TIMEOUT  <integer>  The number of seconds before the pinentry
				 process will terminate while waiting for a
				 passphrase. The default is 20, 0 disables.

    PINENTRTY_PATH    <string>   Full path to the pinentry binary. The default
                                 is specified at compile time.

    TTYNAME           <string>   Same as the --ttyname option to pinentry(1).

    TTYTYPE           <string>   Same as the --ttytype option to pinentry(1).

    DISPLAY           <string>   Same as the --display option to pinentry(1).

    TITLE             <string>   Sets the title string of the pinentry dialog.

    PROMPT            <string>   Sets the prompt string of the pinentry dialog.

    DESC              <string>   Sets the error or description string of the
                                 pinentry dialog.

    LC_CTYPE          <string>   Same as the --lc-ctype option to pinentry(1).

    LC_MESSAGES       <string>   Same as the --lc-messages option to
                                 pinentry(1).

    NAME              <string>   Associates the thread ID of the connection
				 with the specified textual representation.
				 Useful for debugging log messages.

    CIPHER            <string>   The cipher to use for the next SAVE.
				 * Deprecated. Use --cipher instead.

    ITERATIONS        <integer>  The number of encryption iterations to do
                                 when the SAVE command is sent. An opened file
                                 is needed when setting this option. The
                                 CONFIG status message is sent after receiving
                                 this command.
				 *Deprecated. Use --iterations instead.

    LOCK_ON_OPEN      0|1        If enabled then the file mutex will be locked
                                 after a successful OPEN as if the LOCK
                                 command had been sent.
				 * Deprecated. Use --lock instead.

    RC_ON_LOCKED      0|1        If enabled then return an error code instead
				 of a status message when the file mutex is
                                 locked by another thread.

To reset an option to its default value, use the UNSET command.


STATUS MESSAGES
---------------
Some commands send a status message to the client when successful or as a
progress indicator. Status messages begin with a KEYWORD followed by the
status description. What messages are sent, when, and how often, depend on
configuration settings:

    COMMAND      | KEYWORD
    -------------|-------------
    <ALL>	  LOCKED

    OPEN          DECRYPT
		  DECOMPRESS
		  CACHE

    SAVE          COMPRESS
		  ENCRYPT
		  CACHE

    GET		  XFER

    LIST	  XFER

    DUMP	  XFER

    XPATH	  XFER

    CLEARCACHE    CACHE

    CACHETIMEOUT  CACHE


    KEYWORD    |OUTPUT FORMAT
    -----------|--------------------
    CACHE       <slots used>
		Sent to each client after the file cache changes.

    ENCRYPT     <iterations so far> <total iterations>

    DECRYPT     <iterations so far> <total iterations>

    COMPRESS    <bytes so far> <total bytes>

    DECOMPRESS  <bytes so far> <total bytes>

    XFER	<bytes so far> <total bytes>

    LOCKED	When another thread owns a mutex lock that the current thread
		needs, this is status message is sent and the thread will
		block until the lock can be obtained.

    KEEPALIVE	Sent to each client after every configured amount of
		seconds. It is important that this status message be sent to
		test for client connectivity.

    CONFIG	Sent to each client after the configuration file has
		been reloaded or has had a value changed that may affect other
		connected clients.

    CLIENTS	<count>
		Sent to each client after a client connects or disconnects.


THE TARGET ATTRIBUTE
--------------------
There is a special attribute "target" (case sensitive) that can be set with
ATTR SET. The value of this attribute is an element path that is located
somewhere else in the XML document and are alot like how XPath treats
entities, but is needed do to how pwmd commands are implemented. The syntax
is as follows:

ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
                arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the element path of where the "target" attribute (arg1) is to be stored
doesn't exist then it will be created. This is the only time the ATTR command
will create elements.

When a protocol command requests <arg1> as the element path then the path will
be modified to use <arg2>. This is useful if you need elements to share the
same data. If the target is modified, the other elements "pointing" to the
target will have the same content. To get the real or literal element and
ignore any "target" attributes, prefix the element with a '!' character.
Another way to think of this attribute is that it's like a symbolic link in a
filesystem. Here's an example XML document:

    <pwmd>
    	<element _name="a">
	    <element _name="child">value a</element>
	</element>
	<element _name="b" target="a">
	    <element _name="element_b">value b</element>
	</element>
	<element _name="c" target="b"/>
	<element name="d" target="!b"/>
    </pwmd>

Example:
    C> LIST b
    S> b
    S> b !child

Notice that there is not an <element_b> listed. This is because of the
"target" attribute. The target attribute is recursive too, meaning that it can
point to other elements with a "target" attibute:

    C> LIST c
    S> c
    S> c !child

To get the value of an element with a "target" attribute without resolving the
target, prefix the element with the literal element character '!':

    C> LIST !b
    S> !b
    S> !b !element_b

A "target" attribute value may also contain the literal element character:

    C> LIST d
    S> d
    S> d !element_b

The value of the "target" attribute isn't limited to only one element. It can
be a full element path with literal element characters placed where needed.
Use the REALPATH command to resolve all "target" attributes.

The "target" attribute is considered for all commands that support an element
path. If the target element has been renamed or deleted afterwards, the
command will fail.

Clients should be careful of creating target loops or targets which resolve to
themselves. See the "recursion_depth" configuration parameter for details.


XML DOCUMENT STRUCTURE
----------------------
When importing an XML data file with the -I command line option, the document
should have the following DTD:

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

The "pwmd" element is the document root node while all other elements of the
document have the name "element" with an attribute "_name" which is used as
the reference to the current "element". It's done this way so commonly used
characters that would normally cause the XML parser to throw an error while
parsing an XML element won't because the element name is stored as an XML
attribute which has more loose restrictions in their values. See THE TARGET
ATTRIBUTE for an example document.


Ben Kibbey <bjk@luxsci.net>
http://bjk.sourceforge.net/pwmd/
