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 "\-\-socket <string>"
  45 A pwmd socket 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\-passphrase\-file <filename>"
 118 Obtain the passphrase to decrypt the SSH private key from the specified
 119 filename.  Note that libssh2 needs to be built with OpenSSL to support
 120 decryption of a private SSH key.
 121
 122 .TP
 123 .I "\-\-no\-lock"
 124 Do not lock the data file upon opening it. Locking the data file
 125 prevents other clients from opening the same file.
 126
 127 .TP
 128 .I "\-\-lock\-timeout <N>"
 129 The time in tenths of a second to wait for another client to release the lock
 130 held on a data file before returning an error. When not specified or 0, pwmc
 131 will wait indefinitely. When \-1, an error will be returned immediately. The
 132 default is 50.
 133
 134 .TP
 135 .I "\-\-name, \-n <string>"
 136 Set the client name to the specified string. This string is what is shown in
 137 the
 138 .BR pwmd (1)
 139 log files. The default is "pwmc".
 140
 141 .TP
 142 .I "\-\-local\-pinentry"
 143 Force use of the local pinentry for passphrase retrieval. This will
 144 disable pwmd's pinentry and use a pinentry fork(2)'ed from libpwmd.
 145
 146 .TP
 147 .I "\-\-no\-pinentry"
 148 Disable the use of pinentry entirely. Both pwmd and libpwmd's local
 149 pinentry will be disabled. Pwmc will prompt for the passphrase via
 150 stdin.
 151
 152 .TP
 153 .I "\-\-ttyname, \-y <path>"
 154 The full path of the TTY for
 155 .BR pinentry (1)
 156 to prompt on. The default is the current terminal.
 157
 158 .TP
 159 .I "\-\-ttytype, \-t <string>"
 160 The terminal type of the specified TTY that
 161 .BR pinentry (1)
 162 should use. This is required if
 163 .I "\-\-ttyname"
 164 is specified.
 165
 166 .TP
 167 .I "\-\-display, \-d <string>"
 168 The X11 display that
 169 .BR pinentry (1)
 170 should use. Note that remote connections to pwmd do not use pwmd's
 171 pinentry but use a pinentry fork(2)'ed from libpwmd instead. The default
 172 is obtained from the
 173 .B DISPLAY
 174 environment variable.
 175
 176 .TP
 177 .I "\-\-lc\-ctype, <string>"
 178 For
 179 .BR pinentry (1)
 180 localization.
 181
 182 .TP
 183 .I "\-\-lc\-messages, <string>"
 184 For
 185 .BR pinentry (1)
 186 localization.
 187
 188 .TP
 189 .I "\-\-tries, <n>"
 190 The number of times before failing when an invalid passphrase is entered in
 191 the
 192 .BR pinentry (1)
 193 dialog. The default is 3.
 194
 195 .TP
 196 .I "\-\-timeout, <seconds>"
 197 The number of seconds before
 198 .BR pinentry (1)
 199 will timeout while waiting for a passphrase. The default is 30.
 200
 201 .TP
 202 .I "\-\-inquire <command>"
 203 Some pwmd protocol commands use what is called an INQUIRE to retrieve
 204 data from the client. This options argument should be the command name
 205 that uses an inquire. The command data will be read from the file
 206 descriptor specified by the
 207 .I "\-\-inquire\-fd"
 208 option or stdin by default.
 209
 210 .TP
 211 .I "\-\-inquire\-line, \-L <string>"
 212 The initial line to send during an inquire and before any other data read from
 213 the inquire file descriptor. This option is useful to specify an
 214 element path without needing to modify the remaining inquire data. See
 215 .B EXAMPLES
 216 below.
 217
 218 .TP
 219 .I "\-\-inquire\-fd <fd>"
 220 Read inquire data from the specified file descriptor. For use with the
 221 .I "\-\-inquire"
 222 option. By default, inquire data is read from stdin. Use
 223 .I "\-\-inquire\-line"
 224 to send an initial line before the actual data.
 225
 226 .TP
 227 .I "\-\-inquire\-file <filename>"
 228 Read inquire data from the specified filename.  For use with the
 229 .I "\-\-inquire"
 230 option. By default, inquire data is read from stdin. Use
 231 .I "\-\-inquire\-line"
 232 to send an initial line before the actual data.
 233
 234 .TP
 235 .I "\-\-output\-fd <fd>"
 236 Redirect the output of the pwmd command to the specified file
 237 descriptor. The default is stdout.
 238
 239 .TP
 240 .I "\-\-save, \-S"
 241 After the command has been processed without error, send the SAVE
 242 command to the server to write any changes to disk.
 243
 244 .TP
 245 .I "\-\-passphrase\-file <filename>"
 246 Read the passphrase used to open a data file from the specified filename.
 247
 248 .TP
 249 .I "\-\-new\-passphrase\-file <filename>"
 250 Read a passphrase from the specified filename that is to be used for a
 251 new data file or when changing the passphrase for an existing data
 252 file.
 253
 254 .TP
 255 .I "\-\-sign\-passphrase\-file <filename>"
 256 Read a passphrase from the specified filename that is to be used for signing
 257 of a symmetrically encrypted data file.
 258
 259 .TP
 260 .I "\-\-key\-params <filename>"
 261 When saving, use the key parameters obtained from
 262 .B filename
 263 rather than the
 264 .B pwmd
 265 defaults. The parameters are in GnuPG XML format.
 266
 267 .TP
 268 .I "\-\-keyid <fingerprint>[,...]"
 269 Encrypt the XML data to the specified recipients. When not specified, the same
 270 recipients for an existing data file will be used. Otherwise, a new key pair
 271 will be generated.
 272
 273 .TP
 274 .I "\-\-sign\-keyid <fingerprint>[,...]"
 275 Sign the encrypted XML data using the specified signing key(s).
 276
 277 .TP
 278 .I "\-\-symmetric
 279 Conventionally encrypt a new data file rather than creating a new key pair.
 280 Note that a signer can also be specified.
 281
 282 .TP
 283 .I "\-\-no\-status"
 284 Do not show server status messages. By default, status messages are
 285 written to stderr.
 286
 287 .TP
 288 .I "\-\-status\-fd <FD>
 289 Redirect status messages to the specified file descriptor. The default is
 290 stderr.
 291
 292 .TP
 293 .I "\-\-status\-ignore <string[,...]>
 294 A list of status messages that are ignored or not displayed. This may be
 295 useful in interactive mode to prevent messing up or confusing the input line.
 296 The default is
 297 .B KEEPALIVE,STATE,GPGME,PASSPHRASE_INFO,PASSPHRASE_HINT.
 298
 299 .TP
 300 .I "\-\-status\-state
 301 Enable receiving of client STATE status messages.
 302
 303 .TP
 304 .I "\-\-quiet"
 305 Do not show informational messages from pwmc. Implies \--no\-status.
 306
 307 .TP
 308 .I "\-\-no\-interactive"
 309 Disable interactive mode. By default, interactive mode is enabled when input
 310 is from a terminal. Interactive mode allows for sending more than one command
 311 per connection. See
 312 .B INTERACTIVE
 313 for more information.
 314
 315 .TP
 316 .I "\-\-version"
 317 Version information.
 318 .TP
 319 .I "\-\-help"
 320 Show available command line options and syntax.
 321
 322
 323 .SH SSH
 324 Pwmc can connect to a remote pwmd server over an SSH connection by
 325 using a proxy program that can read from stdin and write to a UNIX
 326 domain socket and vice-versa.
 327
 328 Most SSH servers allow special options in the
 329 .B authorized_keys
 330 file that do various things. One such option is the
 331 .B "command"
 332 option that will launch a program when an SSH client connects. We can
 333 use this to start a proxy program that connects to the UNIX domain
 334 socket that pwmd listens on by putting the following in
 335 your
 336 .B ~/.ssh/authorized_keys
 337 file on the remote SSH host:
 338
 339     command="socat gopen:$HOME/.pwmd/socket \-" [...public.key...]
 340
 341 Notice the
 342 .B "command="
 343 is prepended to the public key that was
 344 generated using
 345 .BR ssh\-keygen (1)
 346 and specified using the
 347 .I "\-\-identity"
 348 command line option.
 349
 350 The
 351 .BR socat (1)
 352 command can be replaced with any utility that can read from stdin and write
 353 to a UNIX domain socket.
 354
 355
 356 .SH PINENTRY
 357 .BR pinentry (1)
 358 is a program that prompts a user for input. This is currently not
 359 supported when connected to a remote pwmd server since X11 port
 360 forwarding has yet to be implemented. If a pinentry is required over a
 361 remote connection then a local pinentry fork'ed from libpwmd will be
 362 used unless the
 363 .I "\-\-no\-pinentry"
 364 command line option was specified.
 365
 366 The terminal, terminal type or
 367 .B DISPLAY
 368 that pinentry will prompt on is either
 369 set with the command line options or uses options set in
 370 .B ~/.config/libpwmd.conf
 371 when available (see below). Otherwise the current terminal and
 372 terminal type or X11
 373 .B DISPLAY
 374 is used.
 375
 376
 377 .SH CONFIGURATION FILE
 378 The
 379 .B ~/.config/libpwmd.conf
 380 file contains one
 381 .B NAME=VALUE
 382 pair per line. Comments begin with a '#'. Options specified on the command
 383 line override the settings in this file.
 384
 385 .TP
 386 .I pinentry\-path = /path
 387 Same as \-\-pinentry.
 388
 389 .TP
 390 .I pinentry\-display = string
 391 Same as \-\-display.
 392
 393 .TP
 394 .I pinentry\-ttyname = /path
 395 Same as \-\-ttyname.
 396
 397 .TP
 398 .I pinentry\-ttytype = string
 399 Same as \-\-ttytype.
 400
 401 .TP
 402 .I pinentry\-lc\-messages = string
 403 Same as \-\-lc\-messages.
 404
 405 .TP
 406 .I pinentry\-lc\-ctype = string
 407 Same as \-\-lc\-ctype.
 408
 409 .TP
 410 .I pinentry\-tries = N
 411 Same as \-\-tries.
 412
 413 .TP
 414 .I pinentry\-timeout = N
 415 Same as \-\-timeout.
 416
 417 .TP
 418 .I no\-pinentry = 0|1
 419 Same as \-\-no\-pinentry.
 420
 421 .TP
 422 .I local\-pinentry = 0|1
 423 Same as \-\-local\-pinentry.
 424
 425 .TP
 426 .I no\-ssh\-agent = 0|1
 427 Same as \-\-no\-ssh\-agent.
 428
 429 .TP
 430 .I no\-tls\-verify = 0|1
 431 Same as \-\-no\-tls\-verify.
 432
 433 .TP
 434 .I tls\-priority = <string>
 435 Same as \-\-tls\-priority.
 436
 437 .TP
 438 .I socket\-timeout = N
 439 Same as \-\-socket\-timeout.
 440
 441 .TP
 442 .I no\-lock = 0|1
 443 Same as \-\-no\-lock.
 444
 445 .TP
 446 .I include = filename
 447 Path to a filename containing additional
 448 .B libpwmd.conf
 449 configuration settings. May be useful for a file containing pinentry settings
 450 which is updated as needed.
 451
 452 .SH INTERACTIVE
 453 Interactive mode has a few dot commands. Dot commands (an idea borrowed from
 454 the
 455 .BR sqlite3 (1)
 456 command line program), begin with a
 457 .B .
 458 followed by the command name and any arguments. Here are the available
 459 pwmc interactive commands:
 460
 461 .TP
 462 .I .open <filename>
 463 Open the specified
 464 .B filename
 465 while losing any changes to the current filename. Although the
 466 .B OPEN
 467 protocol command can be used to open a file, this dot command is
 468 recommended because it takes care of pinentry settings among other
 469 things.
 470
 471 .TP
 472 .I .read [\-\-prefix <string>] <filename> <command> [args ...]
 473 For use with a
 474 .B command
 475 that uses a server INQUIRE. The
 476 .I "\-\-prefix"
 477 option behaves like the
 478 .I "\-\-inquire\-line"
 479 command line option. It is the initial line to send before any data
 480 read from
 481 .B filename.
 482
 483 .TP
 484 .I .redir <filename> <command>
 485 Redirect the output of
 486 .B command
 487 to
 488 .B filename.
 489
 490 .TP
 491 .I .set help | <name> [<value>] [...]
 492 Set option
 493 .B name
 494 is set to
 495 .B value.
 496 When no
 497 .B value
 498 is specified, the option
 499 .B name
 500 is unset.
 501 .RS
 502
 503 .TP
 504 .I passphrase\-file [<filename>]
 505 Obtain the passphrase from
 506 .B filename
 507 for the next command requiring a passphrase. This is equivalent to the
 508 .I "\-\-passphrase\-file"
 509 command line option. This value will be unset after the next protocol
 510 command to prevent misuse.
 511
 512 .TP
 513 .I new\-passphrase\-file [<filename>]
 514 Obtain the passphrase from
 515 .B filename
 516 for the next command requiring a new passphrase. This is equivalent to the
 517 .I "\-\-new\-passphrase\-file"
 518 command line option. This value will be unset after the next protocol
 519 command to prevent misuse.
 520
 521 .TP
 522 .I sign\-passphrase\-file [<filename>]
 523 Obtain the passphrase from
 524 .B filename
 525 for the next command requiring a passphrase used for signing. This is
 526 equivalent to the
 527 .I "\-\-sign\-passphrase\-file"
 528 command line option and is optionally used for signing a symmetrically
 529 encrypted data file. This value will be unset after the next protocol command
 530 to prevent misuse.
 531
 532 .TP
 533 .I pinentry\-timeout <seconds>
 534 Set the amount of seconds before the pinentry program will close and return an
 535 error while waiting for user input.
 536 .RE
 537
 538 .TP
 539 .I .save [args]
 540 Save changes of the document to disk. Using this dot command rather than
 541 the pwmd
 542 .B SAVE
 543 protocol command is recommended since it determines whether to use
 544 pinentry or not.
 545
 546 .TP
 547 .I .passwd
 548 Change the passphrase for the secret key of the opened data file. Using this
 549 dot command rather than the pwmd
 550 .B PASSWD
 551 protocol command is recommended since it determines whether to use
 552 pinentry or not. For symmetrically encrypted data files, use the
 553 .B .save
 554 command instead.
 555
 556 .TP
 557 .I .listkeys [\-\-options] [pattern[,...]]
 558 Display human readable output of the LISTKEYS protocol command.
 559
 560 .TP
 561 .I .help
 562 Show available interactive commands.
 563
 564 .SH EXAMPLES
 565 To list all XML root elements of the data file and use
 566 .BR pinentry (1)
 567 to retrieve the passphrase (if required):
 568 .RS
 569 .I echo list | pwmc filename
 570 .RE
 571 .P
 572 To store an element path and save the file afterwards:
 573 .RS
 574 .I echo \-ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc \-\-inquire STORE \-S filename
 575 .P
 576 And then to get the content:
 577 .P
 578 .I echo \-ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 579 .RE
 580 .P
 581 Store a larger file:
 582 .RS
 583 .I echo \-ne 'some\\\\telement\\\\tpath\\\\t' | cat \- data_file | pwmc \-\-inquire STORE \-S filename
 584 .RE
 585 or
 586 .RS
 587 .I pwmc \-\-inquire STORE \-\-inquire\-line 'some\\\\telement\\\\tpath\\\\t' \-S filename < data_file
 588 .RE
 589 .P
 590 Clear the file cache for a single file:
 591 .RS
 592 .I echo 'clearcache filename' | pwmc
 593 .RE
 594 .P
 595 To list root elements of a data file which is stored on a remote pwmd server
 596 over an SSH connection:
 597 .RS
 598 .I echo list | pwmc \-\-socket ssh://user@hostname \-i ~/.ssh/identity filename
 599 .RE
 600 .P
 601 Connect to a remote pwmd server over TLS, interactively:
 602 .RS
 603 .I pwmc \-\-socket tls://hostname \-\-ca\-cert cafile.pem \-\-client\-cert client.pem \-\-client\-key clientkey.pem filename
 604 .RE
 605
 606 .SH NOTES
 607 Be careful of newline characters when storing data. The data is transferred
 608 and stored exactly as the input is read, newlines and all. If you wonder why
 609 your new passphrase for a service doesn't work then a trailing newline
 610 character may be the reason.
 611
 612 .SH FILES
 613 .TP
 614 .B @pwmd_socket@
 615 Default pwmd socket to connect to.
 616 .TP
 617 .B ~/.config/libpwmd.conf
 618 Default settings that
 619 .BR pinentry (1)
 620 will use for the terminal, terminal type or X11 display.
 621 .TP
 622 .B @pinentry@
 623 Default location of the
 624 .BR pinentry (1)
 625 binary.
 626
 627 .SH AUTHOR
 628 Ben Kibbey <bjk@luxsci.net>
 629 .br
 630 .URL "https://gitlab.com/bjk/libpwmd/wikis" "libpwmd Homepage" .
 631
 632 .SH "SEE ALSO"
 633 .BR pwmd (1),
 634 .BR pinentry (1),
 635 .BR ssh\-keygen (1),
 636 .BR authorized_keys (5),
 637 .BR socat (1),
 638 .BR libpwmd (3)
 639
 640 And the pwmd texinfo manual for protocol commands and their syntax.