From a96af5428ceee4fb2d1c7ce92cd24fe8e09a49fa Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Wed, 27 Feb 2013 23:01:40 -0500 Subject: [PATCH] Generate HTML from the texinfo source and include it in the dist. --- README | 4 +- doc/Makefile.am | 7 +- doc/pwmd.html | 2306 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 2314 insertions(+), 3 deletions(-) create mode 100644 doc/pwmd.html diff --git a/README b/README index 637a0e83..00457279 100644 --- a/README +++ b/README @@ -86,8 +86,8 @@ or A more user-friendly client QPwmc is also available. It has a Qt GUI and is much easier to use. See http://qpwmc.sourceforge.net/ for details. -Please read the pwmd.info manual for protocol commands, syntax and -configuration details after installation. +Please read pwmd.info manual for protocol commands, syntax and +configuration details. A HTML version is also available in doc/pwmd.html. GIT Repository diff --git a/doc/Makefile.am b/doc/Makefile.am index f00a19cd..a6e3b2e0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ EXTRA_DIST = config.example magic extract-help-text.awk commands.texi \ - menu.texi pwmd.1 + menu.texi pwmd.1 pwmd.info pwmd.html man1_MANS = pwmd.1 info_TEXINFOS = pwmd.texi @@ -22,3 +22,8 @@ pwmd.1: yat2m pwmd.texi --release @VERSION@ $(top_srcdir)/doc/pwmd.texi \ > $(top_srcdir)/doc/pwmd.1; \ fi + +pwmd.html: pwmd.info + texi2html pwmd.texi + +dist-hook: pwmd.html diff --git a/doc/pwmd.html b/doc/pwmd.html new file mode 100644 index 00000000..8378a284 --- /dev/null +++ b/doc/pwmd.html @@ -0,0 +1,2306 @@ + + + + +PWMD Manual + + + + + + + + + + + + + + + + + + + + +
[Top][Contents][Index][ ? ]
+

PWMD Manual

+ + + + + + + + + + + +
1. Overview of pwmd   Overview of pwmd. +
2. Invoking pwmd   Command line options. +
3. pwmd configuration file options   Configuration file options. +
6. Protocol commands and their syntax   Protocol commands. +
37. Status messages and their meanings   Status lines and their meaning. +
38. The target attribute   A kind of symbolic link. +
39. Recognized signals   Signals known to pwmd. +
Concept Index   Index of concepts. +
+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

1. Overview of pwmd

+ + + + + + +

pwmd or Password Manager Daemon is a server that +applications connect to and send commands to store and retrieve data +that is saved in an encrypted XML document. +

+

The server uses the Assuan protocol (See (assuan)Implementation) which +is the same used by gpg-agent, pinentry and +scdaemon. It also uses libgpg-error for error reporting with +the error source set as GPG_ERR_SOURCE_USER_1. +

+ +

The XML document uses 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 +whose value uniquely identifies the element at the current element tree depth. +It is done this way to avoid XML parsing errors for commonly used +characters. A URL for example would be an invalid XML element +since the URI contains a ‘:’ which is also the 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 _name attribute +value. pwmd will stop searching for an element of an 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 element path is a <TAB> delimited character string where each +<TAB> separates each element in the path. For example, the element path +a<TAB>b<TAB>c has the following XML document structure: +

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

The only restriction of an element name is that it contain no whitespace +characters. It also cannot begin with a ‘!’ since this character is +reserved for the target attribute. See section The target attribute. +

+
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

2. Invoking pwmd

+ + + +

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

+

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

+ +

pwmd is executed as follows: +

+
 
pwmd options [ file1 ] [ …   ]
+
+ +

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

+ + +

The following command line options are supported: +

+ +
+
‘--homedir directory’
+

The root directory where pwmd will store its data and temporary files. The +default is ‘~/.pwmd’. +

+
+
‘--rcfile, -f rcfile’
+

Specify an alternate configuration file. The default is +‘~/.pwmd/config’. +

+
+
‘--use-agent’
+

Enable the use of gpg-agent and add support for data files +encrypted with a keypair. Files previously handled by +gpg-agent when this option is not specified will no longer be +able to be opened and new data files are symmetrically or conventionally +encrypted and without a public and private key. If +specified, both data file types are supported. +

+
+
‘--import, -I filename’
+

