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 "11 Nov 2010" "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 .P
  26 .B pwmsh
  27 [options] [file]
  28
  29 .SH DESCRIPTION
  30 .B pwmc
  31 is a
  32 .BR libpwmd (3)
  33 client for
  34 .BR pwmd (1) .
  35 A server command is read from standard input and the command result, if any,
  36 is sent to either a file descriptor or standard output.
  37
  38 .SH OPTIONS
  39 .TP
  40 .I "\--url <string>"
  41 A string to parse that can be used for remote pwmd server details rather than
  42 the other command line options.
  43 See
  44 .B EXAMPLES .
  45
  46 .TP
  47 .I "\--socket <path>"
  48 Connect to the specified local domain socket.  The default is
  49 \fB~/.pwmd/socket\fR.
  50
  51 .TP
  52 .I "\--no-lock"
  53 Don't lock the data file upon opening it.
  54
  55 .TP
  56 .I "\--host, -h <hostname>"
  57 Establish an SSH connection to the specified hostname. See
  58 .B SSH
  59 below for how to setup the SSH host to use
  60 .BR pwmd (1)
  61 via a proxy.
  62
  63 .TP
  64 .I "\--port, -p <port>"
  65 The port of the hostname to connect to. The default is 22.
  66
  67 .TP
  68 .I "\--known-hosts, -k <filename>"
  69 An OpenSSH formatted known_hosts file that
  70 .BR libpwmd (3)
  71 will verify the hostkey against while connecting to a remote host. The default
  72 is
  73 .B ~/.ssh/known_hosts.
  74
  75 .TP
  76 .I "\--no-ssh-agent"
  77 Normally, when the SSH_AGENT_PID environment variable is set, pwmc will get
  78 authentication details from the ssh agent. When this option is specified or
  79 when the environment variable is unset, a private key must be specified on the
  80 command line with the
  81 .B -i
  82 or
  83 .B --url
  84 options. See
  85 .B ssh-add(1)
  86 for how to add a private key to the ssh agent. Note that the
  87 .B -i
  88 command line option has priority over the ssh agent. It is not possible for
  89 the
  90 .B --url
  91 option to have priority.
  92
  93 .TP
  94 .I "\--identity, -i <filename>"
  95 The
  96 .BR ssh (1)
  97 identity file to use for public key authentication. This is the only supported
  98 method of SSH authentication. Both the public and private key must be
  99 available.
 100
 101 .TP
 102 .I "\--user, -u <username>"
 103 The username to login as on the remote SSH server. The default is the invoking
 104 user.
 105
 106 .TP
 107 .I "\--get-hostkey, -g"
 108 Retrieve the OpenSSH formatted host key of the remote SSH hostname specified
 109 with
 110 .B -h .
 111 The result should be appended to the known hosts file.
 112
 113 .TP
 114 .I "\--ipv4, -4"
 115 Connect to an IPv4 host only. The default is to try an IPv6 host first, then
 116 an IPv4 host.
 117
 118 .TP
 119 .I "\--ipv4, -6"
 120 Connect to an IPv6 host only. The default is to try an IPv6 host first, then
 121 an IPv4 host.
 122
 123 .TP
 124 .I "\--name, -n <string>"
 125 Set the client name to the specified string. This string is what shows up in
 126 the
 127 .BR pwmd (1)
 128 log files. The default is "pwmc".
 129
 130 .TP
 131 .I "\--no-status"
 132 Don't show server status messages. By default, status messages are written to
 133 stderr.
 134
 135 .TP
 136 .I "\--interactive"
 137 Use an interactive pwmc shell. This will let you send more than one command
 138 per connection. See
 139 .B INTERACTIVE
 140 below for commands.
 141
 142 .TP
 143 .I "\--inquire <COMMAND>"
 144 Use this option to send commands that use a server inquire to retrieve data.
 145 Only the command name and any command options should be specified.  The
 146 command data will be read from the inquire file descriptor or stdin by
 147 default.
 148
 149 .TP
 150 .I "\--inquire-line, -L <STRING>"
 151 The initial line to send during an inquire and before any other data read from
 152 the inquire file descriptor. Use this to specify an element path without
 153 having to modify the inquire data. See
 154 .B EXAMPLES
 155 below.
 156
 157 .TP
 158 .I "\--inquire-fd <FD>"
 159 For use with
 160 .I "\--inquire"
 161 This option sets the file descriptor to read data from. The default is stdin
 162 or 0.
 163
 164 .TP
 165 .I "\--output-fd <FD>"
 166 Redirect output to the specified file descriptor. The default is stdout.
 167
 168 .TP
 169 .I "\--cipher <string>"
 170 When saving, encrypt with the specified cipher.
 171
 172 .TP
 173 .I "\--iterations, -I <integer>"
 174 Specifies the number of encryption iterations to use when
 175 .B -S
 176 is used. The default is specified in the
 177 .BR pwmd (1)
 178 server configuration.
 179
 180 .TP
 181 .I "\--save, -S"
 182 After the command has been processed and no error occurred, send the SAVE
 183 command to the server.
 184
 185 .TP
 186 .I "\--passphrase, -P <string>"
 187 The passphrase to use when required. If not set then a
 188 .BR pinentry (1)
 189 will be used if available.
 190
 191 .TP
 192 .I "\--key-file <filename>"
 193 Read the passphrase from the specified filename.
 194
 195 .TP
 196 .I "\--base64"
 197 Specifies that the passphrase is Base64 encoded.
 198 .BR pwmd (1)
 199 will decode the passphrase before encryption and decryption.
 200
 201 .TP
 202 .I "\--no-pinentry"
 203 Disable the use pinentry entirely, both with pwmd and libpwmd.
 204
 205 .TP
 206 .I "\--pinentry, <path>"
 207 The full path to the pinentry binary. The default is the
 208 .BR pwmd (1)
 209 server configured setting.
 210
 211 .TP
 212 .I "\--ttyname, <path>"
 213 The full path of the TTY for
 214 .BR pinentry (1)
 215 to prompt on. The default is the current terminal.
 216
 217 .TP
 218 .I "\--ttytype, <string>"
 219 The terminal type of the specified TTY that
 220 .BR pinentry (1)
 221 should use. This is required if
 222 .B --ttyname
 223 is specified.
 224
 225 .TP
 226 .I "\--display, <string>"
 227 The X11 display that
 228 .BR pinentry (1)
 229 should use. Note that a remote SSH
 230 .BR pinentry (1)
 231 is currently not supported. The default is the current DISPLAY if set.
 232
 233 .TP
 234 .I "\--lc-ctype, <string>"
 235 For
 236 .BR pinentry (1)
 237 localization.
 238
 239 .TP
 240 .I "\--lc-messages, <string>"
 241 For
 242 .BR pinentry (1)
 243 localization.
 244
 245 .TP
 246 .I "\--tries, <N>"
 247 The number of times before failing when an invalid passphrase is entered in
 248 the
 249 .BR pinentry (1)
 250 dialog. The default is 3.
 251
 252 .TP
 253 .I "\--timeout, <seconds>"
 254 The number of seconds before
 255 .BR pinentry (1)
 256 will timeout while waiting for a passphrase. The default is 30.
 257
 258 .TP
 259 .I "\--local-pinentry"
 260 Force using the local pinentry for passphrase retrieval. This has the same
 261 effect as specifying
 262 .B --passphrase
 263 after the
 264 .BR pinentry (1)
 265 dialog is closed.
 266
 267 .TP
 268 .I "\--force-save"
 269 Like
 270 .B --save
 271 but expire any cache entry on the server before saving. When used with
 272 .B --local-pinentry,
 273 the initial passphrase is also cleared.
 274
 275 .TP
 276 .I "\--version"
 277 Version information.
 278 .TP
 279 .I "\--help"
 280 Help text.
 281
 282
 283 .SH SSH
 284 In order to get this to work you need to put the following in your
 285 .B ~/.ssh/authorized_keys
 286 file on the remote SSH host. It should be prepended to the public key that was
 287 generated using
 288 .BR ssh-keygen (1)
 289 and specified using the
 290 .B --identity
 291 command line option:
 292
 293     command="socat gopen:$HOME/.pwmd/socket -"
 294
 295 The
 296 .BR socat (1)
 297 command can be replaced with any utility that can read from stdin and write
 298 to a local domain socket, and vice-versa.
 299
 300
 301 .SH PINENTRY
 302 .BR pinentry (1)
 303 is a program that prompts the user for input of a passphrase. This is
 304 currently not supported when connected to a remote pwmd server since X11 port
 305 forwarding is not done yet. If a pinentry is required then a local pinentry
 306 will be tried.
 307
 308 The terminal, terminal type or DISPLAY that pinentry will prompt on is either
 309 set with the command line options or uses options set in
 310 .B ~/.pwmd/pinentry.conf
 311 when available. Otherwise the current terminal and terminal type or X11
 312 DISPLAY is used.
 313
 314 The
 315 .B ~/.pwmd/pinentry.conf
 316 file contains one NAME=VALUE pair per line. Comments begin with a '#'.
 317
 318 .B PATH
 319 The full path to the location of the pinentry binary.
 320
 321 .B DISPLAY
 322 The X11 display to use.
 323
 324 .B TTYNAME
 325 The full path to the tty that pinentry should prompt on.
 326
 327 .B TTYTYPE
 328 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
 329 set.
 330
 331
 332 .SH INTERACTIVE
 333 When passed the
 334 .B --interactive
 335 option or started as
 336 .B pwmsh
 337 a shell like interface can be used. This allows sending more than one command
 338 during a connection. It's a little tricky to get server inquires to work right
 339 so two special commands were added to the shell:
 340 .P
 341 .B INQUIRE
 342 .I <COMMAND>
 343 .P
 344 .B INQUIRE_FILE
 345 .I <FILENAME>
 346 .I <COMMAND>
 347 .P
 348 The
 349 .I COMMAND
 350 is the inquire command to send with any needed command options. The data is
 351 read from stdin or from the specified
 352 .I FILENAME.
 353 All other commands are sent directly to
 354 .B pwmd(1)
 355 via
 356 .B libpwmd(3)
 357 .I pwmd_command()
 358 without modification.
 359 .P
 360 Since interactive mode uses the
 361 .B readline(3)
 362 library, the TAB character is normally interpreted as the line completion
 363 character. This conflicts with the
 364 .B pwmd(1)
 365 element separation character. In order to insert a TAB you'd first need to
 366 press CTRL-V then press TAB. See
 367 .B readline(3)
 368 for more information about line history and completion.
 369
 370
 371 .SH EXAMPLES
 372 To list the available accounts and use
 373 .BR pinentry (1)
 374 to get the passphrase (if required):
 375 .RS
 376 echo list | pwmc filename
 377 .RE
 378 .P
 379 To store an element path and save the file afterwards:
 380 .RS
 381 echo -ne 'isp\\tsmtp\\thostname\\tsomehost.com' | pwmc --inquire STORE -S filename
 382 .P
 383 And then to get the content:
 384 .P
 385 echo -ne 'get isp\\tsmtp\\thostname' | pwmc filename
 386 .RE
 387 .P
 388 Store a larger file:
 389 .RS
 390 echo -ne 'some\\telement\\tpath\\t' | cat - data_file | pwmc -S filename --inquire STORE
 391 .RE
 392 or
 393 .RS
 394 pwmc -S filename --inquire STORE --inquire-line 'some\\telement\\tpath\\t' <
 395 data_file
 396 .RE
 397 .P
 398 Clear the file cache for a single file:
 399 .RS
 400 echo 'clearcache filename' | pwmc
 401 .RE
 402 .P
 403 To list root elements of a data file which is stored on a remote pwmd server
 404 over an SSH connection:
 405 .RS
 406 echo list | pwmc --url ssh://user@hostname,~/identity,~/known_hosts filename
 407 .RE
 408 .P
 409 Start an interactive session over an SSH channel and use the SSH agent to
 410 retrieve the private key and save when finished:
 411 .RS
 412 pwmc --url ssh://user@hostname --interactive --use-agent -S filename
 413 .RE
 414
 415 .SH NOTES
 416 Be careful of newline characters when storing data. The data is transfered and
 417 stored exactly as the input is read, newlines and all. If you wonder why your
 418 new passphrase for a service doesn't work then a trailing newline character
 419 may be the reason.
 420
 421 .SH FILES
 422 .TP
 423 .B ~/.pwmd/socket
 424 Default socket to connect to.
 425 .TP
 426 .B ~/.pwmd/pinentry.conf
 427 Default settings that
 428 .BR pinentry (1)
 429 will use for the terminal, terminal type or X11 display.
 430 .TP
 431 .B @pinentry@
 432 Default location of the
 433 .BR pinentry (1)
 434 binary.
 435
 436 .SH AUTHOR
 437 Ben Kibbey <bjk@luxsci.net>
 438 .br
 439 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 440
 441 .SH "SEE ALSO"
 442 .BR pwmd (1),
 443 .BR pinentry (1),
 444 .BR ssh-keygen (1),
 445 .BR authorized_keys (5),
 446 .BR socat (1),
 447 .BR libpwmd (3)