doc/pwmc.1.in

   1 .\" Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
   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 PWMC 1 "25 Feb 2013" "@VERSION@" "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
  30 .SH DESCRIPTION
  31 .B pwmc
  32 is a
  33 .BR libpwmd (3)
  34 client for
  35 .BR pwmd (1).
  36 Pwmc reads pwmd protocol commands from either standard input or
  37 interactively by using libreadline to prompt for input. The
  38 interactive mode allows for more than one command to be sent to the
  39 pwmd server.
  40
  41 .SH OPTIONS
  42 .TP
  43 .I "\--url <string>"
  44 A pwmd URL to connect to. The available URL types depend on options
  45 enabled at compile-time. The default when not specified is
  46 .B @pwmd_socket@.
  47 See
  48 .B EXAMPLES
  49 for details.
  50
  51 .TP
  52 .I "\--connect-timeout <seconds>"
  53 The number of seconds before timing out when connecting to a remote
  54 server. The default is 120 seconds.
  55
  56 .TP
  57 .I "\--socket-timeout <seconds>"
  58 The number of seconds before a remote command will timeout. The
  59 default is 300 seconds.
  60
  61 .TP
  62 .I "\--ca-cert, <filename>"
  63 The X509 certificate authority file to use when validating the pwmd
  64 TLS server certificate. Required when connecting via TLS.
  65
  66 .TP
  67 .I "\--client-cert, <filename>"
  68 The X509 client certificate to use when authenticating a TLS
  69 connection. Required when connecting via TLS.
  70
  71 .TP
  72 .I "\--client-key, <filename>"
  73 The X509 key file to use to unlock the client certificate.  Required
  74 when connecting via TLS.
  75
  76 .TP
  77 .I "\--tls-priority, <string>"
  78 A string representing compression, cipher and hashing algorithm priorities for
  79 a TLS connection. See the GnuTLS documentation for details. The default is
  80 SECURE256.
  81
  82 .TP
  83 .I "\--tls-verify"
  84 Verify the TLS server hostname stored in the server certificate to the
  85 connected hostname. The default is disabled.
  86
  87 .TP
  88 .I "\--tls-fingerprint <string>"
  89 Verify the
  90 .BR pwmd
  91 TLS server certificate against the specified SHA-256 hash.
  92
  93 .TP
  94 .I "\--no-ssh-agent"
  95 Normally, when the SSH_AUTH_SOCK environment variable is set, pwmc will get
  96 authentication details from the ssh agent. When this option is specified or
  97 when the environment variable is unset, a private key must be specified on the
  98 command line with the
  99 .I "\-\-identity"
 100 option. See
 101 .BR ssh-add (1)
 102 for how to add a private key to the ssh agent. Note that the
 103 .I "\-\-identity"
 104 command line option has priority over the ssh agent.
 105
 106 .TP
 107 .I "\-\-identity, -i <filename>"
 108 The SSH identity file use when connecting via SSH.
 109
 110 .TP
 111 .I "\-\-knownhosts, -k <filename"
 112 The SSH knownhosts file to use when connection via SSH. The default is
 113 ~/.ssh/knownhosts.
 114
 115 .TP
 116 .I "\--no-lock"
 117 Do not lock the data file upon opening it. Locking the data file
 118 prevents other clients from opening the same file.
 119
 120 .TP
 121 .I "\--lock-timeout <N>"
 122 The time in tenths of a second to wait for another client to release the lock
 123 held on a data file before returning an error. When not specified or 0, pwmc
 124 will wait indefinately. When -1, an error will be returned
 125 immediately. The default is 50.
 126
 127 .TP
 128 .I "\--name, -n <string>"
 129 Set the client name to the specified string. This string is what is shown in
 130 the
 131 .BR pwmd (1)
 132 log files. The default is "pwmc".
 133
 134 .TP
 135 .I "\--pinentry, <path>"
 136 The full path to the pinentry binary. The default is specified at
 137 compile-time.
 138
 139 .TP
 140 .I "\--local-pinentry"
 141 Force use of the local pinentry for passphrase retrieval. This will
 142 disable pwmd's pinentry and use a pinentry fork'ed from libpwmd.
 143
 144 .TP
 145 .I "\--no-pinentry"
 146 Disable the use of pinentry entirely. Both pwmd and libpwmd's local
 147 pinentry will be disabled. Pwmc will prompt for the passphrase via
 148 stdin.
 149
 150 .TP
 151 .I "\--ttyname, -y <path>"
 152 The full path of the TTY for
 153 .BR pinentry (1)
 154 to prompt on. The default is the current terminal.
 155
 156 .TP
 157 .I "\--ttytype, -t <string>"
 158 The terminal type of the specified TTY that
 159 .BR pinentry (1)
 160 should use. This is required if
 161 .I "\-\-ttyname"
 162 is specified.
 163
 164 .TP
 165 .I "\--display, -d <string>"
 166 The X11 display that
 167 .BR pinentry (1)
 168 should use. Note that remote connections to pwmd do not use pwmd's
 169 pinentry but use a pinentry fork'ed from libpwmd instead. The default
 170 is obtained from the
 171 .B DISPLAY
 172 environment variable.
 173
 174 .TP
 175 .I "\--lc-ctype, <string>"
 176 For
 177 .BR pinentry (1)
 178 localization.
 179
 180 .TP
 181 .I "\--lc-messages, <string>"
 182 For
 183 .BR pinentry (1)
 184 localization.
 185
 186 .TP
 187 .I "\--tries, <n>"
 188 The number of times before failing when an invalid passphrase is entered in
 189 the
 190 .BR pinentry (1)
 191 dialog. The default is 3.
 192
 193 .TP
 194 .I "\-\-timeout, <seconds>"
 195 The number of seconds before
 196 .BR pinentry (1)
 197 will timeout while waiting for a passphrase. The default is 30.
 198
 199 .TP
 200 .I "\--inquire <command>"
 201 Some pwmd protocol commands use what is called an INQUIRE to retrieve
 202 data from the client. This options argument should be the command name
 203 that uses an inquire. The command data will be read from the file
 204 descriptor specified by the
 205 .I "\-\-inquire\-fd"
 206 option or stdin by default.
 207
 208 .TP
 209 .I "\--inquire-line, -L <string>"
 210 The initial line to send during an inquire and before any other data read from
 211 the inquire file descriptor. This option is useful to specify an
 212 element path without needing to modify the remaining inquire data. See
 213 .B EXAMPLES
 214 below.
 215
 216 .TP
 217 .I "\--inquire-fd <fd>"
 218 Read inquire data from the specified file descriptor. For use with the
 219 .I "\-\-inquire"
 220 option. By default, inquire data is read from stdin. Use
 221 .I "\-\-inquire-line"
 222 to send an initial line before the actual data.
 223
 224 .TP
 225 .I "\-\-inquire-file <filename>"
 226 Read inquire data from the specified filename.  For use with the
 227 .I "\-\-inquire"
 228 option. By default, inquire data is read from stdin. Use
 229 .I "\-\-inquire-line"
 230 to send an initial line before the actual data.
 231
 232 .TP
 233 .I "\--output-fd <fd>"
 234 Redirect the output of the pwmd command to the specified file
 235 descriptor. The default is stdout.
 236
 237 .TP
 238 .I "\--save, -S"
 239 After the command has been processed without error, send the SAVE
 240 command to the server to write any changes to disk.
 241
 242 .TP
 243 .I "\--force-save"
 244 Like
 245 .I "\-\-save"
 246 but expire any cached passphrase on the server before saving. This
 247 will require a passphrase, if needed, when saving.
 248
 249 .TP
 250 .I "\-\-no\-passphrase"
 251 When saving to a new file, do not prompt for a passphrase. This will
 252 allow the data file to be opened without a passphrase.
 253
 254 .TP
 255 .I "\-\-no-gpg-agent"
 256 When
 257 .BR pwmd (1)
 258 is compiled with
 259 .BR gpg-agent (1)
 260 support and gpg-agent usage is enabled, pwmd will default to using
 261 the gpg-agent key-pair encryption mechanism rather than symmetric
 262 encryption of the data file. Use this option to force symmetric
 263 encryption of the data file without using gpg-agent. Note that this
 264 option only has an affect when saving to a new file.
 265
 266 .TP
 267 .I "\--key-file <filename>"
 268 Read the passphrase used to open a file from the specified filename.
 269
 270 .TP
 271 .I "\--new-key-file <filename>"
 272 Read a passphrase from the specified filename that is to be used for a
 273 new data file or when changing the passphrase for an existing data
 274 file.
 275
 276 .TP
 277 .I "\--cipher <string>"
 278 When saving, encrypt with the specified cipher algorithm. See the
 279 pwmd documentation for available ciphers. The default is "aes256".
 280
 281 .TP
 282 .I "\--cipher-iterations <N>"
 283 The number of cipher encryption iterations of the XML data. This is
 284 actually N+1.
 285
 286 .TP
 287 .I "\-\-key\-params <string>"
 288 When saving, use the specified key parameters rather than the pwmd
 289 default. This should be a valid S-expression. See the libgcrypt
 290 documentation for details.
 291
 292 .TP
 293 .I "\-\-keygrip <hex-string>"
 294 Encrypt the XML data using the specified key grip. The key can be any
 295 that
 296 .BR gpg-agent (1)
 297 knows of.
 298
 299 .TP
 300 .I "\-\-sign-keygrip <hex-string>"
 301 Sign the encrypted XML data using the specified key grip. The key can
 302 be any that
 303 .BR gpg-agent (1)
 304 knows of.
 305
 306 .TP
 307 .I "\--s2k-count <n>"
 308 The number of passphrase hashing iterations for a new file.
 309
 310 .TP
 311 .I "\--no-status"
 312 Do not show server status messages. By default, status messages are
 313 written to stderr.
 314
 315 .TP
 316 .I "\--quiet"
 317 Do not show informational messages from pwmc. Implies --no-status.
 318
 319 .TP
 320 .I "\--interactive"
 321 Use an interactive pwmc shell. This will let you send more than one command
 322 per connection and is the default when input is from a terminal. See
 323 .B INTERACTIVE
 324 for more information.
 325
 326 .TP
 327 .I "\--version"
 328 Version information.
 329 .TP
 330 .I "\--help"
 331 This help text.
 332
 333
 334 .SH SSH
 335 Pwmc can connect to a remote pwmd server over an SSH connection by
 336 using a proxy program that can read from stdin and write to a UNIX
 337 domain socket and vice-versa.
 338
 339 Most SSH servers allow special options in the
 340 .B authorized_keys
 341 file that do various things. One such option is the
 342 .B "command"
 343 option that will launch a program when an SSH client connects. We can
 344 use this to start a proxy program that connects to the UNIX domain
 345 socket that pwmd listens on by putting the following in
 346 your
 347 .B ~/.ssh/authorized_keys
 348 file on the remote SSH host:
 349
 350     command="socat gopen:$HOME/.pwmd/socket -" [...public.key...]
 351
 352 Notice the
 353 .B "command="
 354 is prepended to the public key that was
 355 generated using
 356 .BR ssh-keygen (1)
 357 and specified using the
 358 .I "\-\-identity"
 359 command line option.
 360
 361 The
 362 .BR socat (1)
 363 command can be replaced with any utility that can read from stdin and write
 364 to a local domain socket.
 365
 366
 367 .SH PINENTRY
 368 .BR pinentry (1)
 369 is a program that prompts a user for input. This is currently not
 370 supported when connected to a remote pwmd server since X11 port
 371 forwarding has yet to be implemented. If a pinentry is required over a
 372 remote connection then a local pinentry fork'ed from libpwmd will be
 373 used unless the
 374 .I "\\-\-no\-pinentry"
 375 command line option was specified.
 376
 377 The terminal, terminal type or
 378 .B DISPLAY
 379 that pinentry will prompt on is either
 380 set with the command line options or uses options set in
 381 .B ~/.pwmd/pinentry.conf
 382 when available (see below). Otherwise the current terminal and
 383 terminal type or X11
 384 .B DISPLAY
 385 is used.
 386
 387 The
 388 .B ~/.pwmd/pinentry.conf
 389 file contains one
 390 .B NAME=VALUE
 391 pair per line. Comments begin with a '#'.
 392
 393 .I PATH
 394 The full path to the location of the pinentry binary.
 395
 396 .I DISPLAY
 397 The X11 display to use.
 398
 399 .I TTYNAME
 400 The full path to the tty that pinentry should prompt on.
 401
 402 .I TTYTYPE
 403 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
 404 set.
 405
 406 .I LC_MESSAGES
 407 For pinentry localization.
 408
 409 .I LC_CTYPE
 410 For pinentry localization.
 411
 412
 413 .SH INTERACTIVE
 414 Since interactive mode uses the
 415 .BR readline (3)
 416 library, the TAB character is normally interpreted as the line completion
 417 character. This conflicts with the
 418 .BR pwmd (1)
 419 element separation character. In order to insert a TAB you will first need to
 420 press CTRL-V then press TAB. See
 421 .BR readline (3)
 422 for more information about line history and completion.
 423
 424 Interactive mode also has a few dot commands. Dot commands (an idea
 425 borrowed from the
 426 .BR sqlite3 (1)
 427 command line program), begin with a
 428 .B .
 429 followed by the command name and any arguments. Here are the available
 430 pwmc interactive commands:
 431
 432 .TP
 433 .I .open <filename>
 434 Open the specified
 435 .B filename
 436 while losing any changes to the current filename. Although the
 437 .B OPEN
 438 protocol command can be used to open a file, this dot command is
 439 recommended because it takes care of pinentry settings among other
 440 things.
 441
 442 .TP
 443 .I .read [--prefix <string>] <filename> <command> [args ...]
 444 For use with a
 445 .B command
 446 that uses a server INQUIRE. The
 447 .I "\-\-prefix"
 448 option behaves like the
 449 .I "\-\-inquire-line"
 450 command line option. It is the initial line to send before any data
 451 read from
 452 .B filename.
 453
 454 .TP
 455 .I .redir <filename> <command>
 456 Redirect the output of
 457 .B command
 458 to
 459 .B filename.
 460
 461 .TP blah
 462 .I .set help | <name> [<value>] [...]
 463 Set option
 464 .B name
 465 is set to
 466 .B value.
 467 When no
 468 .B value
 469 is specified, the option
 470 .B name
 471 is unset.
 472 .RS
 473 .TP
 474 .I keyfile <datafile> [<filename>]
 475 Set the
 476 .B filename
 477 containing the passphrase to open
 478 .B datafile
 479 for the next command requiring a passphrase. This is equivalent to the
 480 .I "\-\-key-file"
 481 command line option. This value will be unset after the next protocol
 482 command to prevent misuse.
 483 .TP
 484 .I new-keyfile <datafile> [<filename>]
 485 Set the
 486 .B filename
 487 containing the passphrase to use to save
 488 .B datafile
 489 for the next command requiring a new passphrase. This is equivalent to the
 490 .I "\-\-new-key-file"
 491 command line option. This value will be unset after the next protocol
 492 command to prevent misuse.
 493 .TP
 494 .I pinentry-timeout <seconds>
 495 Set the amount of seconds before the pinentry program will close and return an
 496 error while waiting for user input.
 497 .RE
 498
 499 .TP
 500 .I .save [args]
 501 Save changes of the document to disk. Using this dot command rather than
 502 the pwmd
 503 .B SAVE
 504 protocol command is recommended since it determines whether to use
 505 pinentry or not.
 506
 507 .TP
 508 .I .help
 509 Show available interactive commands.
 510
 511 .SH EXAMPLES
 512 To list all XML root elements of the data file and use
 513 .BR pinentry (1)
 514 to retrieve the passphrase (if required):
 515 .RS
 516 .I echo list | pwmc filename
 517 .RE
 518 .P
 519 To store an element path and save the file afterwards:
 520 .RS
 521 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
 522 .P
 523 And then to get the content:
 524 .P
 525 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 526 .RE
 527 .P
 528 Store a larger file:
 529 .RS
 530 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
 531 .RE
 532 or
 533 .RS
 534 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
 535 .RE
 536 .P
 537 Clear the file cache for a single file:
 538 .RS
 539 .I echo 'clearcache filename' | pwmc
 540 .RE
 541 .P
 542 To list root elements of a data file which is stored on a remote pwmd server
 543 over an SSH connection:
 544 .RS
 545 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
 546 .RE
 547 .P
 548 Connect to a remote pwmd server over TLS, interactively:
 549 .RS
 550 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
 551 .RE
 552 .P
 553 Connect to a remote pwmd server over TLS and generate a new keypair
 554 for a data file that may not already exist using a keyfile as
 555 passphrase and inquire data from a file descriptor:
 556 .RS
 557 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem --inquire STORE --inquire-line 'some\\\\telement\\\\t' --inquire-fd 3 --key-file old_key --new-key-file new_key --cipher serpent128 --cipher-iterations 4000 --key-params '(genkey (rsa (nbits 4:1024)))' -S datafile 3<inquire_data
 558 .RE
 559
 560 .SH NOTES
 561 Be careful of newline characters when storing data. The data is transfered and
 562 stored exactly as the input is read, newlines and all. If you wonder why your
 563 new passphrase for a service doesn't work then a trailing newline character
 564 may be the reason.
 565
 566 .SH FILES
 567 .TP
 568 .B @pwmd_socket@
 569 Default pwmd socket to connect to.
 570 .TP
 571 .B ~/.pwmd/pinentry.conf
 572 Default settings that
 573 .BR pinentry (1)
 574 will use for the terminal, terminal type or X11 display.
 575 .TP
 576 .B @pinentry@
 577 Default location of the
 578 .BR pinentry (1)
 579 binary.
 580
 581 .SH AUTHOR
 582 Ben Kibbey <bjk@luxsci.net>
 583 .br
 584 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 585
 586 .SH "SEE ALSO"
 587 .BR pwmd (1),
 588 .BR pinentry (1),
 589 .BR ssh-keygen (1),
 590 .BR authorized_keys (5),
 591 .BR socat (1),
 592 .BR libpwmd (3)
 593
 594 And the pwmd texinfo manual for protocol commands and their syntax.