Imports an XML file. The XML file should be in conformance to +the pwmd DTD (see section Overview of pwmd). You +will be prompted for a passphrase to encrypt with. The output is written to +the filename specified with ‘--outfile’. To make use of the imported +data, place the output file in ‘~/.pwmd/data’. +

+
+
‘--keyparam S-expression’
+

The key parameters to use when generating a new key pair while importing an +XML file or when converting a version 2 data file. The argument +must be a valid S-expression (See (gcrypt)S-expressions). +

+
+
‘--keygrip hexstring’
+

Specifies the hexadecimal encoded public key-grip to use for encryption when +importing or converting. When not specified a new key-pair will be created. +

+
+
‘--sign-keygrip hexstring’
+

Specifies the hexadecimal encoded public key-grip to use for signing of the +data file when importing or converting. When not specified the generated +public key or the key specified with the ‘--keygrip’ option will be +used. +

+
+
‘--passphrase-file, -k filename"’
+

Obtain the passphrase from the specified filename. +

+
+
‘--s2k-count iterations’
+

The number of times to hash the passphrase when importing or converting. The +default is the gpg-agent calibrated value of the machine. When less than +‘65536’ the default will be used. +

+
+
‘--cipher-iterations iterations’
+

The number of symmetric encryption iterations. The value is actually N+1. The +default is 0+1. +

+
+
‘--cipher algo’
+

When importing, the cipher to use for data encryption. See the cipher +configuration parameter (see section pwmd configuration file options) for available ciphers. The +default is ‘aes256’. +

+
+
‘--convert, -C filename’
+

Converts a pwmd version 2 data file to a version 3 +data file. If encrypted, you will be prompted for a passphrase to use for +decryption unless ‘--passphrase-file’ was specified. The converted data +file will be saved to the filename specified with ‘--outfile’. All +‘--import’ related options may also be used when converting. +

+
+
‘--disable-dump, -D’
+

Disable the XPATH, XPATHATTR, LIST and DUMP +protocol commands (see section Protocol commands and their syntax). This overrides any +disable_list_and_dump configuration parameter (see section pwmd configuration file options). +

+
+
‘--no-fork, -n’
+

Run as a foreground process and do not fork into the background. +

+
+
‘--ignore’
+

Ignore cache pushing failures on startup. By default, pwmd will exit +if an error occurred do to an invalid passphrase or other error. +

+
+
‘--debug-level keyword,keyword,...’
+

Output libassuan See (assuan)Top protocol IO with the comma +separated list of output keywords. Valid keywords are: init, +ctx, engine, data, sysio and control. +

+
+
‘--version’
+

Show the version, copyright and compile time features and exit. +

+
+
‘--help’
+

Print a summary of options. +

+
+ + +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

3. pwmd configuration file options

+ + +

If no configuration file is specified with the pwmd ‘-f’ +command line option, pwmd will read ‘~/.pwmd/config’ if it +exists, and if not, will use defaults. Blank lines and lines beginning with +‘#’ 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., ‘[filename]’). Global options may be +specified in a ‘[global]’ section and are the default options for new or +unspecified files. +

+

A tilde <~> will be expanded to the home directory of the invoking user +when contained in a parameter whose value is a filename. +

+ +

The configuration file can be reloaded by sending the SIGHUP signal to +a pwmd process. +

+ +

The following options are only for use in the ‘global’ section: +

+
+
‘socket_path = /path/to/socket’
+

Listen on the specified socket. The default is ‘~/.pwmd/socket’. +

+
+
‘socket_perms = octal_mode’
+

Permissions to set after creating the socket. This will override any +umask(2) setting. +

+
+
‘allowed = user,@group,...’
+

A comma separated list of local user names or group names allowed to connect +to the socket. Groups should be prefixed with a ‘@’. When not specified +only the invoking user may connect. +

+
+
‘disable_mlockall = boolean’
+

When set to false, 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 true. +

+
+
‘log_path = /path/to/logfile’
+

Logs informational messages to the specified file. The default is +‘~/.pwmd/log’. +

+
+
‘enable_logging = boolean’
+

Enable or disable logging to log_path. The default is false. +

+
+
‘syslog = boolean’
+

Enable logging to syslog(8) with facility LOG_DAEMON and priority +LOG_INFO. The default is false. +

+
+
‘log_level = level’
+

When 0, only connections and errors are logged. When 1, client +commands are also logged. When 2, the command arguments are also logged. +The default is 0. +

