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 "27 Aug 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 "\--tls-verify"
  85 Verify the TLS server hostname stored in the server certificate to the
  86 connected hostname. The default is disabled.
  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 ~/.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 Interactive mode has a few dot commands. Dot commands (an idea borrowed from
 415 the
 416 .BR sqlite3 (1)
 417 command line program), begin with a
 418 .B .
 419 followed by the command name and any arguments. Here are the available
 420 pwmc interactive commands:
 421
 422 .TP
 423 .I .open <filename>
 424 Open the specified
 425 .B filename
 426 while losing any changes to the current filename. Although the
 427 .B OPEN
 428 protocol command can be used to open a file, this dot command is
 429 recommended because it takes care of pinentry settings among other
 430 things.
 431
 432 .TP
 433 .I .read [--prefix <string>] <filename> <command> [args ...]
 434 For use with a
 435 .B command
 436 that uses a server INQUIRE. The
 437 .I "\-\-prefix"
 438 option behaves like the
 439 .I "\-\-inquire-line"
 440 command line option. It is the initial line to send before any data
 441 read from
 442 .B filename.
 443
 444 .TP
 445 .I .redir <filename> <command>
 446 Redirect the output of
 447 .B command
 448 to
 449 .B filename.
 450
 451 .TP
 452 .I .set help | <name> [<value>] [...]
 453 Set option
 454 .B name
 455 is set to
 456 .B value.
 457 When no
 458 .B value
 459 is specified, the option
 460 .B name
 461 is unset.
 462 .RS
 463
 464 .TP
 465 .I passphrase-file [<filename>]
 466 Obtain the passphrase from
 467 .B filename
 468 for the next command requiring a passphrase. This is equivalent to the
 469 .I "\-\-passphrase-file"
 470 command line option. This value will be unset after the next protocol
 471 command to prevent misuse.
 472
 473 .TP
 474 .I new-passphrase-file [<filename>]
 475 Obtain the passphrase from
 476 .B filename
 477 for the next command requiring a new passphrase. This is equivalent to the
 478 .I "\-\-new-passphrase-file"
 479 command line option. This value will be unset after the next protocol
 480 command to prevent misuse.
 481
 482 .TP
 483 .I sign-passphrase-file [<filename>]
 484 Obtain the passphrase from
 485 .B filename
 486 for the next command requiring a passphrase used for signing. This is
 487 equivalent to the
 488 .I "\-\-sign-passphrase-file"
 489 command line option and is optionally used for signing a symmetrically
 490 encrypted data file. This value will be unset after the next protocol command
 491 to prevent misuse.
 492
 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 .passwd
 509 Change the passphrase for the secret key of the opened data file. Using this
 510 dot command rather than the pwmd
 511 .B PASSWD
 512 protocol command is recommended since it determines whether to use
 513 pinentry or not. For symmetrically encrypted data files, use the
 514 .B .save
 515 command instead.
 516
 517 .TP
 518 .I .listkeys [--options] [pattern[,...]]
 519 Display human readable output of the LISTKEYS protocol command.
 520
 521 .TP
 522 .I .help
 523 Show available interactive commands.
 524
 525 .SH EXAMPLES
 526 To list all XML root elements of the data file and use
 527 .BR pinentry (1)
 528 to retrieve the passphrase (if required):
 529 .RS
 530 .I echo list | pwmc filename
 531 .RE
 532 .P
 533 To store an element path and save the file afterwards:
 534 .RS
 535 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
 536 .P
 537 And then to get the content:
 538 .P
 539 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 540 .RE
 541 .P
 542 Store a larger file:
 543 .RS
 544 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
 545 .RE
 546 or
 547 .RS
 548 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
 549 .RE
 550 .P
 551 Clear the file cache for a single file:
 552 .RS
 553 .I echo 'clearcache filename' | pwmc
 554 .RE
 555 .P
 556 To list root elements of a data file which is stored on a remote pwmd server
 557 over an SSH connection:
 558 .RS
 559 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
 560 .RE
 561 .P
 562 Connect to a remote pwmd server over TLS, interactively:
 563 .RS
 564 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
 565 .RE
 566
 567 .SH NOTES
 568 Be careful of newline characters when storing data. The data is transferred
 569 and stored exactly as the input is read, newlines and all. If you wonder why
 570 your new passphrase for a service doesn't work then a trailing newline
 571 character may be the reason.
 572
 573 .SH FILES
 574 .TP
 575 .B @pwmd_socket@
 576 Default pwmd socket to connect to.
 577 .TP
 578 .B ~/.pwmd/pinentry.conf
 579 Default settings that
 580 .BR pinentry (1)
 581 will use for the terminal, terminal type or X11 display.
 582 .TP
 583 .B @pinentry@
 584 Default location of the
 585 .BR pinentry (1)
 586 binary.
 587
 588 .SH AUTHOR
 589 Ben Kibbey <bjk@luxsci.net>
 590 .br
 591 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 592
 593 .SH "SEE ALSO"
 594 .BR pwmd (1),
 595 .BR pinentry (1),
 596 .BR ssh-keygen (1),
 597 .BR authorized_keys (5),
 598 .BR socat (1),
 599 .BR libpwmd (3)
 600
 601 And the pwmd texinfo manual for protocol commands and their syntax.