1pageant(1)                     PuTTY tool suite                     pageant(1)
2
3
4

NAME

6       pageant - PuTTY SSH authentication agent
7

SYNOPSIS

9       pageant ( -X | -T | --permanent | --debug ) [ [ --encrypted ] key-file... ]
10       pageant [ [ --encrypted ] key-file... ] --exec command [ args... ]
11       pageant -a [ --encrypted ] key-file...
12       pageant ( -d | -r | --public | --public-openssh ) key-identifier...
13       pageant ( -D | -R )
14       pageant -l [ --fptype format ]
15       pageant --askpass prompt
16

DESCRIPTION

18       pageant is both an SSH authentication agent, and also a tool for commu‐
19       nicating with an already-running agent.
20
21       When running as an SSH agent, it listens on a  Unix-domain  socket  for
22       connections  from  client processes running under your user id. Clients
23       can load SSH private keys into the agent, or request  signatures  on  a
24       given  message  from a key already in the agent. This permits one-touch
25       authentication by SSH client programs, if Pageant is holding a key that
26       the server they are connecting to will accept.
27
28       pageant  can also act as a client program itself, communicating with an
29       already-running agent to add or remove keys, list the keys, or  extract
30       their public half.
31
32       The  agent  protocol used by pageant is compatible with the PuTTY tools
33       and also with other implementations such as OpenSSH's  SSH  client  and
34       ssh-agent(1).  Some  pageant features are implemented with protocol ex‐
35       tensions, so will only work if pageant is on both ends.
36
37       To run pageant as an agent, you must provide an option to tell it  what
38       its  lifetime  should  be. Typically you would probably want Pageant to
39       last for the duration of a login session, in which case you should  use
40       either  -X  or  -T,  depending  on whether your login session is GUI or
41       purely terminal-based respectively. For  example,  in  your  X  session
42       startup script you might write
43
44       eval $(pageant -X)
45
46       which  will cause Pageant to start running, monitor the X server to no‐
47       tice when your session terminates (and then it will terminate too), and
48       print  on  standard output some shell commands to set environment vari‐
49       ables that client processes will need to find the running agent.
50
51       In a terminal-based login, you could do almost exactly the  same  thing
52       but with -T:
53
54       eval $(pageant -T)
55
56       This will cause Pageant to tie its lifetime to that of your controlling
57       terminal: when you log out, and the terminal device ceases to be  asso‐
58       ciated  with  your session, Pageant will notice that it has no control‐
59       ling terminal any more, and will terminate automatically.
60
61       In either of these modes, you can also add one or more private keys  as
62       extra command-line arguments, e.g.
63
64       eval $(pageant -T ~/.ssh/key.ppk)
65
66       in which case Pageant will immediately prompt for the keys' passphrases
67       (if any) and start the agent with those keys already loaded in  cleart‐
68       ext  form.  Passphrase prompts will use the controlling terminal if one
69       is available, or failing that the GUI if one  of  those  is  available.
70       (The  prompt  method  can be overridden with the --gui-prompt or --tty-
71       prompt options.) If neither is available, no passphrase  prompting  can
72       be done.
73
74       Alternatively,  you  can  start  an agent with keys stored in encrypted
75       form:
76
77       eval $(pageant -T --encrypted ~/.ssh/key.ppk)
78
79       In this case, Pageant will not prompt for a passphrase at startup;  in‐
80       stead,  it  will  prompt  the first time a client tries to use the key.
81       (Pageant will need access to a GUI so that it can pop up  a  passphrase
82       prompt when required, unless it's running in --debug mode.)
83
84       To use Pageant to talk to an existing agent, you can add new keys using
85       -a, list the current set of keys' fingerprints and  comments  with  -l,
86       extract  the  full  public  half of any key using --public or --public-
87       openssh, delete a specific key or all keys using -d or -D respectively,
88       or  request  re-encryption of a specific key or all keys using -r or -R
89       respectively.
90

LIFETIME

92       The following options are  called  lifetime  modes.  They  all  request
93       Pageant to operate in agent mode; each one specifies a different method
94       for Pageant to start up and know when to shut down.
95
96       -X     Pageant will open a connection to your X display, and when  that
97              connection  is  lost,  it will terminate. This gives it the same
98              lifetime as your GUI login session, so in this mode it is  suit‐
99              able  for  running  from a startup script such as .xsession. The
100              actual agent will be a subprocess; the main Pageant process will
101              terminate  immediately, after printing environment-variable set‐
102              ting commands on standard output which should  be  installed  in
103              any process wanting to communicate with the agent.
104
105              The usual approach would be to run
106
107              eval $(pageant -X)
108
109              in an X session startup script. However, other possibilities ex‐
110              ist, such as directing the standard output of `pageant -X' to  a
111              file which is then sourced by any new shell.
112
113       -T     Pageant  will tie its lifetime to that of the login session run‐
114              ning on its controlling terminal, by noticing when it ceases  to
115              have  a controlling terminal (which will automatically happen as
116              a side effect of the session leader process  terminating).  Like
117              -X, Pageant will print environment-variable commands on standard
118              output.
119
120       --exec command
121              Pageant will run the provided command as a subprocess, preloaded
122              with  the  appropriate environment variables to access the agent
123              it starts up. When the subprocess terminates, Pageant will  ter‐
124              minate as well.
125
126              All  arguments  on  Pageant's  command line after --exec will be
127              treated as part of the command to run, even if  they  look  like
128              other valid Pageant options or key files.
129
130       --permanent
131              Pageant  will  fork  off a subprocess to be the agent, and print
132              environment-variable commands on standard output,  like  -X  and
133              -T.  However,  in this case, it will make no effort to limit its
134              lifetime in any way; it will simply run permanently, unless man‐
135              ually killed. The environment variable SSH_AGENT_PID, set by the
136              commands printed by Pageant, permits the  agent  process  to  be
137              found for this purpose.
138
139              This  option  is not recommended, because any method of manually
140              killing the agent carries the risk of  the  session  terminating
141              unexpectedly before it manages to happen.
142
143       --debug
144              Pageant  will  run  in  the foreground, without forking. It will
145              print its environment variable setup commands on  standard  out‐
146              put,  and then it will log all agent activity to standard output
147              as well; any passphrase prompts will  need  to  be  answered  on
148              standard input. This is useful for debugging what Pageant itself
149              is doing, or what another process is doing to it.
150

CLIENT OPTIONS

152       The following options tell Pageant to operate in client mode,  contact‐
153       ing  an existing agent via environment variables that it should already
154       have set.
155
156       -a key-files
157              Load the specified private key file(s) and add them to  the  al‐
158              ready-running  agent.  Unless  --encrypted  is  also  specified,
159              pageant will decrypt them if necessary by  prompting  for  their
160              passphrases (with the same choice of user interfaces as in agent
161              mode).
162
163              The private key files must be in PuTTY's .ppk file format.
164
165       -l     List the keys currently in the running agent. Each key's finger‐
166              print  and  comment  string will be shown. (Use the -E option to
167              change the fingerprint format.)
168
169              Keys that will require a passphrase on their next use are listed
170              as  `encrypted'. Keys that can be returned to this state with -r
171              are listed as `re-encryptable'.
172
173       --public key-identifiers
174              Print the public half of each specified key,  in  the  RFC  4716
175              standard  format (multiple lines, starting with `---- BEGIN SSH2
176              PUBLIC KEY ----').
177
178              Each key-identifier can be any of the following:
179
180              The name of a file containing the key, either  the  whole
181                     key (again in .ppk format) or just its public half.
182
183              The key's comment string, as shown by pageant -l.
184
185              Enough  of  one  of  the  key's fingerprint formats to be
186                     unique among keys currently loaded into the agent.
187
188              If Pageant can uniquely identify one  key  by  interpreting  the
189              key-identifier in any of these ways, it will assume that key was
190              the one you meant. If it cannot, you will have to  specify  more
191              detail.
192
193              If  you  find  that  your  desired  key-identifier string can be
194              validly interpreted as more than one of the above kinds of iden‐
195              tification, you can disambiguate by prefixing it as follows:
196
197              `file:'
198                     to indicate that it is a filename
199
200              `comment:'
201                     to indicate that it is a comment string
202
203              `fp:'  to  indicate  that  it  is a fingerprint; any fingerprint
204                     format will be matched
205
206              `sha256:' or `md5:'
207                     to indicate that it is a fingerprint of a specific format
208
209       --public-openssh key-identifiers, -L key-identifiers
210              Print the public half of each specified  key,  in  the  one-line
211              format  used  by  OpenSSH,  suitable  for putting in .ssh/autho‐
212              rized_keys files.
213
214       -d key-identifiers
215              Delete each specified key from the agent's memory, so  that  the
216              agent  will no longer serve it to clients unless it is loaded in
217              again using pageant -a.
218
219       -D     Delete all keys from the agent's memory, leaving  it  completely
220              empty.
221
222       -r key-identifiers
223              `Re-encrypt' each specified key in the agent's memory - that is,
224              forget any cleartext version, so that the user will be  prompted
225              for  a  passphrase again next time the key is used. (For this to
226              be possible, the key must previously have been  added  with  the
227              --encrypted option.)
228
229              (Holding  encrypted  keys is a Pageant extension, so this option
230              and -R are unlikely to work with other agents.)
231
232       -R     `Re-encrypt' all possible keys in the agent's memory. (This  may
233              leave  some keys in cleartext, if they were not previously added
234              with the --encrypted option.)
235
236       --test-sign key-identifier
237
238
239       --test-sign-with-flags=flags key-identifier
240              Sign arbitrary data with the given key. This mode is only likely
241              to be useful when testing pageant itself.
242
243              The  data  to  sign  is taken from standard input, signed by the
244              agent with the key identified by key-identifier, and the result‐
245              ing  signature  emitted  on standard output (as a binary blob in
246              the format defined by the SSH specifications).
247
248              flags is a number representing a combination of  flag  bits  de‐
249              fined by the SSH agent protocol.
250

SSH-ASKPASS REPLACEMENT

252       --askpass prompt
253              With this option, pageant acts as an ssh-askpass(1) replacement,
254              rather than performing any SSH agent functionality. This may  be
255              useful if you prefer Pageant's GUI prompt style, which minimises
256              information leakage about your passphrase length in  its  visual
257              feedback, compared to other ssh-askpass(1) implementations.
258
259              pageant  --askpass implements the standard ssh-askpass(1) inter‐
260              face: it can be passed a prompt to display (as  a  single  argu‐
261              ment) and, if successful, prints the passphrase on standard out‐
262              put and returns a zero exit status. Typically you would use  the
263              environment  variable  SSH_ASKPASS to tell other programs to use
264              pageant in this way.
265

OPTIONS

267       -v     Verbose mode. When Pageant  runs  in  agent  mode,  this  option
268              causes  it  to log all agent activity to its standard error. For
269              example, you might run
270
271              eval $(pageant -X -v 2>~/.pageant.log)
272
273              and expect a list of all signatures requested by  agent  clients
274              to build up in that log file.
275
276              The  log information is the same as that produced by the --debug
277              lifetime option, but --debug sends it to standard output  (since
278              that  is  the  main  point  of debugging mode) whereas -v in all
279              other lifetime modes sends the same log data to  standard  error
280              (being  a by-product of the program's main purpose). Using -v in
281              --debug mode has no effect: the log still goes to standard  out‐
282              put.
283
284       -s, -c Force  Pageant  to  output its environment setup commands in the
285              style of POSIX / Bourne shells (-s) or  C  shells  (-c)  respec‐
286              tively.  If neither option is given, Pageant will guess based on
287              whether the environment variable SHELL has  a  value  ending  in
288              `csh'.
289
290       --symlink fixed-path
291              When  operating  in  agent  mode, as well as creating a uniquely
292              named listening socket, pageant will also create (or  update)  a
293              symbolic link at fixed-path pointing to that socket.
294
295              This   allows  access  to  an  agent  instance  by  setting  the
296              SSH_AUTH_SOCK environment variable to  fixed-path,  rather  than
297              having to use the value invented by pageant when it starts. It's
298              mainly expected to be useful for debugging.
299
300       --encrypted, --no-decrypt
301              When adding keys to the agent (at startup or later),  keep  them
302              in  encrypted form until the first attempt to use them; the user
303              will be prompted for a passphrase then. Once  decrypted,  a  key
304              that  was added in this way can be `re-encrypted' with the -r or
305              -R client options.
306
307              The --encrypted option makes no difference for key  files  which
308              do not have a passphrase.
309
310              (Storing  keys  in  encrypted form is a Pageant extension; other
311              agent implementations are unlikely to support it.)
312
313       -E fingerprint-type, --fptype fingerprint-type
314              Specify the fingerprint format to print.  Only  applicable  when
315              listing  fingerprints  with -l. The available formats are sha256
316              (the default) and md5.
317
318       --gui-prompt, --tty-prompt
319              Force Pageant to prompt for key passphrases  with  a  particular
320              method  (GUI  or  terminal) rather than trying to guess the most
321              appropriate method as described above. (These options are  rele‐
322              vant  whenever a key file is specified to pageant that needs im‐
323              mediate decryption, and in --askpass mode.)
324
325       --help Print a brief summary of command-line options and terminate.
326
327       --version, -V
328              Print the version of Pageant.
329
330       --     Cause all subsequent arguments to be treated as key file  names,
331              even if they look like options.
332
333
334
335PuTTY tool suite                  2015‐05‐19                        pageant(1)
Impressum