From 5ea2f3065ecfb8dcf337d63097e5c8cb51003800 Mon Sep 17 00:00:00 2001 From: Simon Tatham Date: Tue, 19 May 2015 18:24:04 +0100 Subject: [PATCH] Unix Pageant: man page and online help. I think Unix Pageant is now more or less usable, though of course I wouldn't blame anyone for sticking with other SSH agent solutions. --- doc/Makefile | 4 +- doc/man-pag.but | 270 ++++++++++++++++++++++++++++++++++++++++++++++++ unix/uxpgnt.c | 24 ++++- 3 files changed, 296 insertions(+), 2 deletions(-) create mode 100644 doc/man-pag.but diff --git a/doc/Makefile b/doc/Makefile index 96a19eb1..0477cb30 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -58,7 +58,8 @@ putty.hhp: $(INPUTS) chm.but $(HALIBUT) --html $(INPUTS) chm.but MKMAN = $(HALIBUT) --man=$@ mancfg.but $< -MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1 +MANPAGES = putty.1 puttygen.1 plink.1 pscp.1 psftp.1 puttytel.1 pterm.1 \ + pageant.1 man: $(MANPAGES) putty.1: man-putt.but mancfg.but; $(MKMAN) @@ -68,6 +69,7 @@ pscp.1: man-pscp.but mancfg.but; $(MKMAN) psftp.1: man-psft.but mancfg.but; $(MKMAN) puttytel.1: man-ptel.but mancfg.but; $(MKMAN) pterm.1: man-pter.but mancfg.but; $(MKMAN) +pageant.1: man-pag.but mancfg.but; $(MKMAN) mostlyclean: rm -f *.html *.txt *.hlp *.cnt *.1 *.info vstr.but *.hh[pck] diff --git a/doc/man-pag.but b/doc/man-pag.but new file mode 100644 index 00000000..15bc5bad --- /dev/null +++ b/doc/man-pag.but @@ -0,0 +1,270 @@ +\cfg{man-identity}{pageant}{1}{2015-05-19}{PuTTY tool suite}{PuTTY tool suite} + +\H{pageant-manpage} Man page for Pageant + +\S{pageant-manpage-name} NAME + +\cw{pageant} - SSH authentication agent for the PuTTY tools + +\S{pageant-manpage-synopsis} SYNOPSIS + +\c pageant ( -X | -T | --permanent | --debug ) [ key-file... ] +\e bbbbbbb bb bb bbbbbbbbbbb bbbbbbb iiiiiiii +\c pageant [ key-file... ] --exec command [ args... ] +\e bbbbbbb iiiiiiii bbbbbb iiiiiii iiii +\c pageant -a key-file... +\e bbbbbbb bb iiiiiiii +\c pageant ( -d | --public | --public-openssh ) key-identifier... +\e bbbbbbb bb bbbbbbbb bbbbbbbbbbbbbbbb iiiiiiiiiiiiii +\c pageant -D +\e bbbbbbb bb +\c pageant -l +\e bbbbbbb bb + +\S{pageant-manpage-description} DESCRIPTION + +\c{pageant} is both an SSH authentication agent, and also a tool for +communicating with an already-running agent. + +When running as an SSH agent, it listens on a Unix-domain socket for +connections from client processes running under your user id. Clients +can load SSH private keys into the agent, or request signatures on a +given message from a key already in the agent. This permits one-touch +authentication by SSH client programs, if Pageant is holding a key +that the server they are connecting to will accept. + +\c{pageant} can also act as a client program itself, communicating +with an already-running agent to add or remove keys, list the keys, or +extract their public half. + +To run \c{pageant} as an agent, you must provide an option to tell it +what its \e{lifetime} should be. Typically you would probably want +Pageant to last for the duration of a login session, in which case you +should use either \cw{-X} or \cw{-T}, depending on whether your login +session is GUI or purely terminal-based respectively. For example, in +your X session startup script you might write + +\c eval $(pageant -X) +\e bbbbbbbbbbbbbbbbbb + +which will cause Pageant to start running, monitor the X server to +notice when your session terminates (and then it will terminate too), +and print on standard output some shell commands to set environment +variables that client processes will need to find the running agent. + +In a terminal-based login, you could do almost exactly the same thing +but with \cw{-T}: + +\c eval $(pageant -T) +\e bbbbbbbbbbbbbbbbbb + +This will cause Pageant to tie its lifetime to that of your +controlling terminal: when you log out, and the terminal device ceases +to be associated with your session, Pageant will notice that it has no +controlling terminal any more, and will terminate automatically. + +In either of these modes, you can also add one or more private keys as +extra command-line arguments, e.g. + +\c eval $(pageant -T ~/.ssh/key.ppk) +\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb + +in which case Pageant will prompt for the keys' passphrases (if any) +and start the agent with those keys already loaded. Passphrase prompts +will use the controlling terminal if one is available, or the GUI if +one of those is available. If neither is available, no passphrase +prompting can be done. + +To use Pageant to talk to an existing agent, you can add new keys +using \cw{-a}, list the current set of keys' fingerprints and comments +with \cw{-l}, extract the full public half of any key using +\cw{--public} or \cw{--public-openssh}, delete a key using \cw{-d}, or +delete all keys using \cw{-D}. + +\S{pageant-manpage-lifetime} LIFETIME + +The following options are called \e{lifetime modes}. They all request +Pageant to operate in agent mode; each one specifies a different +method for Pageant to start up and know when to shut down. + +\dt \cw{-X} + +\dd Pageant will open a connection to your X display, and when that +connection is lost, it will terminate. This gives it the same lifetime +as your GUI login session, so in this mode it is suitable for running +from a startup script such as \cw{.xsession}. The actual agent will be +a subprocess; the main Pageant process will terminate immediately, +after printing environment-variable setting commands on standard +output which should be installed in any process wanting to communicate +with the agent. + +\lcont{ + +The usual approach would be to run + +\c eval $(pageant -X) +\e bbbbbbbbbbbbbbbbbb + +in an X session startup script. However, other possibilities exist, +such as directing the standard output of \cq{pageant -X} to a file +which is then sourced by any new shell. + +} + +\dt \cw{-T} + +\dd Pageant will tie its lifetime to that of the login session running +on its controlling terminal, by noticing when it ceases to have a +controlling terminal (which will automatically happen as a side effect +of the session leader process terminating). Like \cw{-X}, Pageant will +print environment-variable commands on standard output. + +\dt \cw{--exec} \e{command} + +\dd Pageant will run the provided command as a subprocess, preloaded +with the appropriate environment variables to access the agent it +starts up. When the subprocess terminates, Pageant will terminate as +well. + +\lcont{ + +All arguments on Pageant's command line after \cw{--exec} will be +treated as part of the command to run, even if they look like other +valid Pageant options or key files. + +} + +\dt \cw{--permanent} + +\dd Pageant will fork off a subprocess to be the agent, and print +environment-variable commands on standard output, like \cw{-X} and +\cw{-T}. However, in this case, it will make no effort to limit its +lifetime in any way; it will simply run permanently, unless manually +killed. The environment variable \cw{SSH_AGENT_PID}, set by the +commands printed by Pageant, permits the agent process to be found for +this purpose. + +\lcont{ + +This option is not recommended, because any method of manually killing +the agent carries the risk of the session terminating unexpectedly +before it manages to happen. + +} + +\dt \cw{--debug} + +\dd Pageant will run in the foreground, without forking. It will print +its enviroment variable setup commands on standard output, and then it +will log all agent activity to standard output as well. This is useful +for debugging what Pageant itself is doing, or what another process is +doing to it. + +\S{pageant-manpage-client} CLIENT OPTIONS + +The following options tell Pageant to operate in client mode, +contacting an existing agent via environment variables that it should +already have set. + +\dt \cw{-a} \e{key-files} + +\dd Load the specified private key file(s), decrypt them if necessary +by prompting for their passphrases, and add them to the +already-running agent. + +\lcont{ + +The private key files must be in PuTTY's \cw{.ppk} file format. + +} + +\dt \cw{-l} + +\dd List the keys currently in the running agent. Each key's +fingerprint and comment string will be shown. + +\dt \cw{--public} \e{key-identifiers} + +\dd Print the public half of each specified key, in the RFC 4716 +standard format (multiple lines, starting with \cq{---- BEGIN SSH2 +PUBLIC KEY ----}). + +\lcont{ + +Each \e{key-identifier} can be any of the following: + +\b The name of a file containing the key, either the whole key (again +in \cw{.ppk} format) or just its public half. + +\b The key's comment string, as shown by \cw{pageant -l}. + +\b Enough hex digits of the key's fingerprint to be unique among keys +currently loaded into the agent. + +If Pageant can uniquely identify one key by interpreting the +\e{key-identifier} in any of these ways, it will assume that key was +the one you meant. If it cannot, you will have to specify more detail. + +If you find that your desired \e{key-identifier} string can be validly +interpreted as more than one of the above \e{kinds} of identification, +you can disambiguate by prefixing it with \cq{file:}, \cq{comment:} or +\cq{fp:} to indicate that it is a filename, comment string or +fingerprint prefix respectively. + +} + +\dt \cw{--public-openssh} \e{key-identifiers} + +\dd Print the public half of each specified key, in the one-line +format used by OpenSSH, suitable for putting in +\cw{.ssh/authorized_keys} files. + +\dt \cw{-d} \e{key-identifiers} + +\dd Delete each specified key from the agent's memory, so that the +agent will no longer serve it to clients unless it is loaded in again +using \cw{pageant -a}. + +\dt \cw{-D} + +\dd Delete all keys from the agent's memory, leaving it completely +empty. + +\S{pageant-manpage-options} OPTIONS + +\dt \cw{-v} + +\dd Verbose mode. When Pageant runs in agent mode, this option causes +it to log all agent activity to its standard error. For example, you +might run + +\lcont{ + +\c eval $(pageant -X -v 2>~/.pageant.log) +\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb + +and expect a list of all signatures requested by agent clients to +build up in that log file. + +The log information is the same as that produced by the \cw{--debug} +lifetime option, but \cw{--debug} sends it to standard output (since +that is the main point of debugging mode) whereas \cw{-v} in all other +lifetime modes sends the same log data to standard error (being a +by-product of the program's main purpose). Using \cw{-v} in +\cw{--debug} mode has no effect: the log still goes to standard +output. + +} + +\dt \cw{--help} + +\dd Print a brief summary of command-line options and terminate. + +\dt \cw{--version} + +\dd Print the version of Pageant. + +\dt \cw{--} + +\dd Cause all subsequent arguments to be treated as key file names, +even if they look like options. diff --git a/unix/uxpgnt.c b/unix/uxpgnt.c index 95646b3e..bfd4f0ff 100644 --- a/unix/uxpgnt.c +++ b/unix/uxpgnt.c @@ -111,7 +111,29 @@ static void usage(void) { printf("Pageant: SSH agent\n"); printf("%s\n", ver); - printf("FIXME\n"); + printf("Usage: pageant [key files]\n"); + printf(" pageant [key files] --exec [args]\n"); + printf(" pageant -a [key files]\n"); + printf(" pageant -d [key identifiers]\n"); + printf(" pageant --public [key identifiers]\n"); + printf(" pageant --public-openssh [key identifiers]\n"); + printf(" pageant -l\n"); + printf(" pageant -D\n"); + printf("Lifetime options, for running Pageant as an agent:\n"); + printf(" -X run with the lifetime of the X server\n"); + printf(" -T run with the lifetime of the controlling tty\n"); + printf(" --permanent run permanently\n"); + printf(" --debug run in debugging mode, without forking\n"); + printf(" --exec run with the lifetime of that command\n"); + printf("Client options, for talking to an existing agent:\n"); + printf(" -a add key(s) to the existing agent\n"); + printf(" -l list currently loaded key fingerprints and comments\n"); + printf(" --public print public keys in RFC 4716 format\n"); + printf(" --public-openssh print public keys in OpenSSH format\n"); + printf(" -d delete key(s) from the agent\n"); + printf(" -D delete all keys from the agent\n"); + printf("Other options:\n"); + printf(" -v verbose mode (in agent mode)\n"); exit(1); } -- 2.45.2