From e2b688fc586758cf94279a89c35f577d0e0f1fa1 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Fri, 8 Mar 2013 20:02:53 -0500 Subject: [PATCH] Renamed TODO to TODO.org. And update. --- Makefile.am | 2 +- TODO | 28 -- TODO.org | 36 ++ doc/pwmd.html | 1528 --------------------------------------------------------- 4 files changed, 37 insertions(+), 1557 deletions(-) delete mode 100644 TODO create mode 100644 TODO.org delete mode 100644 doc/pwmd.html diff --git a/Makefile.am b/Makefile.am index 04ec8851..31675636 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -EXTRA_DIST=KnownBugs TODO ChangeLog INSTALL NEWS debian ABOUT-NLS THANKS +EXTRA_DIST=KnownBugs TODO.org ChangeLog INSTALL NEWS debian ABOUT-NLS THANKS ACLOCAL_AMFLAGS = -I m4 SUBDIRS=po doc src tests diff --git a/TODO b/TODO deleted file mode 100644 index c659236d..00000000 --- a/TODO +++ /dev/null @@ -1,28 +0,0 @@ -Here are some ideas that might make it into later versions. - -+ = started -- = not started -? = not sure to included it -* = planned - -? - Use the DBUS protocol instead of libassuan. Better asynchronous IO. More - language bindings. Better handling of large amounts of data. May be better - to hack libassuan though since DBUS is a binary protocol. Probably will - never happen. - -? - Make a specification that applications should follow when accessing or - storing the XML elements. This way two clients (one for console and - another for GUI) that require the same data (mail client) could use the - same element paths and not duplicate each others data. - - For example, a POP3 client would require a hostname, username, password - and optional port along with an SSL request (fingerprint, certificate), - etc. The root element of the service might have an attribute - "service=pop3" along with "default=1" or "active=1" (if you have more than - one POP3 account) so all the client needs to get the pop3 server info is - the type of service ("pop3" here). The client would then loop through the - LIST command output and search for the required service attribute. Using - the XPATH command would be faster (especially over remote connections) but - it won't resolve any "target" attributes and the output is raw XML which - doesn't have TAB delimited elements. But that could be fixed by the - client. diff --git a/TODO.org b/TODO.org new file mode 100644 index 00000000..3d615913 --- /dev/null +++ b/TODO.org @@ -0,0 +1,36 @@ +* TODO +** Other public key algorithms other than RSA and DSA + ELG, ECDA and ECDSA. To be honest, its beyond me at the moment. :) +** Add command line and SAVE option --sign-keyparam + To generate a new key-pair used for signing. This would require a + new inquire keyword GENKEY_SIGN. +** Port to Windows and Mac + I don't have a machine to test a Mac build on. Windows could be + done, but I have no motivation. +** Test TLS timeouts using FIONWRITE and SO_SNDLOWAT + OpenBSD and Solaris/SunOS and maybe others. + +* UNSURE +** Use the DBUS protocol instead of libassuan + Better asynchronous IO. More language bindings. Better handling of + large amounts of data. May be better to hack libassuan though since + DBUS is a binary protocol. Either will probably never happen. +** Make a specification that applications should follow + When accessing or storing the XML elements. This way two clients + (one for console and another for GUI) that require the same data + (mail client) could use the same element paths and not duplicate + each others data. + + For example, a POP3 client would require a hostname, username, + password and optional port along with an SSL request (fingerprint, + certificate), etc. The root element of the service might have an + attribute "service=pop3" along with "default=1" or "active=1" (if + you have more than one POP3 account) so all the client needs to get + the pop3 server info is the type of service ("pop3" here). The + client would then loop through the LIST command output and search + for the required service attribute. + + Using the XPATH command would be faster (especially over remote + connections) but it won't resolve any "target" attributes and the + output is raw XML which doesn't have TAB delimited elements. But + that could be fixed by the client. diff --git a/doc/pwmd.html b/doc/pwmd.html deleted file mode 100644 index c25ab1cb..00000000 --- a/doc/pwmd.html +++ /dev/null @@ -1,1528 +0,0 @@ - - -PWMD Manual - - - - - - - - - -