+
+
‘use_agent = boolean’
+

When true, enable gpg-agent support (see section Invoking pwmd). +

+
+
‘agent_env_file = filename’
+

A file containing the GPG_AGENT_INFO environment variable and value as +output by the gpg-agent ‘--write-env-file’ command line +option. +

+
+
‘kill_scd = boolean’
+

Kill scdaemon after each OPEN (see section OPEN command) or SAVE +(see section SAVE command) command. +

+
+
‘disable_list_and_dump = boolean’
+

When true, the XPATH, XPATHATTR, LIST and +DUMP protocol commands (see section Protocol commands and their syntax) will be disabled. +

+
+
‘cache_push = file1,file2’
+

A comma separated list of filenames that will be pushed into the file cache +upon startup. pwmd will prompt for the passphrase for each file unless +specified with the passphrase or passphrase_file parameters in a +matching file section. +

+
+
‘priority = integer’
+

The priority, or niceness, of the server. The default is inherited from the +parent process. +

+
+
‘cipher = algorithm’
+

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

+
+
‘cipher_iterations = integer’
+

The number of times to encrypt the XML data. This differs from the +s2k_count parameter which specifies the number of times to hash the +passphrase used to encrypt the data. The default is 0 although 1 iteration is +still done. +

+
+
‘cipher_progress = integer’
+

Send a progress message to the client after the specified amount of encryption +or decryption iterations have been done. The default is 2000. +

+
+
‘algo = algorithm’
+

The default algorithm to use when generating a new key-pair. The default is +rsa. +

+
+
‘nbits = bits’
+

The default number of bits to use when generating a new key-pair. The default +is 2048. +

+
+
‘pinentry_path = /path/to/pinentry’
+

The location of the pinentry binary. This program is used to +prompt for a passphrase when not using gpg-agent. The default +is specified at compile time. +

+
+
‘pinentry_timeout = seconds’
+

The number of seconds to wait for a pinentry before giving up and +returning an error. This timeout value is used for both waiting for +another pinentry to complete and for the pinentry waiting for user input. +

+
+ + +

The following options are defaults for new files when specified in the +‘global’ section. When placed in a data file section they are options +specific to that data file only. +

+
+
‘backup = boolean’
+

Whether to create a backup of the data file when saving. The backup filename +has the ‘.backup’ extension appended to the opened file. The default is +true. +

+
+
‘cache_timeout = seconds’
+

The number of seconds to keep the cache entry for this file. If -1, the +cache entry is kept forever. If 0, each time an encrypted file is +OPENed (see section OPEN command) a passphrase will be required. The default +is -1. +

+
+
‘xfer_progress = bytes’
+

Commands that send data lines to the client will also send the XFER +status message (see section Status messages and their meanings) after the specified number of bytes +have been sent. The number of bytes is rounded to ASSUAN_LINELENGTH or +1002 bytes. The default is 8196. +

+
+
‘passphrase = string’
+

The passphrase to use for this file. If specified in the ‘global’ section +then ‘global’ is treated as a data filename and not a default for other +files. Note that if a client changes the passphrase for this data file then +this value is not modified and will need to be updated. +

+
+
‘passphrase_file = /path/to/file’
+

Same as the passphrase parameter above but obtains the passphrase from +the specified filename. +

+
+
‘recursion_depth = integer’
+

The maximum number of times to resolve a target attribute for an +element in an element path (see section The target attribute). An error is returned +when this value is exceeded. The default is 100 but can be disabled by +setting to 0 (not recommended). +

+
+
+ + + +
4. Configuring remote connections over TLS.   Remote connections over TLS. +
5. Pinentry configuration   Configuration file and defaults. +
+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

4. Configuring remote connections over TLS.

+

Remote connections can also be made to pwmd over TLS. +Authentication is done by using X509 client certificates that are signed with +the same Certificate Authority (CA) as the server certificate. +

+

The CA certificate is expected to be found in +‘~/.pwmd/ca-cert.pem’ while the pwmd server certificate and key +file should be put in ‘~/.pwmd/server-cert.pem’ and +‘~/.pwmd/server-key.pem’, respectively. +

+

See the documentation of certtool or openssl for details +on creating self-signed certificates. +

+

The following TLS configuration options are available: +

+
+
‘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 +false. +

+
+
‘tcp_port = integer’
+

