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 SHA-1 hash of the servers certificate against the specified
  90 SHA-1 hash.
  91 .TP
  92
  93 .I "\--no-ssh-agent"
  94 Normally, when the SSH_AUTH_SOCK environment variable is set, pwmc will get
  95 authentication details from the ssh agent. When this option is specified or
  96 when the environment variable is unset, a private key must be specified on the
  97 command line with the
  98 .I "\-\-identity"
  99 option. See
 100 .BR ssh-add (1)
 101 for how to add a private key to the ssh agent. Note that the
 102 .I "\-\-identity"
 103 command line option has priority over the ssh agent.
 104
 105 .TP
 106 .I "\-\-identity, -i <filename>"
 107 The SSH identity file use when connecting via SSH.
 108
 109 .TP
 110 .I "\-\-knownhosts, -k <filename"
 111 The SSH knownhosts file to use when connection via SSH. The default is
 112 ~/.ssh/knownhosts.
 113
 114 .TP
 115 .I "\--no-lock"
 116 Do not lock the data file upon opening it. Locking the data file
 117 prevents other clients from opening the same file.
 118
 119 .TP
 120 .I "\--lock-timeout <N>"
 121 The time in tenths of a second to wait for another client to release the lock
 122 held on a data file before returning an error. When not specified or 0, pwmc
 123 will wait indefinately. When -1, an error will be returned
 124 immediately. The default is 50.
 125
 126 .TP
 127 .I "\--name, -n <string>"
 128 Set the client name to the specified string. This string is what is shown in
 129 the
 130 .BR pwmd (1)
 131 log files. The default is "pwmc".
 132
 133 .TP
 134 .I "\--pinentry, <path>"
 135 The full path to the pinentry binary. The default is specified at
 136 compile-time.
 137
 138 .TP
 139 .I "\--local-pinentry"
 140 Force use of the local pinentry for passphrase retrieval. This will
 141 disable pwmd's pinentry and use a pinentry fork'ed from libpwmd.
 142
 143 .TP
 144 .I "\--no-pinentry"
 145 Disable the use of pinentry entirely. Both pwmd and libpwmd's local
 146 pinentry will be disabled. Pwmc will prompt for the passphrase via
 147 stdin.
 148
 149 .TP
 150 .I "\--ttyname, -y <path>"
 151 The full path of the TTY for
 152 .BR pinentry (1)
 153 to prompt on. The default is the current terminal.
 154
 155 .TP
 156 .I "\--ttytype, -t <string>"
 157 The terminal type of the specified TTY that
 158 .BR pinentry (1)
 159 should use. This is required if
 160 .I "\-\-ttyname"
 161 is specified.
 162
 163 .TP
 164 .I "\--display, -d <string>"
 165 The X11 display that
 166 .BR pinentry (1)
 167 should use. Note that remote connections to pwmd do not use pwmd's
 168 pinentry but use a pinentry fork'ed from libpwmd instead. The default
 169 is obtained from the
 170 .B DISPLAY
 171 environment variable.
 172
 173 .TP
 174 .I "\--lc-ctype, <string>"
 175 For
 176 .BR pinentry (1)
 177 localization.
 178
 179 .TP
 180 .I "\--lc-messages, <string>"
 181 For
 182 .BR pinentry (1)
 183 localization.
 184
 185 .TP
 186 .I "\--tries, <n>"
 187 The number of times before failing when an invalid passphrase is entered in
 188 the
 189 .BR pinentry (1)
 190 dialog. The default is 3.
 191
 192 .TP
 193 .I "\-\-timeout, <seconds>"
 194 The number of seconds before
 195 .BR pinentry (1)
 196 will timeout while waiting for a passphrase. The default is 30.
 197
 198 .TP
 199 .I "\--inquire <command>"
 200 Some pwmd protocol commands use what is called an INQUIRE to retrieve
 201 data from the client. This options argument should be the command name
 202 that uses an inquire. The command data will be read from the file
 203 descriptor specified by the
 204 .I "\-\-inquire\-fd"
 205 option or stdin by default.
 206
 207 .TP
 208 .I "\--inquire-line, -L <string>"
 209 The initial line to send during an inquire and before any other data read from
 210 the inquire file descriptor. This option is useful to specify an
 211 element path without needing to modify the remaining inquire data. See
 212 .B EXAMPLES
 213 below.
 214
 215 .TP
 216 .I "\--inquire-fd <fd>"
 217 Read inquire data from the specified file descriptor. For use with the
 218 .I "\-\-inquire"
 219 option. By default, inquire data is read from stdin. Use
 220 .I "\-\-inquire-line"
 221 to send an initial line before the actual data.
 222
 223 .TP
 224 .I "\-\-inquire-file <filename>"
 225 Read inquire data from the specified filename.  For use with the
 226 .I "\-\-inquire"
 227 option. By default, inquire data is read from stdin. Use
 228 .I "\-\-inquire-line"
 229 to send an initial line before the actual data.
 230
 231 .TP
 232 .I "\--output-fd <fd>"
 233 Redirect the output of the pwmd command to the specified file
 234 descriptor. The default is stdout.
 235
 236 .TP
 237 .I "\--save, -S"
 238 After the command has been processed without error, send the SAVE
 239 command to the server to write any changes to disk.
 240
 241 .TP
 242 .I "\--force-save"
 243 Like
 244 .I "\-\-save"
 245 but expire any cached passphrase on the server before saving. This
 246 will require a passphrase, if needed, when saving.
 247
 248 .TP
 249 .I "\-\-no\-passphrase"
 250 When saving to a new file, do not prompt for a passphrase. This will
 251 allow the data file to be opened without a passphrase.
 252
 253 .TP
 254 .I "\-\-no-gpg-agent"
 255 When
 256 .BR pwmd (1)
 257 is compiled with
 258 .BR gpg-agent (1)
 259 support and gpg-agent usage is enabled, pwmd will default to using
 260 the gpg-agent key-pair encryption mechanism rather than symmetric
 261 encryption of the data file. Use this option to force symmetric
 262 encryption of the data file without using gpg-agent. Note that this
 263 option only has an affect when saving to a new file.
 264
 265 .TP
 266 .I "\--key-file <filename>"
 267 Read the passphrase used to open a file from the specified filename.
 268
 269 .TP
 270 .I "\--new-key-file <filename>"
 271 Read a passphrase from the specified filename that is to be used for a
 272 new data file or when changing the passphrase for an existing data
 273 file.
 274
 275 .TP
 276 .I "\--cipher <string>"
 277 When saving, encrypt with the specified cipher algorithm. See the
 278 pwmd documentation for available ciphers. The default is "aes256".
 279
 280 .TP
 281 .I "\--cipher-iterations <N>"
 282 The number of cipher encryption iterations of the XML data. This is
 283 actually N+1.
 284
 285 .TP
 286 .I "\-\-key\-params <string>"
 287 When saving, use the specified key parameters rather than the pwmd
 288 default. This should be a valid S-expression. See the libgcrypt
 289 documentation for details.
 290
 291 .TP
 292 .I "\-\-keygrip <hex-string>"
 293 Encrypt the XML data using the specified key grip. The key can be any
 294 that
 295 .BR gpg-agent (1)
 296 knows of.
 297
 298 .TP
 299 .I "\-\-sign-keygrip <hex-string>"
 300 Sign the encrypted XML data using the specified key grip. The key can
 301 be any that
 302 .BR gpg-agent (1)
 303 knows of.
 304
 305 .TP
 306 .I "\--s2k-count <n>"
 307 The number of passphrase hashing iterations for a new file.
 308
 309 .TP
 310 .I "\--no-status"
 311 Do not show server status messages. By default, status messages are
 312 written to stderr.
 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 local 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 <datafile> [<filename>]
 474 Set the
 475 .B filename
 476 containing the passphrase to open
 477 .B datafile
 478 for the next command requiring a passphrase. This is equivalent to the
 479 .I "\-\-key-file"
 480 command line option. This value will be unset after the next protocol
 481 command to prevent misuse.
 482 .TP
 483 .I new-keyfile <datafile> [<filename>]
 484 Set the
 485 .B filename
 486 containing the passphrase to use to save
 487 .B datafile
 488 for the next command requiring a new passphrase. This is equivalent to the
 489 .I "\-\-new-key-file"
 490 command line option. This value will be unset after the next protocol
 491 command to prevent misuse.
 492 .TP
 493 .I pinentry-timeout <seconds>
 494 Set the amount of seconds before the pinentry program will close and return an
 495 error while waiting for user input.
 496 .RE
 497
 498 .TP
 499 .I .save [args]
 500 Save changes of the document to disk. Using this dot command rather than
 501 the pwmd
 502 .B SAVE
 503 protocol command is recommended since it determines whether to use
 504 pinentry or not.
 505
 506 .TP
 507 .I .help
 508 Show available interactive commands.
 509
 510 .SH EXAMPLES
 511 To list all XML root elements of the data file and use
 512 .BR pinentry (1)
 513 to retrieve the passphrase (if required):
 514 .RS
 515 .I echo list | pwmc filename
 516 .RE
 517 .P
 518 To store an element path and save the file afterwards:
 519 .RS
 520 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
 521 .P
 522 And then to get the content:
 523 .P
 524 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
 525 .RE
 526 .P
 527 Store a larger file:
 528 .RS
 529 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
 530 .RE
 531 or
 532 .RS
 533 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
 534 .RE
 535 .P
 536 Clear the file cache for a single file:
 537 .RS
 538 .I echo 'clearcache filename' | pwmc
 539 .RE
 540 .P
 541 To list root elements of a data file which is stored on a remote pwmd server
 542 over an SSH connection:
 543 .RS
 544 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
 545 .RE
 546 .P
 547 Connect to a remote pwmd server over TLS, interactively:
 548 .RS
 549 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
 550 .RE
 551 .P
 552 Connect to a remote pwmd server over TLS and generate a new keypair
 553 for a data file that may not already exist using a keyfile as
 554 passphrase and inquire data from a file descriptor:
 555 .RS
 556 .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
 557 .RE
 558
 559 .SH NOTES
 560 Be careful of newline characters when storing data. The data is transfered and
 561 stored exactly as the input is read, newlines and all. If you wonder why your
 562 new passphrase for a service doesn't work then a trailing newline character
 563 may be the reason.
 564
 565 .SH FILES
 566 .TP
 567 .B @pwmd_socket@
 568 Default pwmd socket to connect to.
 569 .TP
 570 .B ~/.pwmd/pinentry.conf
 571 Default settings that
 572 .BR pinentry (1)
 573 will use for the terminal, terminal type or X11 display.
 574 .TP
 575 .B @pinentry@
 576 Default location of the
 577 .BR pinentry (1)
 578 binary.
 579
 580 .SH AUTHOR
 581 Ben Kibbey <bjk@luxsci.net>
 582 .br
 583 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
 584
 585 .SH "SEE ALSO"
 586 .BR pwmd (1),
 587 .BR pinentry (1),
 588 .BR ssh-keygen (1),
 589 .BR authorized_keys (5),
 590 .BR socat (1),
 591 .BR libpwmd (3)
 592
 593 And the pwmd texinfo manual for protocol commands and their syntax.