1pageant(1) PuTTY tool suite pageant(1)
2
6 pageant - PuTTY SSH authentication agent
7
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
18 pageant is both an SSH authentication agent, and also a tool for commu‐
19 nicating with an already-running agent.
20 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 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 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 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 eval $(pageant -X)
45 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 In a terminal-based login, you could do almost exactly the same thing
52 but with -T:
53 eval $(pageant -T)
55 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 In either of these modes, you can also add one or more private keys as
62 extra command-line arguments, e.g.
63 eval $(pageant -T ~/.ssh/key.ppk)
65 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 Alternatively, you can start an agent with keys stored in encrypted
75 form:
76 eval $(pageant -T --encrypted ~/.ssh/key.ppk)
78 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 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
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 -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 The usual approach would be to run
106 eval $(pageant -X)
108 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 -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 --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 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 --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 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 --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
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 -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 The private key files must be in PuTTY's .ppk file format.
164 -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 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 --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 Each key-identifier can be any of the following:
179 • The name of a file containing the key, either the whole
181 key (again in .ppk format) or just its public half.
182 • The key's comment string, as shown by pageant -l.
184 • Enough of one of the key's fingerprint formats to be
186 unique among keys currently loaded into the agent.
187 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 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 `file:'
198 to indicate that it is a filename
199 `comment:'
201 to indicate that it is a comment string
202 `fp:' to indicate that it is a fingerprint; any fingerprint
204 format will be matched
205 `sha256:' or `md5:'
207 to indicate that it is a fingerprint of a specific format
208 --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 -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 -D Delete all keys from the agent's memory, leaving it completely
220 empty.
221 -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 (Holding encrypted keys is a Pageant extension, so this option
230 and -R are unlikely to work with other agents.)
231 -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 --test-sign key-identifier
237 --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 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 flags is a number representing a combination of flag bits de‐
249 fined by the SSH agent protocol.
250
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 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
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 eval $(pageant -X -v 2>~/.pageant.log)
272 and expect a list of all signatures requested by agent clients
274 to build up in that log file.
275 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 -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 --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 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 --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 The --encrypted option makes no difference for key files which
308 do not have a passphrase.
309 (Storing keys in encrypted form is a Pageant extension; other
311 agent implementations are unlikely to support it.)
312 -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 --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 --help Print a brief summary of command-line options and terminate.
326 --version, -V
328 Print the version of Pageant.
329 -- Cause all subsequent arguments to be treated as key file names,
331 even if they look like options.
332PuTTY tool suite 2015‐05‐19 pageant(1)