The TCP port to listen on when enable_tcp is true. The default is +6466. +

+
+
‘tcp_bind = string’
+

The internet protocol to listen with. Must be one of ipv4, ipv6 +or any to listen for both IPv4 and IPv6 connections. +

+
+
‘tcp_interface = string’
+

Only useful if running as root. +

+
+
‘tls_timeout = seconds’
+

The number of seconds to wait for a read() or write() call on a +TLS client file descriptor to complete before returning an +error. The default is 300. +

+

Note that the SAVE command (see section SAVE command) may take a longer time +to complete than other commands since key generation may need to be done +or do to a large ‘--cipher-iterations’ setting. +

+
+
‘keepalive_interval = seconds’
+

Send a keepalive status message to an idle remote client. An idle +client is one who is not in a command. The purpose of this status +message is to disconnect a hung remote client and release any file mutex +locks so another client may open the same data file. +

+
+
‘tls_access = string[,string,...]’
+

A comma separated list of client X509 certificate fingerprints in SHA-1 +format that will be allowed to connect or open a file. If prefixed with +! then access is denied for the fingerprint. When ! is +found by itself in the list it is treated as a default for remaining +fingerprints in the list. The + prefix behaves the same but +allows access. +

+

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

+
+
‘tcp_require_key = boolean’
+

When true, require the remote client to provide the key or passphrase +to open a data file even if the file is cached. Note that the cache entry is +cleared during the see section OPEN command command and the passphrase will be retrieved +from the client via a server INQUIRE. This option is a default +for all files when specified in the ‘global’ section. The default +is false. +

+
+
‘tcp_wait = integer’
+

The time in tenths of a second to wait between TCP connections. Setting to 0 +will disable waiting. The default is 3. +

+
+
‘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 SECURE256. +

+
+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

5. Pinentry configuration

+ +

The 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 pinentry about +the terminal or X11 display before requiring the input. This is done by +using the pwmd see section OPTION command protocol command. It need be +done only once per client connection. To avoid the use of +pinentry entirely, use the OPTION (see section OPTION command) +‘--disable-pinentry’ protocol command. +

+
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

6. Protocol commands and their syntax

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
7. AGENT command   +
8. ATTR command   +
9. CACHETIMEOUT command   +
10. CLEARCACHE command   +
11. COPY command   +
12. DELETE command   +
13. DUMP command   +
14. GET command   +
15. GETCONFIG command   +
16. GETINFO command   +
17. HELP command   +
18. IMPORT command   +
19. ISCACHED command   +
20. KEYGRIP command   +
21. LIST command   +
22. LOCK command   +
23. LS command   +
24. MOVE command   +
25. NOP command   +
26. OPEN command   +
27. OPTION command   +
28. PASSWD command   +
29. REALPATH command   +
30. RENAME command   +
31. RESET command   +
32. SAVE command   +
33. STORE command   +
34. UNLOCK command   +
35. XPATH command   +
36. XPATHATTR command   +
+
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

7. AGENT command

+ +

Syntax: +

 
AGENT <command>
+
+ +

Send a gpg-agent protocol command directly to the +gpg-agent. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

8. ATTR command

+ +

Syntax: +

 
ATTR [--inquire] SET|GET|DELETE|LIST [<attribute>] [!]element[<TAB>[!]child[..]] ..
+
+ +
+
ATTR SET attribute [!]element[<TAB>[!]child[..]] [value]
+
+

Stores or updates an attribute name and optional value of an +element. When no value is specified any existing value will be removed. +

+
+
ATTR DELETE attribute [!]element[<TAB>[!]child[..]]
+
+

Removes an attribute from an element. +

+
+
ATTR LIST [!]element[<TAB>[!]child[..]]
+
+

Retrieves a newline separated list of attributes names and values +from the specified element. Each attribute name and value is space delimited. +

+
+
ATTR GET attribute [!]element[<TAB>[!]child[..]]
+
+

Retrieves the value of an attribute from an element. +

+
+ +

The _name attribute (case sensitive) cannot be removed nor modified. +Use the DELETE (see section DELETE command) or RENAME (see section RENAME command) +commands instead. +

+

The _mtime attribute is updated each time an element is modified by +either storing content, editing attributes or by deleting a child element. +The _ctime attribute is created for each new element in an element +path. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+

See section The target attribute, for details about this special attribute. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

9. CACHETIMEOUT command

+ +