PWMD Manual

-
- -

-Up: (dir) - -
- - - - -
- -

-Next: , -Up: Top - -
- -

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 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 Target Attribute. - - -

- -

-Next: , -Previous: Introduction, -Up: Top - -
- -

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 Introduction). 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 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 Configuration) 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 Commands). This overrides any -disable_list_and_dump configuration parameter (see Configuration). - -
‘--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 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. -
- - -
- -

-Next: , -Previous: Invoking, -Up: Top - -
- -

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 Invoking). - -
‘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 OPEN) or SAVE -(see SAVE) command. - -
‘require_save_key = boolean’
Require the passphrase needed to open a data file before writing changes -of the documment to disk reguardless of the key cache status. - -
‘disable_list_and_dump = boolean’
When true, the XPATH, XPATHATTR, LIST and -DUMP protocol commands (see Commands) 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. - -
‘keyparam = s-expression’
The default key paramaters to use when generating a new key-pair. The -default is RSA with 2048 bits. Note that only RSA as the encryption -algorithm is supported at the moment. Both RSA and DSA keys may be used -for signing. - -
‘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 OPEN) 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 Status Messages) 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 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). - -
- - - -
- -

-Next: , -Previous: Configuration, -Up: Configuration - -
- -

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 SAVE) 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 OPEN) 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 OPEN 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. -
- -
- -

-Next: , -Previous: TLS, -Up: Configuration - -
- -

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 OPTION protocol command. It need be -done only once per client connection. To avoid the use of -pinentry entirely, use the OPTION (see OPTION) ---disable-pinentry protocol command. - - -

- -

-Next: , -Previous: Pinentry, -Up: Top - -
- -

6 Protocol commands and their syntax

- - -
- -

-Next: , -Up: Commands - -
- -

7 AGENT command

- -

Syntax: -

     AGENT <command>
-
-

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

- -

-Next: , -Previous: AGENT, -Up: Commands - -
- -

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 DELETE) or RENAME (see RENAME) -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 Target Attribute, for details about this special attribute. - -

- -

-Next: , -Previous: ATTR, -Up: Commands - -
- -

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 OPEN, -see SAVE). See Configuration, and the cache_timeout -parameter. - -

- -

-Next: , -Previous: CACHETIMEOUT, -Up: Commands - -
- -

10 CLEARCACHE command

- -

Syntax: -

     CLEARCACHE [<filename>]
-
-

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

- -

-Next: , -Previous: CLEARCACHE, -Up: Commands - -
- -

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

- -

-Next: , -Previous: COPY, -Up: Commands - -
- -

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

- -

-Next: , -Previous: DELETE, -Up: Commands - -
- -

13 DUMP command

- -

Syntax: -

     DUMP
-
-

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

- -

-Next: , -Previous: DUMP, -Up: Commands - -
- -

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

- -

-Next: , -Previous: GET, -Up: Commands - -
- -

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 OPTION) will be returned. - -

- -

-Next: , -Previous: GETCONFIG, -Up: Commands - -
- -

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 Status Messages. - -

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

- -

-Next: , -Previous: GETINFO, -Up: Commands - -
- -

17 HELP command

- -

Syntax: -

     HELP [<COMMAND>]
-
-

Show available commands or command specific help text. - -

- -

-Next: , -Previous: HELP, -Up: Commands - -
- -

18 IMPORT command

- -

Syntax: -

     IMPORT [--root [!]element[<TAB>[!]child[..]]] <content>
-
-

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

Like the STORE command (see STORE), but the content -argument is raw XML data. The content is created as a child of -the element path specified with the --root option or at the -document root when not specified. Existing elements of the same name will -be overwritten. - -

The content must begin with an XML element node. See Introduction, -for details. - -

- -

-Next: , -Previous: IMPORT, -Up: Commands - -
- -

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

- -

