1 .\" Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
2 .\" Ben Kibbey <bjk@luxsci.net>
4 .\" This file is part of libpwmd.
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.
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.
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/>.
19 \\$2 \(laURL: \\$1 \(ra\\$3
21 .if \n[.g] .mso www.tmac
22 .TH PWMC 1 "25 Feb 2013" "@VERSION@" "Password Manager Client"
25 pwmc \- send a command to a pwmd server
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
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
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.
57 .I "\--socket-timeout <seconds>"
58 The number of seconds before a remote command will timeout. The
59 default is 300 seconds.
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.
67 .I "\--client-cert, <filename>"
68 The X509 client certificate to use when authenticating a TLS
69 connection. Required when connecting via TLS.
72 .I "\--client-key, <filename>"
73 The X509 key file to use to unlock the client certificate. Required
74 when connecting via TLS.
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
84 Verify the TLS server hostname stored in the server certificate to the
85 connected hostname. The default is disabled.
88 .I "\--tls-fingerprint <string>"
91 TLS server certificate against the specified SHA-256 hash.
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
102 for how to add a private key to the ssh agent. Note that the
104 command line option has priority over the ssh agent.
107 .I "\-\-identity, -i <filename>"
108 The SSH identity file use when connecting via SSH.
111 .I "\-\-knownhosts, -k <filename"
112 The SSH knownhosts file to use when connection via SSH. The default is
117 Do not lock the data file upon opening it. Locking the data file
118 prevents other clients from opening the same file.
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.
128 .I "\--name, -n <string>"
129 Set the client name to the specified string. This string is what is shown in
132 log files. The default is "pwmc".
135 .I "\--pinentry, <path>"
136 The full path to the pinentry binary. The default is specified at
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.
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
151 .I "\--ttyname, -y <path>"
152 The full path of the TTY for
154 to prompt on. The default is the current terminal.
157 .I "\--ttytype, -t <string>"
158 The terminal type of the specified TTY that
160 should use. This is required if
165 .I "\--display, -d <string>"
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
172 environment variable.
175 .I "\--lc-ctype, <string>"
181 .I "\--lc-messages, <string>"
188 The number of times before failing when an invalid passphrase is entered in
191 dialog. The default is 3.
194 .I "\-\-timeout, <seconds>"
195 The number of seconds before
197 will timeout while waiting for a passphrase. The default is 30.
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
206 option or stdin by default.
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
217 .I "\--inquire-fd <fd>"
218 Read inquire data from the specified file descriptor. For use with the
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.
225 .I "\-\-inquire-file <filename>"
226 Read inquire data from the specified filename. For use with the
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.
233 .I "\--output-fd <fd>"
234 Redirect the output of the pwmd command to the specified file
235 descriptor. The default is stdout.
239 After the command has been processed without error, send the SAVE
240 command to the server to write any changes to disk.
246 but expire any cached passphrase on the server before saving. This
247 will require a passphrase, if needed, when saving.
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.
255 .I "\-\-no-gpg-agent"
260 support and gpg-agent usage is enabled, pwmd will default to using
261 the gpg-agent key-pair encryption mechanism rather than symmetric
262 encryption of the data file. Use this option to force symmetric
263 encryption of the data file without using gpg-agent. Note that this
264 option only has an affect when saving to a new file.
267 .I "\--key-file <filename>"
268 Read the passphrase used to open a file from the specified filename.
271 .I "\--new-key-file <filename>"
272 Read a passphrase from the specified filename that is to be used for a
273 new data file or when changing the passphrase for an existing data
277 .I "\--cipher <string>"
278 When saving, encrypt with the specified cipher algorithm. See the
279 pwmd documentation for available ciphers. The default is "aes256".
282 .I "\--cipher-iterations <N>"
283 The number of cipher encryption iterations of the XML data. This is
287 .I "\-\-key\-params <string>"
288 When saving, use the specified key parameters rather than the pwmd
289 default. This should be a valid S-expression. See the libgcrypt
290 documentation for details.
293 .I "\-\-keygrip <hex-string>"
294 Encrypt the XML data using the specified key grip. The key can be any
300 .I "\-\-sign-keygrip <hex-string>"
301 Sign the encrypted XML data using the specified key grip. The key can
307 .I "\--s2k-count <n>"
308 The number of passphrase hashing iterations for a new file.
312 Do not show server status messages. By default, status messages are
317 Do not show informational messages from pwmc. Implies --no-status.
321 Use an interactive pwmc shell. This will let you send more than one command
322 per connection and is the default when input is from a terminal. See
324 for more information.
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.
339 Most SSH servers allow special options in the
341 file that do various things. One such option is the
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
347 .B ~/.ssh/authorized_keys
348 file on the remote SSH host:
350 command="socat gopen:$HOME/.pwmd/socket -" [...public.key...]
354 is prepended to the public key that was
357 and specified using the
363 command can be replaced with any utility that can read from stdin and write
364 to a local domain socket.
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
374 .I "\\-\-no\-pinentry"
375 command line option was specified.
377 The terminal, terminal type or
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
388 .B ~/.pwmd/pinentry.conf
391 pair per line. Comments begin with a '#'.
394 The full path to the location of the pinentry binary.
397 The X11 display to use.
400 The full path to the tty that pinentry should prompt on.
403 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
407 For pinentry localization.
410 For pinentry localization.
414 Since interactive mode uses the
416 library, the TAB character is normally interpreted as the line completion
417 character. This conflicts with the
419 element separation character. In order to insert a TAB you will first need to
420 press CTRL-V then press TAB. See
422 for more information about line history and completion.
424 Interactive mode also has a few dot commands. Dot commands (an idea
427 command line program), begin with a
429 followed by the command name and any arguments. Here are the available
430 pwmc interactive commands:
436 while losing any changes to the current filename. Although the
438 protocol command can be used to open a file, this dot command is
439 recommended because it takes care of pinentry settings among other
443 .I .read [--prefix <string>] <filename> <command> [args ...]
446 that uses a server INQUIRE. The
448 option behaves like the
449 .I "\-\-inquire-line"
450 command line option. It is the initial line to send before any data
455 .I .redir <filename> <command>
456 Redirect the output of
462 .I .set help | <name> [<value>] [...]
469 is specified, the option
474 .I keyfile <datafile> [<filename>]
477 containing the passphrase to open
479 for the next command requiring a passphrase. This is equivalent to the
481 command line option. This value will be unset after the next protocol
482 command to prevent misuse.
484 .I new-keyfile <datafile> [<filename>]
487 containing the passphrase to use to save
489 for the next command requiring a new passphrase. This is equivalent to the
490 .I "\-\-new-key-file"
491 command line option. This value will be unset after the next protocol
492 command to prevent misuse.
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.
501 Save changes of the document to disk. Using this dot command rather than
504 protocol command is recommended since it determines whether to use
509 Show available interactive commands.
512 To list all XML root elements of the data file and use
514 to retrieve the passphrase (if required):
516 .I echo list | pwmc filename
519 To store an element path and save the file afterwards:
521 .I echo -ne 'isp\\\\tsmtp\\\\thostname\\\\tsomehost.com' | pwmc --inquire STORE -S filename
523 And then to get the content:
525 .I echo -ne 'get isp\\\\tsmtp\\\\thostname' | pwmc filename
530 .I echo -ne 'some\\\\telement\\\\tpath\\\\t' | cat - data_file | pwmc --inquire STORE -S filename
534 .I pwmc --inquire STORE --inquire-line 'some\\\\telement\\\\tpath\\\\t' -S filename < data_file
537 Clear the file cache for a single file:
539 .I echo 'clearcache filename' | pwmc
542 To list root elements of a data file which is stored on a remote pwmd server
543 over an SSH connection:
545 .I echo list | pwmc --url ssh://user@hostname -i ~/.ssh/identity filename
548 Connect to a remote pwmd server over TLS, interactively:
550 .I pwmc --url tls://hostname --ca-cert cafile.pem --client-cert client.pem --client-key clientkey.pem filename
553 Connect to a remote pwmd server over TLS and generate a new keypair
554 for a data file that may not already exist using a keyfile as
555 passphrase and inquire data from a file descriptor:
557 .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
561 Be careful of newline characters when storing data. The data is transfered and
562 stored exactly as the input is read, newlines and all. If you wonder why your
563 new passphrase for a service doesn't work then a trailing newline character
569 Default pwmd socket to connect to.
571 .B ~/.pwmd/pinentry.conf
572 Default settings that
574 will use for the terminal, terminal type or X11 display.
577 Default location of the
582 Ben Kibbey <bjk@luxsci.net>
584 .URL "http://libpwmd.sourceforge.net/" "libpwmd Homepage" .
590 .BR authorized_keys (5),
594 And the pwmd texinfo manual for protocol commands and their syntax.