Syntax: +

 
CACHETIMEOUT <filename> <seconds>
+
+ +

The time in seconds until filename will be removed from the +cache. -1 will keep the cache entry forever, 0 will require +the passphrase for each OPEN or SAVE command (see section OPEN command, +see section SAVE command). See section pwmd configuration file options, and the cache_timeout +parameter. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

10. CLEARCACHE command

+ +

Syntax: +

 
CLEARCACHE [<filename>]
+
+ +

Clears a file cache entry for all or the specified filename. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

11. COPY command

+ +

Syntax: +

 
COPY [--inquire] [!]source[<TAB>[!]child[..]] [!]dest[<TAB>[!]child[..]]
+
+ +

Copies the entire element tree starting from the child node of the source +element, to the destination element path. If the destination element path +does not exist then it will be created; otherwise it is overwritten. +

+

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

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

12. DELETE command

+ +

Syntax: +

 
DELETE [--inquire] [!]element[<TAB>[!]child[..]]
+
+ +

Removes the specified element path and all of its children. This may break +an element with a target attribute (see section The target attribute) that +refers to this element or any of its children. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

13. DUMP command

+ +

Syntax: +

 
DUMP
+
+ +

Shows the in memory XML document with indenting. See section XPATH command, for +dumping a specific node. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

14. GET command

+ +

Syntax: +

 
GET [--inquire] [!]element[<TAB>[!]child[..]]
+
+ +

Retrieves the content of the specified element. The content is returned +with a data response. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

15. GETCONFIG command

+ +

Syntax: +

 
GETCONFIG [filename] <parameter>
+
+ +

Returns the value of a pwmd configuration parameter with a +data response. If no file has been opened then the value for filename +or the default from the ‘global’ section will be returned. If a file +has been opened and no filename is specified, a value previously +set with the OPTION command (see section OPTION command) will be returned. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

16. GETINFO command

+ +

Syntax: +

 
GETINFO [--data] CACHE | CLIENTS | PID | LAST_ERROR | VERSION
+
+ +

Get server and other information: cache returns the number of cached +documents via a status message. clients returns the number of +connected clients via a status message. pid returns the process ID +number of the server via a data response. VERSION returns the server +version number and compile-time features with a data response with each +being space delimited. LAST_ERROR returns a detailed description of +the last failed command when available. See section Status messages and their meanings. +

+

When the ‘--data’ option is specified then the result will be sent +via a data response rather than a status message. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

17. HELP command

+ +

Syntax: +

 
HELP [<COMMAND>]
+
+ +

Show available commands or command specific help text. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

18. IMPORT command

+ +

Syntax: +

 
IMPORT <content>[<TAB>[!]element[<TAB>[!]child[..]]]
+
+ +

This command uses a server INQUIRE to retrieve data from the client. +

+

Like the STORE command (see section STORE command), but the content +argument is raw XML data. The content is created as a child of the +specified element path and will overwrite an existing element of the same +name. If an element of the element path does not exist then it will be +created. +

+

The content must begin with an XML element node. See section Overview of pwmd, +for details. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

19. ISCACHED command

+ +

Syntax: +

 
ISCACHED [--lock] <filename>
+
+ +

An OK response is returned if the specified filename is found +in the file cache. If not found in the cache but exists on the filesystem +then GPG_ERR_NO_DATA is returned. Otherwise a filesystem error is +returned. +

+

The ‘lock’ option will lock the file mutex of filename when the +file exists; it does not need to be opened nor cached. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

20. KEYGRIP command

+ +

Syntax: +

 
KEYGRIP [--sign] <filename>
+
+ +

Returns the hex encoded keygrip of the specified filename with a +data response. +

+

When the ‘--sign’ option is specified then the key used for signing +of the specified filename will be returned. +

+

For symmetrically encrypted data files this command returns the error +GPG_ERR_NOT_SUPPORTED. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

21. LIST command

+ +

Syntax: +

 
LIST [--inquire] [--no-recurse] [--verbose] [--with-target] [--all] [[!]element[<TAB>[!]child[..]]]
+
+ +

If no element path is given then a newline separated list of root elements +is returned with a data response. If given, then all reachable elements +of 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 resulting +element is prefixed with the literal ! character when the element +contains no target attribute. See section The target attribute, for details. +

+

