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