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