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