From a97c604c62a4305e5605e424c977990f510b2ad1 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Sat, 4 Apr 2009 11:03:06 -0400 Subject: [PATCH] Updated the pwmc documentation. --- doc/pwmc.1.in | 225 ++++++++++++++++++++++++++++++++++++++++++++-------------- src/libpwmd.c | 2 +- src/pwmc.c | 2 +- 3 files changed, 172 insertions(+), 57 deletions(-) diff --git a/doc/pwmc.1.in b/doc/pwmc.1.in index f340d662..649f323b 100644 --- a/doc/pwmc.1.in +++ b/doc/pwmc.1.in @@ -15,15 +15,13 @@ \\$2 \(laURL: \\$1 \(ra\\$3 .. .if \n[.g] .mso www.tmac -.TH PWMD 1 "24 Feb 2009" "Password Manager Client" "Password Manager Client" +.TH PWMD 1 "04 Apr 2009" "Password Manager Client" "Password Manager Client" .SH NAME -pwmc \- send a command to pwmd +pwmc \- send a command to a pwmd server .SH SYNOPSIS .B pwmc -[\-hvX] [\-s ] [[\-P ] [\-D ] [\-T -] [\-N ] [\-C ] [\-M ] | \-p ] -[\-c ] [\-S [\-i ]] [\-t ] [\-d ] [\-I ] [filename] +[options] [file] .SH DESCRIPTION .B pwmc @@ -31,81 +29,189 @@ is a .BR libpwmd (3) client for .BR pwmd (1) . -A command is read from standard input and output is sent to either a file -descriptor or standard output. +A server command is read from standard input and the command result, if any, +is sent to either a file descriptor or standard output. .SH OPTIONS .TP -.I "\-X" -Disable showing of status messages from the server. By default they are -printed to stderr. -.I "\-s " -Connect to the specified socket. The default is \fB~/.pwmd/socket\fR. +.I "\--socket " +Connect to the specified local unix domain socket. The default is +\fB~/.pwmd/socket\fR. + .TP -.I "\-t " -The number of seconds before pinentry will terminate while waiting for a -password. If not specified the server default will be used. +.I "\--host, -h " +Establish an SSH connection to the specified hostname. See +.B SSH +below for how to setup the SSH host to use +.BR pwmd (1) +via a proxy. + .TP -.I "\-P " -The full path of the -.BR pinentry (1) -program. The default is specified at +.I "\--port, -p " +The port of the hostname to connect to. The default is 22. + +.TP +.I "\--known-hosts, -k " +A file containing a list of SHA1 fingerprints of remote SSH servers that +.BR libpwmd (3) +will check against while authenticating the remote host. Note that this file +format differs from the normal +.BR ssh (1) +known_hosts file format. + +.TP +.I "\--identity, -i " +The +.BR ssh (1) +identity file to use for public key authentication. This is the only supported +method of SSH authentication. Both the public and private key must be +available. + +.TP +.I "\--user, -u " +The username to login as on the remote SSH server. The default is the invoking +user. + +.TP +.I "\--get-hostkey, -g" +Retrieve the SHA1 fingerprint of the remote SSH hostname specified with +.B -h . +The result should be appended to the known hosts file. + +.TP +.I "\--ipv4, -4" +Connect to an IPv4 host only. The default is to try an IPv6 host first, then +an IPv4 host. + +.TP +.I "\--ipv4, -6" +Connect to an IPv6 host only. The default is to try an IPv6 host first, then +an IPv4 host. + +.TP +.I "\--name, -n " +Set the client name to the specified string. This string is what shows up in +the .BR pwmd (1) -compile time. +log files. The default is "pwmc". + .TP -.I "\-D " -The pinentry display to use. +.I "\--no-status" +Don't show server status messages. By default, status messages are written to +stderr. + .TP -.I "\-T " -The full path of the tty for pinentry to use. +.I "\--inquire-fd " +For commands that use an INQUIRE from the server (STORE and IMPORT), this sets +the file descriptor that the data will be read from. By default, stdin is +used. + .TP -.I "\-N " -The terminal type for pinentry to use. This is required when using -.B -T -if the invoking -.B pwmc -isn't attached to a terminal. +.I "\--output-fd " +Redirect output to the specified file descriptor. The default is stdout. + .TP -.I "\-C " -For internationalization. Sets \fBLC_CTYPE\fP in the pinentry process. +.I "\--save, -S" +After the command has been processed and no error occurred, send the SAVE +command to the server. + .TP -.I "\-M " -For internationalization. Sets \fBLC_MESSAGES\fP in the pinentry process. +.I "\--iterations, -I " +Specifies the number of encryption iterations to use when +.B -S +is used. The default is specified in the +.BR pwmd (1) +server configuration. + .TP -.I "\-p " -Use the specified password. When not specified and the file is not cached, +.I "\--passphrase, -P " +The passphrase to use when required. If not set then a .BR pinentry (1) -will be used. +will be used if available. + .TP -.I "\-S" -Send the SAVE command before exiting. +.I "\--pinentry, " +The full path to the pinentry binary. The default is the +.BR pwmd (1) +server configured setting. + +.TP +.I "\--ttyname, " +The full path of the TTY for +.BR pinentry (1) +to prompt on. The default is the current terminal. + +.TP +.I "\--ttytype, " +The terminal type of the specified TTY that +.BR pinentry (1) +should use. This is required if +.B --ttyname +is specified. + +.TP +.I "\--display, " +The X11 display that +.BR pinentry (1) +should use. Note that a remote SSH +.BR pinentry (1) +is currently not supported. The default is the current DISPLAY if set. + +.TP +.I "\--lc-ctype, " +For +.BR pinentry (1) +localization. + .TP -.I "\-i" -Encrypt with the specified number of iterations when saving. Note that -\fI-1\fP disables encryption and that \fI0\fP is really 1 iteration. +.I "\--lc-messages, " +For +.BR pinentry (1) +localization. + .TP -.I "\-d " -Writes the result of a command to the specified file descriptor. This may be -needed if your using pinentry to retrieve a password but redirecting standard -output. -.I "\-I " -Reads INQUIRE data from the specified file descriptor. Use this rather than -piping large amounts of data to save memory. +.I "\--tries, " +The number of times before failing when an invalid passphrase is entered in +the +.BR pinentry (1) +dialog. The default is 3. + .TP -.I "\-c " -Sets the client name to the specified string which will show up in log -messages. +.I "\--timeout, " +The number of seconds before +.BR pinentry (1) +will timeout while waiting for a passphrase. The default is 30. + .TP -.I "\-v" +.I "\--version" Version information. .TP -.I "\-h" +.I "\--help" Help text. + +.SH SSH +In order to get this to work you need to put the following in your +.B ~/.ssh/authorized_keys +file on the remote SSH host. It should be prepended to the hash of the public +key that was generated using +.BR ssh-keygen (1) +and specified using the +.B --identity +command line option: + + command="socat gopen:$HOME/.pwmd/socket -" + +The +.BR socat (1) +command can be replaced with any utility that can read from stdin and write +to a unix domain socket, and vice-versa. + + .SH EXAMPLES To list the available accounts and use .BR pinentry (1) -to get the password: +to get the passphrase (if required): .RS echo list | pwmc filename .RE @@ -128,6 +234,12 @@ Clear the file cache for a single file: .RS echo 'clearcache filename' | pwmc .RE +.P +To list the contents of a data file which is stored on a remote pwmd server +over an SSH connection: +.RS +echo list | pwmc -h hostname -k host_hash -i identity_file filename +.RE .SH FILES .TP @@ -147,4 +259,7 @@ Ben Kibbey .SH "SEE ALSO" .BR pwmd (1), .BR pinentry (1), +.BR ssh-keygen (1), +.BR authorized_keys (5), +.BR socat (1), .BR libpwmd (3) diff --git a/src/libpwmd.c b/src/libpwmd.c index a5ecad03..ef224013 100644 --- a/src/libpwmd.c +++ b/src/libpwmd.c @@ -189,7 +189,6 @@ static gpg_error_t _socket_connect_finalize(pwm_t *pwm) #ifdef WITH_PINENTRY pwm->pid = -1; #endif - pwm->pinentry_tries = 3; assuan_set_pointer(pwm->ctx, pwm); if (pwm->name) { @@ -2548,6 +2547,7 @@ pwm_t *pwmd_new(const char *name) h->nb_fd = -1; #endif h->pinentry_timeout = -30; + h->pinentry_tries = 3; #ifdef WITH_TCP h->prot = PWMD_IP_ANY; #endif diff --git a/src/pwmc.c b/src/pwmc.c index af088506..eff69449 100644 --- a/src/pwmc.c +++ b/src/pwmc.c @@ -93,7 +93,7 @@ static void usage(const char *pn, int status) " pinentry timeout\n" " --no-status\n" " disable showing of status messages from the server\n" - " --name \n" + " --name, -n \n" " set the client name\n" " --socket \n" " local socket to connect to (~/.pwmd/socket)\n" -- 2.11.4.GIT