When the ‘--verbose’ option is passed then each element path +returned will have zero or more flags appened to it. These flags are +delimited from the element path by a single space character. A flag itself +is a single character. Flag + indicates that there are child nodes of +the current element path. Flag E indicates that an element of an +element path contained in a target attribute could not be found. Flag +O indicates that a target attribute recursion limit was reached +(see section pwmd configuration file options). Flag T will append the resolved element path +of the target attribute contained in the current element (see below). +

+

The ‘--with-target’ option implies ‘--verbose’ and will append +an additional flag T followed by a single space then an element path. +The appended element path is the resolved path (see section REALPATH command) of the +current element when it contains a target attribute. When no +target attribute is found then no flag will be appended. +

+

The ‘--no-recurse’ option limits the amount of data returned to only +the listing of children of the specified element path and not any +grandchildren. +

+

The ‘--all’ option lists the entire element tree for each root +element. This option also implies option ‘--verbose’. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

22. LOCK command

+ +

Syntax: +

 
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. See section UNLOCK command. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

23. LS command

+ +

Syntax: +

 
LS
+
+ +

Lists the available data files stored in the data directory +(‘~/.pwmd/data’). The result is a newline separated list of filenames. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

24. MOVE command

+ +

Syntax: +

 
MOVE [--inquire] [!]source[<TAB>[!]child[..]] [[!]dest[<TAB>[!]child[..]]]
+
+ +

Moves the source element path to the destination element path. If the +destination is not specified then it will be moved to the root node of the +document. If the destination is specified and exists then it will be +overwritten; otherwise non-existing elements of the destination element +path will be created. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

25. NOP command

+ +

Syntax: +

 
NOP
+
+ +

Does nothing. Always returns successfully. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

26. OPEN command

+ +

Syntax: +

 
OPEN [--lock] <filename> [<passphrase>]
+
+ +

Opens filename using passphrase. When the filename is not +found on the file-system then a new document will be created. If the file +is found, it is looked for in the file cache. If cached and no +passphrase was specified then the cached document is opened. When not +cached, pinentry(1) will be used to retrieve the passphrase to use +for decryption unless ‘disable-pinentry’ (see section OPTION command) was +specified. +

+

When the ‘--lock’ option is passed then the file mutex will be +locked as if the LOCK command (see section LOCK command) had been sent after the +file has been opened. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

27. OPTION command

+ +

Syntax: +

 
OPTION <NAME>=<VALUE>
+
+ +

Sets a client option name to value. The value for an option is +kept for the duration of the connection. +

+
+
DISABLE-PINENTRY
+

Disable use of pinentry for passphrase retrieval. When set, a + server inquire is sent to the client to obtain the passphrase. This option + may be set as needed before the see section OPEN command, see section PASSWD command, and + see section SAVE command commands. +

+
+
TTYNAME
+

Passed to the gpg-agent and used for the pinentry dialog. +

+
+
TTYTYPE
+

Passed to the gpg-agent and used for the pinentry dialog. +

+
+
DISPLAY
+

Passed to the gpg-agent and used for the pinentry dialog. +

+
+
PINENTRY-DESC
+

Sets the description string of the gpg-agent and pinentry dialog. +

+
+
PINENTRY-TITLE
+

Sets the title string of the gpg-agent and pinentry dialog. +

+
+
PINENTRY-PROMPT
+

Sets the prompt string of the gpg-agent and pinentry dialog. +

+
+
LC-CTYPE
+

Passed to the gpg-agent and used for the pinentry dialog. +

+
+
LC-MESSAGES
+

Passed to the gpg-agent and used for the pinentry dialog. +

+
+
NAME
+

Associates the thread ID of the connection with the specified textual +representation. Useful for debugging log messages. +

+
+
LOCK-TIMEOUT
+

When not 0, the duration in tenths of a second to wait for the file +mutex which has been locked by another thread to be released before returning +an error. When -1, then an error will be returned immediately. +

+
+ + +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

28. PASSWD command

+ +

Syntax: +

 
PASSWD [--reset] [--s2k-count=N]
+
+ +

Changes the passphrase of the secret key required to open the current +file or the passphrase of a symmetrically encrypted data file. When the +‘--reset’ option is passed then the cache entry for the current +file will be reset and the passphrase, if any, will be required during the +next OPEN. See section OPEN command. +

+

