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 "11 Oct 2015" "@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 .B SECURE256:SECURE192:SECURE128:-VERS-SSL3.0.
  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 "\--key-file <filename>"
 256 Read the passphrase used to open a file from the specified filename.
 257
 258 .TP
 259 .I "\--new-key-file <filename>"
 260 Read a passphrase from the specified filename that is to be used for a
 261 new data file or when changing the passphrase for an existing data
 262 file.
 263
 264 .TP
 265 .I "\--sign-key-file <filename>"
 266 Read a passphrase from the specified filename that is to be used for signing
 267 of a symmetrically encrypted data file.
 268
 269 .TP
 270 .I "\--cipher <string>"
 271 When saving, encrypt with the specified cipher algorithm. See the
 272 pwmd documentation for available ciphers. The default is "aes256".
 273
 274 .TP
 275 .I "\--cipher-iterations <N>"
 276 The number of cipher encryption iterations of the XML data. This is
 277 actually N+1.
 278
 279 .TP
 280 .I "\-\-key\-params <filename>"
 281 When saving, use the key parameters obtained from
 282 .B filename
 283 rather than the
 284 .B pwmd
 285 defaults. The parameters are in GnuPG XML format.
 286
 287 .TP
 288 .I "\-\-keyid <fingerprint>[,...]"
 289 Encrypt the XML data to the specified recipients. When not specified, the same
 290 recipients for an existing data file will be used. Otherwise, a new key pair
 291 will be generated.
 292
 293 .TP
 294 .I "\-\-sign-keyid <fingerprint>"
 295 Sign the encrypted XML data using the specified key.
 296
 297 .TP
 298 .I "\--no-status"
 299 Do not show server status messages. By default, status messages are
 300 written to stderr.
 301
 302 .TP
 303 .I "\--status-fd <FD>
 304 Redirect status messages to the specified file descriptor. The default is
 305 stderr.
 306
 307 .TP
 308 .I "\--status-ignore <string[,...]>
 309 A list of status messages that are ignored or not displayed. This may be
 310 useful in interactive mode to prevent messing up or confusing the input line.
 311 The default is
 312 .B KEEPALIVE,STATE,GPGME,PASSPHRASE_INFO,PASSPHRASE_HINT.
 313
 314 .TP
 315 .I "\--quiet"
 316 Do not show informational messages from pwmc. Implies --no-status.
 317
 318 .TP
 319 .I "\--interactive"
 320 Use an interactive pwmc shell. This will let you send more than one command
 321 per connection and is the default when input is from a terminal. See
 322 .B INTERACTIVE
 323 for more information.
 324
 325 .TP
 326 .I "\--version"
 327 Version information.
 328 .TP
 329 .I "\--help"
 330 This help text.
 331
 332
 333 .SH SSH
 334 Pwmc can connect to a remote pwmd server over an SSH connection by
 335 using a proxy program that can read from stdin and write to a UNIX
 336 domain socket and vice-versa.
 337
 338 Most SSH servers allow special options in the
 339 .B authorized_keys
 340 file that do various things. One such option is the
 341 .B "command"
 342 option that will launch a program when an SSH client connects. We can
 343 use this to start a proxy program that connects to the UNIX domain
 344 socket that pwmd listens on by putting the following in
 345 your
 346 .B ~/.ssh/authorized_keys
 347 file on the remote SSH host:
 348
 349     command="socat gopen:$HOME/.pwmd/socket -" [...public.key...]
 350
 351 Notice the
 352 .B "command="
 353 is prepended to the public key that was
 354 generated using
 355 .BR ssh-keygen (1)
 356 and specified using the
 357 .I "\-\-identity"
 358 command line option.
 359
 360 The
 361 .BR socat (1)
 362 command can be replaced with any utility that can read from stdin and write
 363 to a UNIX domain socket.
 364
 365
 366 .SH PINENTRY
 367 .BR pinentry (1)
 368 is a program that prompts a user for input. This is currently not
 369 supported when connected to a remote pwmd server since X11 port
 370 forwarding has yet to be implemented. If a pinentry is required over a
 371 remote connection then a local pinentry fork'ed from libpwmd will be
 372 used unless the
 373 .I "\\-\-no\-pinentry"
 374 command line option was specified.
 375
 376 The terminal, terminal type or
 377 .B DISPLAY
 378 that pinentry will prompt on is either
 379 set with the command line options or uses options set in
 380 .B ~/.pwmd/pinentry.conf
 381 when available (see below). Otherwise the current terminal and
 382 terminal type or X11
 383 .B DISPLAY
 384 is used.
 385
 386 The
 387 .B ~/.pwmd/pinentry.conf
 388 file contains one
 389 .B NAME=VALUE
 390 pair per line. Comments begin with a '#'.
 391
 392 .I PATH
 393 The full path to the location of the pinentry binary.
 394
 395 .I DISPLAY
 396 The X11 display to use.
 397
 398 .I TTYNAME
 399 The full path to the tty that pinentry should prompt on.
 400
 401 .I TTYTYPE
 402 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
 403 set.
 404
 405 .I LC_MESSAGES
 406 For pinentry localization.
 407
 408 .I LC_CTYPE
 409 For pinentry localization.
 410
 411
 412 .SH INTERACTIVE
 413 Since interactive mode uses the
 414 .BR readline (3)
 415 library, the TAB character is normally interpreted as the line completion
 416 character. This conflicts with the
 417 .BR pwmd (1)
 418 element separation character. In order to insert a TAB you will first need to
 419 press CTRL-V then press TAB. See
 420 .BR readline (3)
 421 for more information about line history and completion.
 422
 423 Interactive mode also has a few dot commands. Dot commands (an idea
 424 borrowed from the
 425 .BR sqlite3 (1)
 426 command line program), begin with a
 427 .B .
 428 followed by the command name and any arguments. Here are the available
 429 pwmc interactive commands:
 430
 431 .TP
 432 .I .open <filename>
 433 Open the specified
 434 .B filename
 435 while losing any changes to the current filename. Although the
 436 .B OPEN
 437 protocol command can be used to open a file, this dot command is
 438 recommended because it takes care of pinentry settings among other
 439 things.
 440
 441 .TP
 442 .I .read [--prefix <string>] <filename> <command> [args ...]
 443 For use with a
 444 .B command
 445 that uses a server INQUIRE. The
 446 .I "\-\-prefix"
 447 option behaves like the
 448 .I "\-\-inquire-line"
 449 command line option. It is the initial line to send before any data
 450 read from
 451 .B filename.
 452
 453 .TP
 454 .I .redir <filename> <command>
 455 Redirect the output of
 456 .B command
 457 to
 458 .B filename.
 459
 460 .TP blah
 461 .I .set help | <name> [<value>] [...]
 462 Set option
 463 .B name
 464 is set to
 465 .B value.
 466 When no
 467 .B value
 468 is specified, the option
 469 .B name
 470 is unset.
 471 .RS
 472 .TP
 473 .I keyfile [<filename>]
 474 Obtain the passphrase from
 475 .B filename
 476 for the next command requiring a passphrase. This is equivalent to the
 477 .I "\-\-key-file"
 478 command line option. This value will be unset after the next protocol
 479 command to prevent misuse.
 480 .TP
 481 .I new-keyfile [<filename>]
 482 Obtain the passphrase from
 483 .B filename
 484 for the next command requiring a new passphrase. This is equivalent to the
 485 .I "\-\-new-key-file"
 486 command line option. This value will be unset after the next protocol
 487 command to prevent misuse.
 488 .TP
 489 .I sign-keyfile [<filename>]
 490 Obtain the passphrase from
 491 .B filename
 492 for the next command requiring a passphrase used for signing. This is
 493 equivalent to the
 494 .I "\-\-sign-key-file"
 495 command line option and is optionally used for signing a symmetrically
 496 encrypted data file. This value will be unset after the next protocol command
 497 to prevent misuse.
 498 .TP
 499 .I pinentry-timeout <seconds>
 500 Set the amount of seconds before the pinentry program will close and return an
 501 error while waiting for user input.
 502 .RE
 503
 504 .TP
 505 .I .save [args]
 506 Save changes of the document to disk. Using this dot command rather than
 507 the pwmd
 508 .B SAVE
 509 protocol command is recommended since it determines whether to use
 510 pinentry or not.
 511
 512 .TP
 513 .I .help
 514 Show available interactive commands.
 515
 516 .SH EXAMPLES
 517 To list all XML root elements of the data file and use
 518 .BR pinentry (1)
 519 to retrieve the passphrase (if required):
 520 .RS
 521 .I echo list | pwmc filename
 522 .RE
 523 .P
 524 To store an element path and save the file afterwards:
 525 .RS
 526 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
 527 .P
 528 And then to get the content:
 529 .P
 530 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 531 .RE
 532 .P
 533 Store a larger file:
 534 .RS
 535 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
 536 .RE
 537 or
 538 .RS
 539 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
 540 .RE
 541 .P
 542 Clear the file cache for a single file:
 543 .RS
 544 .I echo 'clearcache filename' | pwmc
 545 .RE
 546 .P
 547 To list root elements of a data file which is stored on a remote pwmd server
 548 over an SSH connection:
 549 .RS
 550 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
 551 .RE
 552 .P
 553 Connect to a remote pwmd server over TLS, interactively:
 554 .RS
 555 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
 556 .RE
 557
 558 .SH NOTES
 559 Be careful of newline characters when storing data. The data is transfered and
 560 stored exactly as the input is read, newlines and all. If you wonder why your
 561 new passphrase for a service doesn't work then a trailing newline character
 562 may be the reason.
 563
 564 .SH FILES
 565 .TP
 566 .B @pwmd_socket@
 567 Default pwmd socket to connect to.
 568 .TP
 569 .B ~/.pwmd/pinentry.conf
 570 Default settings that
 571 .BR pinentry (1)
 572 will use for the terminal, terminal type or X11 display.
 573 .TP
 574 .B @pinentry@
 575 Default location of the
 576 .BR pinentry (1)
 577 binary.
 578
 579 .SH AUTHOR
 580 Ben Kibbey <bjk@luxsci.net>
 581 .br
 582 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 583
 584 .SH "SEE ALSO"
 585 .BR pwmd (1),
 586 .BR pinentry (1),
 587 .BR ssh-keygen (1),
 588 .BR authorized_keys (5),
 589 .BR socat (1),
 590 .BR libpwmd (3)
 591
 592 And the pwmd texinfo manual for protocol commands and their syntax.