doc/pwmc.1.in

   1 .\" Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015
   2 .\"               2016
   3 .\" Ben Kibbey <bjk@luxsci.net>
   4 .\"
   5 .\" This file is part of libpwmd.
   6 .\"
   7 .\" Libwmd is free software: you can redistribute it and/or modify
   8 .\" it under the terms of the GNU General Public License as published by
   9 .\" the Free Software Foundation, either version 2 of the License, or
  10 .\" (at your option) any later version.
  11 .\"
  12 .\" Libwmd is distributed in the hope that it will be useful,
  13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 .\" GNU General Public License for more details.
  16 .\"
  17 .\" You should have received a copy of the GNU General Public License
  18 .\" along with Libpwmd.  If not, see <http://www.gnu.org/licenses/>.
  19 .de URL
  20 \\$2 \(laURL: \\$1 \(ra\\$3
  21 ..
  22 .if \n[.g] .mso www.tmac
  23 .TH PWMC 1 "18 Sep 2016" "@VERSION@" "Password Manager Client"
  24 .SH NAME
  25
  26 pwmc \- send a command to a pwmd server
  27 .SH SYNOPSIS
  28 .B pwmc
  29 [options] [file]
  30
  31 .SH DESCRIPTION
  32 .B pwmc
  33 is a
  34 .BR libpwmd (3)
  35 client for
  36 .BR pwmd (1).
  37 Pwmc reads pwmd protocol commands from either standard input or
  38 interactively by using libreadline to prompt for input. The
  39 interactive mode allows for more than one command to be sent to the
  40 pwmd server.
  41
  42 .SH OPTIONS
  43 .TP
  44 .I "\--url <string>"
  45 A pwmd URL to connect to. The available URL types depend on options
  46 enabled at compile-time. The default when not specified is
  47 .B @pwmd_socket@.
  48 See
  49 .B EXAMPLES
  50 for details.
  51
  52 .TP
  53 .I "\--connect-timeout <seconds>"
  54 The number of seconds before timing out when connecting to a remote
  55 server. The default is 120 seconds.
  56
  57 .TP
  58 .I "\--socket-timeout <seconds>"
  59 The number of seconds before a remote command will timeout. The
  60 default is 300 seconds.
  61
  62 .TP
  63 .I "\--ca-cert, <filename>"
  64 The X509 certificate authority file to use when validating the pwmd
  65 TLS server certificate. Required when connecting via TLS.
  66
  67 .TP
  68 .I "\--client-cert, <filename>"
  69 The X509 client certificate to use when authenticating a TLS
  70 connection. Required when connecting via TLS.
  71
  72 .TP
  73 .I "\--client-key, <filename>"
  74 The X509 key file to use to unlock the client certificate.  Required
  75 when connecting via TLS.
  76
  77 .TP
  78 .I "\--tls-priority, <string>"
  79 A string representing compression, cipher and hashing algorithm priorities for
  80 a TLS connection. See the GnuTLS documentation for details. The default is
  81 .B SECURE256:SECURE192:SECURE128:-VERS-SSL3.0.
  82
  83 .TP
  84 .I "\--no-tls-verify"
  85 Disable verification of the TLS server hostname stored in the server
  86 certificate. The default is enabled.
  87
  88 .TP
  89 .I "\--tls-fingerprint <string>"
  90 Verify the
  91 .BR pwmd
  92 TLS server certificate against the specified SHA-256 hash.
  93
  94 .TP
  95 .I "\--no-ssh-agent"
  96 Normally when the SSH_AUTH_SOCK environment variable is set pwmc will get
  97 authentication details from the ssh agent. When this option is specified or
  98 when the environment variable is not set a private key must be specified on
  99 the command line with the
 100 .I "\-\-identity"
 101 option. See
 102 .BR ssh-add (1)
 103 for how to add a private key to the ssh agent. Note that the
 104 .I "\-\-identity"
 105 command line option has priority over the ssh agent.
 106
 107 .TP
 108 .I "\-\-identity, -i <filename>"
 109 The SSH identity file use when connecting via SSH.
 110
 111 .TP
 112 .I "\-\-knownhosts, -k <filename"
 113 The SSH knownhosts file to use when connection via SSH. The default is
 114 ~/.ssh/knownhosts.
 115
 116 .TP
 117 .I "\-\-ssh-needs-passphrase"
 118 This option specifies that the SSH identity file requires a passphrase to
 119 connect. Note that libssh2 needs to be built with OpenSSL to support
 120 decryption of a private SSH key.
 121
 122 .TP
 123 .I "\-\-ssh-passphrase-file <filename>"
 124 Obtain the passphrase to decrypt the SSH private key from the specified
 125 filename.  Note that libssh2 needs to be built with OpenSSL to support
 126 decryption of a private SSH key.
 127
 128 .TP
 129 .I "\--no-lock"
 130 Do not lock the data file upon opening it. Locking the data file
 131 prevents other clients from opening the same file.
 132
 133 .TP
 134 .I "\--lock-timeout <N>"
 135 The time in tenths of a second to wait for another client to release the lock
 136 held on a data file before returning an error. When not specified or 0, pwmc
 137 will wait indefinitely. When -1, an error will be returned immediately. The
 138 default is 50.
 139
 140 .TP
 141 .I "\--name, -n <string>"
 142 Set the client name to the specified string. This string is what is shown in
 143 the
 144 .BR pwmd (1)
 145 log files. The default is "pwmc".
 146
 147 .TP
 148 .I "\--pinentry, <path>"
 149 The full path to the pinentry binary. The default is specified at
 150 compile-time.
 151
 152 .TP
 153 .I "\--local-pinentry"
 154 Force use of the local pinentry for passphrase retrieval. This will
 155 disable pwmd's pinentry and use a pinentry fork(2)'ed from libpwmd.
 156
 157 .TP
 158 .I "\--no-pinentry"
 159 Disable the use of pinentry entirely. Both pwmd and libpwmd's local
 160 pinentry will be disabled. Pwmc will prompt for the passphrase via
 161 stdin.
 162
 163 .TP
 164 .I "\--ttyname, -y <path>"
 165 The full path of the TTY for
 166 .BR pinentry (1)
 167 to prompt on. The default is the current terminal.
 168
 169 .TP
 170 .I "\--ttytype, -t <string>"
 171 The terminal type of the specified TTY that
 172 .BR pinentry (1)
 173 should use. This is required if
 174 .I "\-\-ttyname"
 175 is specified.
 176
 177 .TP
 178 .I "\--display, -d <string>"
 179 The X11 display that
 180 .BR pinentry (1)
 181 should use. Note that remote connections to pwmd do not use pwmd's
 182 pinentry but use a pinentry fork(2)'ed from libpwmd instead. The default
 183 is obtained from the
 184 .B DISPLAY
 185 environment variable.
 186
 187 .TP
 188 .I "\--lc-ctype, <string>"
 189 For
 190 .BR pinentry (1)
 191 localization.
 192
 193 .TP
 194 .I "\--lc-messages, <string>"
 195 For
 196 .BR pinentry (1)
 197 localization.
 198
 199 .TP
 200 .I "\--tries, <n>"
 201 The number of times before failing when an invalid passphrase is entered in
 202 the
 203 .BR pinentry (1)
 204 dialog. The default is 3.
 205
 206 .TP
 207 .I "\-\-timeout, <seconds>"
 208 The number of seconds before
 209 .BR pinentry (1)
 210 will timeout while waiting for a passphrase. The default is 30.
 211
 212 .TP
 213 .I "\--inquire <command>"
 214 Some pwmd protocol commands use what is called an INQUIRE to retrieve
 215 data from the client. This options argument should be the command name
 216 that uses an inquire. The command data will be read from the file
 217 descriptor specified by the
 218 .I "\-\-inquire\-fd"
 219 option or stdin by default.
 220
 221 .TP
 222 .I "\--inquire-line, -L <string>"
 223 The initial line to send during an inquire and before any other data read from
 224 the inquire file descriptor. This option is useful to specify an
 225 element path without needing to modify the remaining inquire data. See
 226 .B EXAMPLES
 227 below.
 228
 229 .TP
 230 .I "\--inquire-fd <fd>"
 231 Read inquire data from the specified file descriptor. For use with the
 232 .I "\-\-inquire"
 233 option. By default, inquire data is read from stdin. Use
 234 .I "\-\-inquire-line"
 235 to send an initial line before the actual data.
 236
 237 .TP
 238 .I "\-\-inquire-file <filename>"
 239 Read inquire data from the specified filename.  For use with the
 240 .I "\-\-inquire"
 241 option. By default, inquire data is read from stdin. Use
 242 .I "\-\-inquire-line"
 243 to send an initial line before the actual data.
 244
 245 .TP
 246 .I "\--output-fd <fd>"
 247 Redirect the output of the pwmd command to the specified file
 248 descriptor. The default is stdout.
 249
 250 .TP
 251 .I "\--save, -S"
 252 After the command has been processed without error, send the SAVE
 253 command to the server to write any changes to disk.
 254
 255 .TP
 256 .I "\--passphrase-file <filename>"
 257 Read the passphrase used to open a data file from the specified filename.
 258
 259 .TP
 260 .I "\--new-passphrase-file <filename>"
 261 Read a passphrase from the specified filename that is to be used for a
 262 new data file or when changing the passphrase for an existing data
 263 file.
 264
 265 .TP
 266 .I "\--sign-passphrase-file <filename>"
 267 Read a passphrase from the specified filename that is to be used for signing
 268 of a symmetrically encrypted data file.
 269
 270 .TP
 271 .I "\-\-key\-params <filename>"
 272 When saving, use the key parameters obtained from
 273 .B filename
 274 rather than the
 275 .B pwmd
 276 defaults. The parameters are in GnuPG XML format.
 277
 278 .TP
 279 .I "\-\-keyid <fingerprint>[,...]"
 280 Encrypt the XML data to the specified recipients. When not specified, the same
 281 recipients for an existing data file will be used. Otherwise, a new key pair
 282 will be generated.
 283
 284 .TP
 285 .I "\-\-sign-keyid <fingerprint>[,...]"
 286 Sign the encrypted XML data using the specified signing key(s).
 287
 288 .TP
 289 .I "\-\-symmetric
 290 Conventionally encrypt a new data file rather than creating a new key pair.
 291 Note that a signer can also be specified.
 292
 293 .TP
 294 .I "\--no-status"
 295 Do not show server status messages. By default, status messages are
 296 written to stderr.
 297
 298 .TP
 299 .I "\--status-fd <FD>
 300 Redirect status messages to the specified file descriptor. The default is
 301 stderr.
 302
 303 .TP
 304 .I "\--status-ignore <string[,...]>
 305 A list of status messages that are ignored or not displayed. This may be
 306 useful in interactive mode to prevent messing up or confusing the input line.
 307 The default is
 308 .B KEEPALIVE,STATE,GPGME,PASSPHRASE_INFO,PASSPHRASE_HINT.
 309
 310 .TP
 311 .I "\--status-state
 312 Enable receiving of client STATE status messages.
 313
 314 .TP
 315 .I "\--quiet"
 316 Do not show informational messages from pwmc. Implies --no-status.
 317
 318 .TP
 319 .I "\--no-interactive"
 320 Disable interactive mode. By default, interactive mode is enabled when input
 321 is from a terminal. Interactive mode allows for sending more than one command
 322 per connection. See
 323 .B INTERACTIVE
 324 for more information.
 325
 326 .TP
 327 .I "\--version"
 328 Version information.
 329 .TP
 330 .I "\--help"
 331 Show available command line options and syntax.
 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 UNIX 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 ~/.config/libpwmd.conf
 382 when available (see below). Otherwise the current terminal and
 383 terminal type or X11
 384 .B DISPLAY
 385 is used.
 386
 387
 388 .SH CONFIGURATION FILE
 389 The
 390 .B ~/.config/libpwmd.conf
 391 file contains one
 392 .B NAME=VALUE
 393 pair per line. Comments begin with a '#'. Options specified on the command
 394 line override the settings in this file.
 395
 396 .TP
 397 .I pinentry-path = /path
 398 Same as --pinentry.
 399
 400 .TP
 401 .I pinentry-display = string
 402 Same as --display.
 403
 404 .TP
 405 .I pinentry-ttyname = /path
 406 Same as --ttyname.
 407
 408 .TP
 409 .I pinentry-ttytype = string
 410 Same as --ttytype.
 411
 412 .TP
 413 .I pinentry-lc-messages = string
 414 Same as --lc-messages.
 415
 416 .TP
 417 .I pinentry-lc-ctype = string
 418 Same as --lc-ctype.
 419
 420 .TP
 421 .I pinentry-tries = N
 422 Same as --tries.
 423
 424 .TP
 425 .I pinentry-timeout = N
 426 Same as --timeout.
 427
 428 .TP
 429 .I no-pinentry = 0|1
 430 Same as --no-pinentry.
 431
 432 .TP
 433 .I local-pinentry = 0|1
 434 Same as --local-pinentry.
 435
 436 .TP
 437 .I no-ssh-agent = 0|1
 438 Same as --no-ssh-agent.
 439
 440 .TP
 441 .I no-tls-verify = 0|1
 442 Same as --no-tls-verify.
 443
 444 .TP
 445 .I tls-priority = <string>
 446 Same as --tls-priority.
 447
 448 .TP
 449 .I socket-timeout = N
 450 Same as --socket-timeout.
 451
 452 .TP
 453 .I no-lock = 0|1
 454 Same as --no-lock.
 455
 456 .TP
 457 .I include = filename
 458 Path to a filename containing additional
 459 .B libpwmd.conf
 460 configuration settings. May be useful for a file containing pinentry settings
 461 which is updated as needed.
 462
 463 .SH INTERACTIVE
 464 Interactive mode has a few dot commands. Dot commands (an idea borrowed from
 465 the
 466 .BR sqlite3 (1)
 467 command line program), begin with a
 468 .B .
 469 followed by the command name and any arguments. Here are the available
 470 pwmc interactive commands:
 471
 472 .TP
 473 .I .open <filename>
 474 Open the specified
 475 .B filename
 476 while losing any changes to the current filename. Although the
 477 .B OPEN
 478 protocol command can be used to open a file, this dot command is
 479 recommended because it takes care of pinentry settings among other
 480 things.
 481
 482 .TP
 483 .I .read [--prefix <string>] <filename> <command> [args ...]
 484 For use with a
 485 .B command
 486 that uses a server INQUIRE. The
 487 .I "\-\-prefix"
 488 option behaves like the
 489 .I "\-\-inquire-line"
 490 command line option. It is the initial line to send before any data
 491 read from
 492 .B filename.
 493
 494 .TP
 495 .I .redir <filename> <command>
 496 Redirect the output of
 497 .B command
 498 to
 499 .B filename.
 500
 501 .TP
 502 .I .set help | <name> [<value>] [...]
 503 Set option
 504 .B name
 505 is set to
 506 .B value.
 507 When no
 508 .B value
 509 is specified, the option
 510 .B name
 511 is unset.
 512 .RS
 513
 514 .TP
 515 .I passphrase-file [<filename>]
 516 Obtain the passphrase from
 517 .B filename
 518 for the next command requiring a passphrase. This is equivalent to the
 519 .I "\-\-passphrase-file"
 520 command line option. This value will be unset after the next protocol
 521 command to prevent misuse.
 522
 523 .TP
 524 .I new-passphrase-file [<filename>]
 525 Obtain the passphrase from
 526 .B filename
 527 for the next command requiring a new passphrase. This is equivalent to the
 528 .I "\-\-new-passphrase-file"
 529 command line option. This value will be unset after the next protocol
 530 command to prevent misuse.
 531
 532 .TP
 533 .I sign-passphrase-file [<filename>]
 534 Obtain the passphrase from
 535 .B filename
 536 for the next command requiring a passphrase used for signing. This is
 537 equivalent to the
 538 .I "\-\-sign-passphrase-file"
 539 command line option and is optionally used for signing a symmetrically
 540 encrypted data file. This value will be unset after the next protocol command
 541 to prevent misuse.
 542
 543 .TP
 544 .I pinentry-timeout <seconds>
 545 Set the amount of seconds before the pinentry program will close and return an
 546 error while waiting for user input.
 547 .RE
 548
 549 .TP
 550 .I .save [args]
 551 Save changes of the document to disk. Using this dot command rather than
 552 the pwmd
 553 .B SAVE
 554 protocol command is recommended since it determines whether to use
 555 pinentry or not.
 556
 557 .TP
 558 .I .passwd
 559 Change the passphrase for the secret key of the opened data file. Using this
 560 dot command rather than the pwmd
 561 .B PASSWD
 562 protocol command is recommended since it determines whether to use
 563 pinentry or not. For symmetrically encrypted data files, use the
 564 .B .save
 565 command instead.
 566
 567 .TP
 568 .I .listkeys [--options] [pattern[,...]]
 569 Display human readable output of the LISTKEYS protocol command.
 570
 571 .TP
 572 .I .help
 573 Show available interactive commands.
 574
 575 .SH EXAMPLES
 576 To list all XML root elements of the data file and use
 577 .BR pinentry (1)
 578 to retrieve the passphrase (if required):
 579 .RS
 580 .I echo list | pwmc filename
 581 .RE
 582 .P
 583 To store an element path and save the file afterwards:
 584 .RS
 585 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
 586 .P
 587 And then to get the content:
 588 .P
 589 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 590 .RE
 591 .P
 592 Store a larger file:
 593 .RS
 594 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
 595 .RE
 596 or
 597 .RS
 598 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
 599 .RE
 600 .P
 601 Clear the file cache for a single file:
 602 .RS
 603 .I echo 'clearcache filename' | pwmc
 604 .RE
 605 .P
 606 To list root elements of a data file which is stored on a remote pwmd server
 607 over an SSH connection:
 608 .RS
 609 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
 610 .RE
 611 .P
 612 Connect to a remote pwmd server over TLS, interactively:
 613 .RS
 614 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
 615 .RE
 616
 617 .SH NOTES
 618 Be careful of newline characters when storing data. The data is transferred
 619 and stored exactly as the input is read, newlines and all. If you wonder why
 620 your new passphrase for a service doesn't work then a trailing newline
 621 character may be the reason.
 622
 623 .SH FILES
 624 .TP
 625 .B @pwmd_socket@
 626 Default pwmd socket to connect to.
 627 .TP
 628 .B ~/.config/libpwmd.conf
 629 Default settings that
 630 .BR pinentry (1)
 631 will use for the terminal, terminal type or X11 display.
 632 .TP
 633 .B @pinentry@
 634 Default location of the
 635 .BR pinentry (1)
 636 binary.
 637
 638 .SH AUTHOR
 639 Ben Kibbey <bjk@luxsci.net>
 640 .br
 641 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 642
 643 .SH "SEE ALSO"
 644 .BR pwmd (1),
 645 .BR pinentry (1),
 646 .BR ssh-keygen (1),
 647 .BR authorized_keys (5),
 648 .BR socat (1),
 649 .BR libpwmd (3)
 650
 651 And the pwmd texinfo manual for protocol commands and their syntax.