doc/pwmc.1.in

   1 .\" This program is free software; you can redistribute it and/or modify
   2 .\" it under the terms of the GNU General Public License as published by
   3 .\" the Free Software Foundation; either version 2 of the License, or
   4 .\" (at your option) any later version.
   5 .\"
   6 .\" This program is distributed in the hope that it will be useful,
   7 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   8 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   9 .\" GNU General Public License for more details.
  10 .\"
  11 .\" You should have received a copy of the GNU General Public License
  12 .\" along with this program; if not, write to the Free Software
  13 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH PWMD 1 "04 Apr 2009" "Password Manager Client" "Password Manager Client"
  19 .SH NAME
  20
  21 pwmc \- send a command to a pwmd server
  22 .SH SYNOPSIS
  23 .B pwmc
  24 [options] [file]
  25
  26 .SH DESCRIPTION
  27 .B pwmc
  28 is a
  29 .BR libpwmd (3)
  30 client for
  31 .BR pwmd (1) .
  32 A server command is read from standard input and the command result, if any,
  33 is sent to either a file descriptor or standard output.
  34
  35 .SH OPTIONS
  36 .TP
  37 .I "\--socket <path>"
  38 Connect to the specified local UNIX domain socket.  The default is
  39 \fB~/.pwmd/socket\fR.
  40
  41 .TP
  42 .I "\--host, -h <hostname>"
  43 Establish an SSH connection to the specified hostname. See
  44 .B SSH
  45 below for how to setup the SSH host to use
  46 .BR pwmd (1)
  47 via a proxy.
  48
  49 .TP
  50 .I "\--port, -p <port>"
  51 The port of the hostname to connect to. The default is 22.
  52
  53 .TP
  54 .I "\--known-hosts, -k <filename>"
  55 A file containing a list of SHA1 fingerprints of remote SSH servers that
  56 .BR libpwmd (3)
  57 will check against while authenticating the remote host. Note that this file
  58 format differs from the usual
  59 .BR ssh (1)
  60 known_hosts file format.
  61
  62 .TP
  63 .I "\--identity, -i <filename>"
  64 The
  65 .BR ssh (1)
  66 identity file to use for public key authentication. This is the only supported
  67 method of SSH authentication. Both the public and private key must be
  68 available.
  69
  70 .TP
  71 .I "\--user, -u <username>"
  72 The username to login as on the remote SSH server. The default is the invoking
  73 user.
  74
  75 .TP
  76 .I "\--get-hostkey, -g"
  77 Retrieve the SHA1 fingerprint of the remote SSH hostname specified with
  78 .B -h .
  79 The result should be appended to the known hosts file.
  80
  81 .TP
  82 .I "\--ipv4, -4"
  83 Connect to an IPv4 host only. The default is to try an IPv6 host first, then
  84 an IPv4 host.
  85
  86 .TP
  87 .I "\--ipv4, -6"
  88 Connect to an IPv6 host only. The default is to try an IPv6 host first, then
  89 an IPv4 host.
  90
  91 .TP
  92 .I "\--name, -n <string>"
  93 Set the client name to the specified string. This string is what shows up in
  94 the
  95 .BR pwmd (1)
  96 log files. The default is "pwmc".
  97
  98 .TP
  99 .I "\--no-status"
 100 Don't show server status messages. By default, status messages are written to
 101 stderr.
 102
 103 .TP
 104 .I "\--inquire-fd <FD>"
 105 For commands that use an INQUIRE from the server (STORE and IMPORT), this sets
 106 the file descriptor that the data will be read from. By default, stdin is
 107 used.
 108
 109 .TP
 110 .I "\--output-fd <FD>"
 111 Redirect output to the specified file descriptor. The default is stdout.
 112
 113 .TP
 114 .I "\--save, -S"
 115 After the command has been processed and no error occurred, send the SAVE
 116 command to the server.
 117
 118 .TP
 119 .I "\--iterations, -I <integer>"
 120 Specifies the number of encryption iterations to use when
 121 .B -S
 122 is used. The default is specified in the
 123 .BR pwmd (1)
 124 server configuration.
 125
 126 .TP
 127 .I "\--passphrase, -P <string>"
 128 The passphrase to use when required. If not set then a
 129 .BR pinentry (1)
 130 will be used if available.
 131
 132 .TP
 133 .I "\--pinentry, <path>"
 134 The full path to the pinentry binary. The default is the
 135 .BR pwmd (1)
 136 server configured setting.
 137
 138 .TP
 139 .I "\--ttyname, <path>"
 140 The full path of the TTY for
 141 .BR pinentry (1)
 142 to prompt on. The default is the current terminal.
 143
 144 .TP
 145 .I "\--ttytype, <string>"
 146 The terminal type of the specified TTY that
 147 .BR pinentry (1)
 148 should use. This is required if
 149 .B --ttyname
 150 is specified.
 151
 152 .TP
 153 .I "\--display, <string>"
 154 The X11 display that
 155 .BR pinentry (1)
 156 should use. Note that a remote SSH
 157 .BR pinentry (1)
 158 is currently not supported. The default is the current DISPLAY if set.
 159
 160 .TP
 161 .I "\--lc-ctype, <string>"
 162 For
 163 .BR pinentry (1)
 164 localization.
 165
 166 .TP
 167 .I "\--lc-messages, <string>"
 168 For
 169 .BR pinentry (1)
 170 localization.
 171
 172 .TP
 173 .I "\--tries, <N>"
 174 The number of times before failing when an invalid passphrase is entered in
 175 the
 176 .BR pinentry (1)
 177 dialog. The default is 3.
 178
 179 .TP
 180 .I "\--timeout, <seconds>"
 181 The number of seconds before
 182 .BR pinentry (1)
 183 will timeout while waiting for a passphrase. The default is 30.
 184
 185 .TP
 186 .I "\--version"
 187 Version information.
 188 .TP
 189 .I "\--help"
 190 Help text.
 191
 192
 193 .SH SSH
 194 In order to get this to work you need to put the following in your
 195 .B ~/.ssh/authorized_keys
 196 file on the remote SSH host. It should be prepended to the hash of the public
 197 key that was generated using
 198 .BR ssh-keygen (1)
 199 and specified using the
 200 .B --identity
 201 command line option:
 202
 203     command="socat gopen:$HOME/.pwmd/socket -"
 204
 205 The
 206 .BR socat (1)
 207 command can be replaced with any utility that can read from stdin and write
 208 to a unix domain socket, and vice-versa.
 209
 210
 211 .SH PINENTRY
 212 .BR pinentry (1)
 213 is a program that prompts the user for input of a passphrase. This is
 214 currently not supported when connected to a remote pwmd server since X11 port
 215 forwarding is not done yet.
 216
 217 The terminal, terminal type or DISPLAY that pinentry will prompt on is either
 218 set with the command line options or uses options set in
 219 .B ~/.pwmd/pinentry.conf
 220 when available. Otherwise the current terminal and terminal type or X11
 221 DISPLAY is used.
 222
 223 The
 224 .B ~/.pwmd/pinentry.conf
 225 file contains one NAME=VALUE pair per line. Comments begin with a '#'.
 226
 227 .B PATH
 228 The full path to the location of the pinentry binary.
 229
 230 .B DISPLAY
 231 The X11 display to use.
 232
 233 .B TTYNAME
 234 The full path to the tty that pinentry should prompt on.
 235
 236 .B TTYTYPE
 237 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
 238 set.
 239
 240
 241 .SH EXAMPLES
 242 To list the available accounts and use
 243 .BR pinentry (1)
 244 to get the passphrase (if required):
 245 .RS
 246 echo list | pwmc filename
 247 .RE
 248 .P
 249 To store an element path and save the file afterwards:
 250 .RS
 251 echo -ne 'store isp\\tsmtp\\thostname\\tsomehost.com' | pwmc -S filename
 252 .RE
 253 .P
 254 Store a large file:
 255 .RS
 256 echo -en 'store blah\\tstuff\\t' | pwmc -S -I 3 filename 3<data_file
 257 .P
 258 And then to get the content:
 259 .P
 260 echo -e 'get blah\\tstuff' | pwmc filename
 261 .RE
 262 .P
 263 Clear the file cache for a single file:
 264 .RS
 265 echo 'clearcache filename' | pwmc
 266 .RE
 267 .P
 268 To list the contents of a data file which is stored on a  remote pwmd server
 269 over an SSH connection:
 270 .RS
 271 echo list | pwmc -h hostname -k host_hash -i identity_file filename
 272 .RE
 273
 274 .SH FILES
 275 .TP
 276 .B ~/.pwmd/socket
 277 Default socket to connect to.
 278 .TP
 279 .B ~/.pwmd/pinentry.conf
 280 Default settings that
 281 .BR pinentry (1)
 282 will use for the terminal, terminal type or X11 display.
 283 .TP
 284 .B @pinentry@
 285 Default location of the
 286 .BR pinentry (1)
 287 binary.
 288
 289 .SH AUTHOR
 290 Ben Kibbey <bjk@luxsci.net>
 291 .br
 292 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 293
 294 .SH "SEE ALSO"
 295 .BR pwmd (1),
 296 .BR pinentry (1),
 297 .BR ssh-keygen (1),
 298 .BR authorized_keys (5),
 299 .BR socat (1),
 300 .BR libpwmd (3)