The ‘--s2k-count’ option sets number of hash iterations for a +passphrase and must be either 0 to use the calibrated count of the +machine (the default), or a value greater than or equal to 65536. +See section SAVE command. This option has no effect for symmetrically encrypted data +files. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

29. REALPATH command

+ +

Syntax: +

 
REALPATH [--inquire] [!]element[<TAB>[!]child[..]]
+
+ +

Resolves all target attributes of the specified element path and +returns the result with a data response. See section The target attribute, for details. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

30. RENAME command

+ +

Syntax: +

 
RENAME [--inquire] [!]element[<TAB>[!]child[..]] <value>
+
+ +

Renames the specified element to the new value. If an element of +the same name as the value already exists it will be overwritten. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

31. RESET command

+ +

Syntax: +

 
RESET
+
+ +

Closes the currently opened file but keeps any previously set client options. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

32. SAVE command

+ +

Syntax: +

 
SAVE [--no-passphrase] [--reset] [--no-agent] [--s2k-count=N] [--cipher=<algo>] [--cipher-iterations=N] [--inquire-keyparam] [--keygrip=hexstring [--sign-keygrip=hexstring]]
+
+ +

Writes the XML document to disk. The file written to is the file that +was opened using the OPEN command (see section OPEN command). If the file is a +new one or the option ‘--inquire-keyparam’ was passed, then a new +keypair will be generated and a pinentry will be used to prompt for the +passphrase to encrypt with unless the ‘--no-passphrase’ option was +passed, in which case the data file will not be passphrase protected. +

+

The ‘--no-agent’ option disables use of gpg-agent for +passphrase retrieval and caching of new files when gpg-agent +use is enabled. The datafile will be symmetrically encrypted and will not +use or generate any keypair. +

+

The ‘--reset’ option will clear the cache entry for the current file +and require a passphrase, if needed, before saving. +

+

The ‘--cipher’ option can be used to encrypt the XML data to +an alternate cipher. The default is aes256. See the Configuration +(see section pwmd configuration file options) for available ciphers. +

+

The ‘--cipher-iterations’ option specifies the number of times to +encrypt the XML data. The default is 0 although 1 iteration is still done. +

+

The ‘--inquire-keyparam’ option will send a server INQUIRE to +the client to obtain the key paramaters to use when generating a new +keypair. The inquired data is expected to be an S-expression. If not +specified then an ‘RSA’ key of ‘2048’ bits will be generated +unless otherwise set in the configuration file (see section pwmd configuration file options). Note +that when this option is specified a new keypair will be generated +reguardless if the file is a new one or not. +

+

You can encrypt the data file to a public key other than the one that it +was originally encrypted with by passing the ‘--keygrip’ option with +the hex encoded keygrip of the public key as its argument. The keygrip may +be of any key that gpg-agent knows about. The +‘--sign-keygrip’ option may also be used to sign with an alternate +secret key. This option may be needed when using a smartcard. This option +has no effect with symmetrically encrypted data files. +

+

The ‘--s2k-count’ option sets number of hash iterations for a +passphrase. A value less-than 65536 will use the machine calibrated +value which is the default. This setting only affects new files. To change +the setting, use the PASSWD command (see section PASSWD command). This option +has no effect with symmetrically encrypted data files. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

33. STORE command

+ +

Syntax: +

 
STORE [!]element[<TAB>[!]child[..]]<TAB>[content]
+
+ +

This command uses a server INQUIRE to retrieve data from the client. +

+

Creates a new element path or modifies the content of an existing +element. If only a single element is specified then a new root element is +created. Otherwise, elements are <TAB> delimited and the content will be +set to the final <TAB> delimited element. If no content is +specified after the final <TAB>, then the content of the 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 (see section The target attribute). There is no whitespace between +the <TAB> delimited elements. It is recommended that the content of an +element be base64 encoded when it contains control or <TAB> characters +to prevent XML parsing and pwmd syntax errors. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

34. UNLOCK command

+ +

Syntax: +

 
UNLOCK
+
+ +

Unlocks the file mutex which was locked with the LOCK command or +a commands’ ‘--lock’ option (see section LOCK command, see section OPEN command, +see section ISCACHED command). +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

35. XPATH command

+ +

Syntax: +

 
XPATH [--inquire] <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. For example: +
+

 
XPATH //element[@_name='password']<TAB>
+
+
+

would clear the content of all password elements in the data file +while leaving off the trailing <TAB> would return all password +elements in XML format. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+

