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 `sha256-cert:' or `md5-cert:'
210 to indicate that it is a fingerprint of a specific for‐
211 mat, and specifically matches the fingerprint of the pub‐
212 lic key including a certificate if any
213 --public-openssh key-identifiers, -L key-identifiers
215 Print the public half of each specified key, in the one-line
216 format used by OpenSSH, suitable for putting in .ssh/autho‐
217 rized_keys files.
218 -d key-identifiers
220 Delete each specified key from the agent's memory, so that the
221 agent will no longer serve it to clients unless it is loaded in
222 again using pageant -a.
223 -D Delete all keys from the agent's memory, leaving it completely
225 empty.
226 -r key-identifiers
228 `Re-encrypt' each specified key in the agent's memory - that is,
229 forget any cleartext version, so that the user will be prompted
230 for a passphrase again next time the key is used. (For this to
231 be possible, the key must previously have been added with the
232 --encrypted option.)
233 (Holding encrypted keys is a Pageant extension, so this option
235 and -R are unlikely to work with other agents.)
236 -R `Re-encrypt' all possible keys in the agent's memory. (This may
238 leave some keys in cleartext, if they were not previously added
239 with the --encrypted option.)
240 --test-sign key-identifier
242 --test-sign-with-flags=flags key-identifier
245 Sign arbitrary data with the given key. This mode is only likely
246 to be useful when testing pageant itself.
247 The data to sign is taken from standard input, signed by the
249 agent with the key identified by key-identifier, and the result‐
250 ing signature emitted on standard output (as a binary blob in
251 the format defined by the SSH specifications).
252 flags is a number representing a combination of flag bits de‐
254 fined by the SSH agent protocol.
255
257 --askpass prompt
258 With this option, pageant acts as an ssh-askpass(1) replacement,
259 rather than performing any SSH agent functionality. This may be
260 useful if you prefer Pageant's GUI prompt style, which minimises
261 information leakage about your passphrase length in its visual
262 feedback, compared to other ssh-askpass(1) implementations.
263 pageant --askpass implements the standard ssh-askpass(1) inter‐
265 face: it can be passed a prompt to display (as a single argu‐
266 ment) and, if successful, prints the passphrase on standard out‐
267 put and returns a zero exit status. Typically you would use the
268 environment variable SSH_ASKPASS to tell other programs to use
269 pageant in this way.
270
272 -v Verbose mode. When Pageant runs in agent mode, this option
273 causes it to log all agent activity to its standard error. For
274 example, you might run
275 eval $(pageant -X -v 2>~/.pageant.log)
277 and expect a list of all signatures requested by agent clients
279 to build up in that log file.
280 The log information is the same as that produced by the --debug
282 lifetime option, but --debug sends it to standard output (since
283 that is the main point of debugging mode) whereas -v in all
284 other lifetime modes sends the same log data to standard error
285 (being a by-product of the program's main purpose). Using -v in
286 --debug mode has no effect: the log still goes to standard out‐
287 put.
288 -s, -c Force Pageant to output its environment setup commands in the
290 style of POSIX / Bourne shells (-s) or C shells (-c) respec‐
291 tively. If neither option is given, Pageant will guess based on
292 whether the environment variable SHELL has a value ending in
293 `csh'.
294 --symlink fixed-path
296 When operating in agent mode, as well as creating a uniquely
297 named listening socket, pageant will also create (or update) a
298 symbolic link at fixed-path pointing to that socket.
299 This allows access to an agent instance by setting the
301 SSH_AUTH_SOCK environment variable to fixed-path, rather than
302 having to use the value invented by pageant when it starts. It's
303 mainly expected to be useful for debugging.
304 --encrypted, --no-decrypt
306 When adding keys to the agent (at startup or later), keep them
307 in encrypted form until the first attempt to use them; the user
308 will be prompted for a passphrase then. Once decrypted, a key
309 that was added in this way can be `re-encrypted' with the -r or
310 -R client options.
311 The --encrypted option makes no difference for key files which
313 do not have a passphrase.
314 (Storing keys in encrypted form is a Pageant extension; other
316 agent implementations are unlikely to support it.)
317 -E fingerprint-type, --fptype fingerprint-type
319 Specify the fingerprint format to print. Only applicable when
320 listing fingerprints with -l. The available formats are sha256
321 (the default) and md5.
322 --gui-prompt, --tty-prompt
324 Force Pageant to prompt for key passphrases with a particular
325 method (GUI or terminal) rather than trying to guess the most
326 appropriate method as described above. (These options are rele‐
327 vant whenever a key file is specified to pageant that needs im‐
328 mediate decryption, and in --askpass mode.)
329 --help Print a brief summary of command-line options and terminate.
331 --version, -V
333 Print the version of Pageant.
334 -- Cause all subsequent arguments to be treated as key file names,
336 even if they look like options.
337PuTTY tool suite 2015‐05‐19 pageant(1)