doc/pwmc.1.in

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