See http://www.w3schools.com/xpath/xpath_syntax.asp for XPATH +expression syntax. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

36. XPATHATTR command

+ +

Syntax: +

 
XPATHATTR [--inquire] SET|DELETE <name> <expression>[<TAB>[<value>]]
+
+ +

Like the XPATH command (see section XPATH command) but operates on element +attributes and does not return a result. For the SET operation the +value is optional but the field is required. If not specified then +the attribute value will be empty. For example: +
+

 
XPATHATTR SET password //element[@_name='password']<TAB>
+
+
+

would create an password attribute for each password element +found in the document. The attribute value will be empty but still exist. +

+

When the ‘--inquire’ option is passed then all remaining non-option +arguments are retrieved via a server INQUIRE. +

+

See http://www.w3schools.com/xpath/xpath_syntax.asp for XPATH +expression syntax. +

+ + +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

37. 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 +KEYWORD followed by a status description for status messages that +require it. What status messages are sent, when, and how often depend on +configuration settings (see section pwmd configuration file options). A status message sent from +gpg-agent (See (gnupg)Invoking GPG-AGENT) is also forwarded to +the client. +

+ + + + + + + + + + + + +
MessageArgumentsDescription
CACHE +<integer>The number of cached documents. Sent to each client after connecting +(see section GETINFO command) and after every cache modification.
CLIENTS +<integer>The number of connected clients (see section GETINFO command). Sent to each client +when another client either connects or disconnects.
DECRYPT +n totalSent to the current client during a decrypt operation. How often this +status message is sent is determined by the cipher_progress +(see section pwmd configuration file options) setting.
ENCRYPT +n totalSent to the current client during an encrypt operation. How often this +status message is sent is determined by the cipher_progress +(see section pwmd configuration file options) setting.
GENKEY +Sent once to the current client just before generating a new key-pair.
INQUIRE_MAXLEN +<bytes>Sent to the client from gpg-agent when inquiring data. This +specifies the maximum number of bytes allowed for the client to send and +should not be exceeded.
KEEPALIVE +Sent to each idle client every keepalive_interval +(see section pwmd configuration file options) seconds.
LOCKED +Sent to the current client when another client is holding the lock for +the mutex associated with a file.
NEWFILE +Sent to the current client when the opened (see section OPEN command) file does not +exist on the file-system.
XFER +<sent> <total>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.
+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

38. The target attribute

+ +

A case sensitive attribute named 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 ATTR command +(see section ATTR command). The value of this attribute is an existing element path +somewhere in the document. If you are familiar with XML entities or +maybe the HTML id or target attributes or a symbolic link +in a file-system, you may find this attribute behaves similar to any of those. +

+

To create a target attribute use the following syntax: +

+
 
ATTR SET target [!]element[<TAB>[!]child[..]] [!]element[<TAB>[!]child[..]]
+
+ +

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

+

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

+

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

+
 
ATTR DELETE target path<TAB>to<TAB>!element
+
+ +

Clients should be careful of creating target loops, or targets that +resolve to themselves. See the recursion_depth (see section pwmd configuration file options) +configuration parameter for details. +

+

The REALPATH command (see section REALPATH command) can be used to show the element +path after resolving all target attributes. +

+ +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

39. Recognized signals

+ +

Sending the SIGHUP signal to a pwmd process will reload the +configuration file and sending SIGUSR1 will clear the entire file +cache. +

+ + +
+ + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+ +

Concept Index

+ + +
+ + + + + + +
[Top][Contents][Index][ ? ]
+

Table of Contents

+
+ + +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

Short Table of Contents

+
+ +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

About This Document

+

+ This document was generated by me on February 27, 2013 using texi2html 1.82. +

+

+ The buttons in the navigation panels have the following meaning: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Button Name Go to From 1.2.3 go to
[ < ] BackPrevious section in reading order1.2.2
[ > ] ForwardNext section in reading order1.2.4
[ << ] FastBackBeginning of this chapter or previous chapter1
[ Up ] UpUp section1.2
[ >> ] FastForwardNext chapter2
[Top] TopCover (top) of document  
[Contents] ContentsTable of contents  
[Index] IndexIndex  
[ ? ] AboutAbout (help)  
+ +

+ where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure: +

+ + + +
+

+ + This document was generated by me on February 27, 2013 using texi2html 1.82. + +
+ +

+ + -- 2.11.4.GIT