-Next: , -Previous: ISCACHED, -Up: Commands - -
- -

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

- -

-Next: , -Previous: KEYGRIP, -Up: Commands - -
- -

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 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 Configuration). 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 REALPATH) 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. - -

- -

-Next: , -Previous: LIST, -Up: Commands - -
- -

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

- -

-Next: , -Previous: LOCK, -Up: Commands - -
- -

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

- -

-Next: , -Previous: LS, -Up: Commands - -
- -

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

- -

-Next: , -Previous: MOVE, -Up: Commands - -
- -

25 NOP command

- -

Syntax: -

     NOP
-
-

Does nothing. Always returns successfully. - -

- -

-Next: , -Previous: NOP, -Up: Commands - -
- -

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 OPTION) was -specified. - -

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

- -

-Next: , -Previous: OPEN, -Up: Commands - -
- -

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 OPEN, see PASSWD, and -see SAVE commands. - -
PINENTRY-TIMEOUT
Sets the number of seconds before a pinentry prompt will return an error -while waiting for user input. - -
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. - -
LOG-LEVEL
An integer specifiying the logging level. -
- -
- -

-Next: , -Previous: OPTION, -Up: Commands - -
- -

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

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 SAVE. This option has no effect for symmetrically encrypted data -files. - -

- -

-Next: , -Previous: PASSWD, -Up: Commands - -
- -

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 Target Attribute, for details. - -

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

- -

-Next: , -Previous: REALPATH, -Up: Commands - -
- -

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

- -

-Next: , -Previous: RENAME, -Up: Commands - -
- -

31 RESET command

- -

Syntax: -

     RESET
-
-

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

- -

-Next: , -Previous: RESET, -Up: Commands - -
- -

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 OPEN). 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 Configuration) 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 Configuration). Note -that when this option is specified a new keypair will be generated -reguardless if the file is a new one and that if the data file is protected -the passphrase to open it will be required before generating the new keypair. - -

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 and is the default. This setting only affects new files. To change -the setting use the PASSWD command (see PASSWD). This option -has no effect with symmetrically encrypted data files. - -

- -

-Next: , -Previous: SAVE, -Up: Commands - -
- -

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

- -

-Next: , -Previous: STORE, -Up: Commands - -
- -

34 UNLOCK command

- -

Syntax: -

     UNLOCK
-
-

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

- -

-Next: , -Previous: UNLOCK, -Up: Commands - -
- -

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

- -

-Previous: XPATH, -Up: Commands - -
- -

36 XPATHATTR command

- -

Syntax: -

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

Like the XPATH command (see XPATH) 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. - - -

- -

-Next: , -Previous: Commands, -Up: Top - -
- -

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 Configuration). A status message sent from -gpg-agent (see Invoking GPG-AGENT) is also forwarded to -the client. - -

Message Arguments Description -
CACHE -<integer> -The number of cached documents. Sent to each client after connecting -(see GETINFO) and after every cache modification. - -


CLIENTS -<integer> -The number of connected clients (see GETINFO). Sent to each client -when another client either connects or disconnects. - -


DECRYPT -n total -Sent to the current client during a decrypt operation. How often this -status message is sent is determined by the cipher_progress -(see Configuration) setting. - -


ENCRYPT -n total -Sent to the current client during an encrypt operation. How often this -status message is sent is determined by the cipher_progress -(see Configuration) 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 Configuration) 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 OPEN) 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. -
- - -

- -

-Next: , -Previous: Status Messages, -Up: Top - -
- -

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 ATTR). 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 ATTR) command will create elements. The attribute is created in the -final element of the element path. - -

The second element path is the destination of where you want the first element -path to resolve to. When an element path is passed to a protocol command -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 Configuration) -configuration parameter for details. - -

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

- -

-Next: , -Previous: Target Attribute, -Up: Top - -
- -

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

- -

-Previous: Signals, -Up: Top - -
- -

Concept Index

- - -
-

Short Contents

- -
- -
-

Table of Contents

- -
- - - -- 2.11.4.GIT