| 1 |
.\" $OpenBSD: ssh-agent.1,v 1.86 2025/10/04 21:41:35 naddy Exp $ |
| 2 |
.\" |
| 3 |
.\" Author: Tatu Ylonen <[email protected]> |
| 4 |
.\" Copyright (c) 1995 Tatu Ylonen <[email protected]>, Espoo, Finland |
| 5 |
.\" All rights reserved |
| 6 |
.\" |
| 7 |
.\" As far as I am concerned, the code I have written for this software |
| 8 |
.\" can be used freely for any purpose. Any derived versions of this |
| 9 |
.\" software must be clearly marked as such, and if the derived work is |
| 10 |
.\" incompatible with the protocol description in the RFC file, it must be |
| 11 |
.\" called by a name other than "ssh" or "Secure Shell". |
| 12 |
.\" |
| 13 |
.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. |
| 14 |
.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. |
| 15 |
.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. |
| 16 |
.\" |
| 17 |
.\" Redistribution and use in source and binary forms, with or without |
| 18 |
.\" modification, are permitted provided that the following conditions |
| 19 |
.\" are met: |
| 20 |
.\" 1. Redistributions of source code must retain the above copyright |
| 21 |
.\" notice, this list of conditions and the following disclaimer. |
| 22 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
| 23 |
.\" notice, this list of conditions and the following disclaimer in the |
| 24 |
.\" documentation and/or other materials provided with the distribution. |
| 25 |
.\" |
| 26 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
| 27 |
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| 28 |
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| 29 |
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 30 |
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| 31 |
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 32 |
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 33 |
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 34 |
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
| 35 |
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 36 |
.\" |
| 37 |
.Dd $Mdocdate: October 4 2025 $ |
| 38 |
.Dt SSH-AGENT 1 |
| 39 |
.Os |
| 40 |
.Sh NAME |
| 41 |
.Nm ssh-agent |
| 42 |
.Nd OpenSSH authentication agent |
| 43 |
.Sh SYNOPSIS |
| 44 |
.Nm ssh-agent |
| 45 |
.Op Fl c | s |
| 46 |
.Op Fl \&DdTU |
| 47 |
.Op Fl a Ar bind_address |
| 48 |
.Op Fl E Ar fingerprint_hash |
| 49 |
.Op Fl O Ar option |
| 50 |
.Op Fl P Ar allowed_providers |
| 51 |
.Op Fl t Ar life |
| 52 |
.Nm ssh-agent |
| 53 |
.Op Fl TU |
| 54 |
.Op Fl a Ar bind_address |
| 55 |
.Op Fl E Ar fingerprint_hash |
| 56 |
.Op Fl O Ar option |
| 57 |
.Op Fl P Ar allowed_providers |
| 58 |
.Op Fl t Ar life |
| 59 |
.Ar command Op Ar arg ... |
| 60 |
.Nm ssh-agent |
| 61 |
.Op Fl c | s |
| 62 |
.Fl k |
| 63 |
.Nm ssh-agent |
| 64 |
.Fl u |
| 65 |
.Sh DESCRIPTION |
| 66 |
.Nm |
| 67 |
is a program to hold private keys used for public key authentication. |
| 68 |
Through use of environment variables the agent can be located |
| 69 |
and automatically used for authentication when logging in to other |
| 70 |
machines using |
| 71 |
.Xr ssh 1 . |
| 72 |
.Pp |
| 73 |
The options are as follows: |
| 74 |
.Bl -tag -width Ds |
| 75 |
.It Fl a Ar bind_address |
| 76 |
Bind the agent to the |
| 77 |
.Ux Ns -domain |
| 78 |
socket |
| 79 |
.Ar bind_address . |
| 80 |
The default is to create a socket at a random path matching |
| 81 |
.Pa $HOME/.ssh/agent/s.* . |
| 82 |
.It Fl c |
| 83 |
Generate C-shell commands on standard output. |
| 84 |
This is the default if |
| 85 |
.Ev SHELL |
| 86 |
looks like it's a csh style of shell. |
| 87 |
.It Fl D |
| 88 |
Foreground mode. |
| 89 |
When this option is specified, |
| 90 |
.Nm |
| 91 |
will not fork. |
| 92 |
.It Fl d |
| 93 |
Debug mode. |
| 94 |
When this option is specified, |
| 95 |
.Nm |
| 96 |
will not fork and will write debug information to standard error. |
| 97 |
.It Fl E Ar fingerprint_hash |
| 98 |
Specifies the hash algorithm used when displaying key fingerprints. |
| 99 |
Valid options are: |
| 100 |
.Dq md5 |
| 101 |
and |
| 102 |
.Dq sha256 . |
| 103 |
The default is |
| 104 |
.Dq sha256 . |
| 105 |
.It Fl k |
| 106 |
Kill the current agent (given by the |
| 107 |
.Ev SSH_AGENT_PID |
| 108 |
environment variable). |
| 109 |
.It Fl O Ar option |
| 110 |
Specify an option when starting |
| 111 |
.Nm . |
| 112 |
The supported options are: |
| 113 |
.Cm allow-remote-pkcs11 , |
| 114 |
.Cm no-restrict-websafe |
| 115 |
and |
| 116 |
.Cm websafe-allow . |
| 117 |
.Pp |
| 118 |
The |
| 119 |
.Cm allow-remote-pkcs11 |
| 120 |
option allows clients of a forwarded |
| 121 |
.Nm |
| 122 |
to load PKCS#11 or FIDO provider libraries. |
| 123 |
By default only local clients may perform this operation. |
| 124 |
Note that signalling that an |
| 125 |
.Nm |
| 126 |
client is remote is performed by |
| 127 |
.Xr ssh 1 , |
| 128 |
and use of other tools to forward access to the agent socket may circumvent |
| 129 |
this restriction. |
| 130 |
.Pp |
| 131 |
The |
| 132 |
.Cm no-restrict-websafe |
| 133 |
option instructs |
| 134 |
.Nm |
| 135 |
to permit signatures using FIDO keys that might be web authentication |
| 136 |
requests. |
| 137 |
By default, |
| 138 |
.Nm |
| 139 |
refuses signature requests for FIDO keys where the key application string |
| 140 |
does not start with |
| 141 |
.Dq ssh: |
| 142 |
and when the data to be signed does not appear to be an |
| 143 |
.Xr ssh 1 |
| 144 |
user authentication request or an |
| 145 |
.Xr ssh-keygen 1 |
| 146 |
signature. |
| 147 |
The default behaviour prevents forwarded access to a FIDO key from also |
| 148 |
implicitly forwarding the ability to authenticate to websites. |
| 149 |
.Pp |
| 150 |
Alternately the |
| 151 |
.Cm websafe-allow |
| 152 |
option allows specifying a pattern-list of key application strings to |
| 153 |
replace the default application allow-list, for example: |
| 154 |
.Dq websafe-allow=ssh:*,example.org,*.example.com |
| 155 |
.Pp |
| 156 |
See PATTERNS in |
| 157 |
.Xr ssh_config 5 |
| 158 |
for a description of pattern-list syntax. |
| 159 |
.It Fl P Ar allowed_providers |
| 160 |
Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO |
| 161 |
authenticator middleware shared libraries that may be used with the |
| 162 |
.Fl S |
| 163 |
or |
| 164 |
.Fl s |
| 165 |
options to |
| 166 |
.Xr ssh-add 1 . |
| 167 |
Libraries that do not match the pattern list will be refused. |
| 168 |
The default list is |
| 169 |
.Dq /usr/lib*/*,/usr/local/lib*/* . |
| 170 |
.Pp |
| 171 |
See PATTERNS in |
| 172 |
.Xr ssh_config 5 |
| 173 |
for a description of pattern-list syntax. |
| 174 |
.It Fl s |
| 175 |
Generate Bourne shell commands on standard output. |
| 176 |
This is the default if |
| 177 |
.Ev SHELL |
| 178 |
does not look like it's a csh style of shell. |
| 179 |
.It Fl T |
| 180 |
Bind the agent socket in a randomised subdirectory of the form |
| 181 |
.Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt , |
| 182 |
instead of the default behaviour of using a randomised name matching |
| 183 |
.Pa $HOME/.ssh/agent/s.* . |
| 184 |
.It Fl t Ar life |
| 185 |
Set a default value for the maximum lifetime of identities added to the agent. |
| 186 |
The lifetime may be specified in seconds or in a time format specified in |
| 187 |
.Xr sshd_config 5 . |
| 188 |
A lifetime specified for an identity with |
| 189 |
.Xr ssh-add 1 |
| 190 |
overrides this value. |
| 191 |
Without this option the default maximum lifetime is forever. |
| 192 |
.It Fl U |
| 193 |
Instructs |
| 194 |
.Nm |
| 195 |
not to clean up stale agent sockets under |
| 196 |
.Pa $HOME/.ssh/agent/ . |
| 197 |
.It Fl u |
| 198 |
Instructs |
| 199 |
.Nm |
| 200 |
to only clean up stale agent sockets under |
| 201 |
.Pa $HOME/.ssh/agent/ |
| 202 |
and then exit immediately. |
| 203 |
If this option is given twice, |
| 204 |
.Nm |
| 205 |
will delete stale agent sockets regardless of the host name that created them. |
| 206 |
.It Ar command Op Ar arg ... |
| 207 |
If a command (and optional arguments) is given, |
| 208 |
this is executed as a subprocess of the agent. |
| 209 |
The agent exits automatically when the command given on the command |
| 210 |
line terminates. |
| 211 |
.El |
| 212 |
.Pp |
| 213 |
There are three main ways to get an agent set up. |
| 214 |
The first is at the start of an X session, |
| 215 |
where all other windows or programs are started as children of the |
| 216 |
.Nm |
| 217 |
program. |
| 218 |
The agent starts a command under which its environment |
| 219 |
variables are exported, for example |
| 220 |
.Cm ssh-agent xterm & . |
| 221 |
When the command terminates, so does the agent. |
| 222 |
.Pp |
| 223 |
The second method is used for a login session. |
| 224 |
When |
| 225 |
.Nm |
| 226 |
is started, |
| 227 |
it prints the shell commands required to set its environment variables, |
| 228 |
which in turn can be evaluated in the calling shell, for example |
| 229 |
.Cm eval `ssh-agent -s` . |
| 230 |
.Pp |
| 231 |
In both of these cases, |
| 232 |
.Xr ssh 1 |
| 233 |
looks at these environment variables |
| 234 |
and uses them to establish a connection to the agent. |
| 235 |
.Pp |
| 236 |
The third way to run |
| 237 |
.Nm |
| 238 |
is via socket activation from a supervising process, such as systemd. |
| 239 |
In this mode, the supervising process creates the listening socket and |
| 240 |
is responsible for starting |
| 241 |
.Nm |
| 242 |
as needed, and also for communicating the location of the socket listener |
| 243 |
to other programs in the user's session. |
| 244 |
Socket activation is used when |
| 245 |
.Nm |
| 246 |
is started with either of the |
| 247 |
.Fl d |
| 248 |
or |
| 249 |
.Fl D |
| 250 |
flags, no socket listening address specified by the |
| 251 |
.Fl a |
| 252 |
flag, and both the |
| 253 |
.Ev LISTEN_FDS |
| 254 |
and |
| 255 |
.Ev LISTEN_PID |
| 256 |
environment variables correctly supplied by the supervising process. |
| 257 |
.Pp |
| 258 |
The agent initially does not have any private keys. |
| 259 |
Keys are added using |
| 260 |
.Xr ssh-add 1 |
| 261 |
or by |
| 262 |
.Xr ssh 1 |
| 263 |
when |
| 264 |
.Cm AddKeysToAgent |
| 265 |
is set in |
| 266 |
.Xr ssh_config 5 . |
| 267 |
Multiple identities may be stored in |
| 268 |
.Nm |
| 269 |
concurrently and |
| 270 |
.Xr ssh 1 |
| 271 |
will automatically use them if present. |
| 272 |
.Xr ssh-add 1 |
| 273 |
is also used to remove keys from |
| 274 |
.Nm |
| 275 |
and to query the keys that are held in one. |
| 276 |
.Pp |
| 277 |
Connections to |
| 278 |
.Nm |
| 279 |
may be forwarded from further remote hosts using the |
| 280 |
.Fl A |
| 281 |
option to |
| 282 |
.Xr ssh 1 |
| 283 |
(but see the caveats documented therein), |
| 284 |
avoiding the need for authentication data to be stored on other machines. |
| 285 |
Authentication passphrases and private keys never go over the network: |
| 286 |
the connection to the agent is forwarded over SSH remote connections |
| 287 |
and the result is returned to the requester, |
| 288 |
allowing the user access to their identities anywhere in the network |
| 289 |
in a secure fashion. |
| 290 |
.Pp |
| 291 |
.Nm |
| 292 |
will delete all keys it has loaded upon receiving |
| 293 |
.Dv SIGUSR1 . |
| 294 |
.Sh ENVIRONMENT |
| 295 |
.Bl -tag -width "SSH_AGENT_PID" |
| 296 |
.It Ev SSH_AGENT_PID |
| 297 |
When |
| 298 |
.Nm |
| 299 |
starts, it stores the name of the agent's process ID (PID) in this variable. |
| 300 |
.It Ev SSH_AUTH_SOCK |
| 301 |
When |
| 302 |
.Nm |
| 303 |
starts, it creates a |
| 304 |
.Ux Ns -domain |
| 305 |
socket and stores its pathname in this variable. |
| 306 |
It is accessible only to the current user, |
| 307 |
but is easily abused by root or another instance of the same user. |
| 308 |
.El |
| 309 |
.Pp |
| 310 |
In Debian, |
| 311 |
.Nm |
| 312 |
is installed with the set-group-id bit set, to prevent |
| 313 |
.Xr ptrace 2 |
| 314 |
attacks retrieving private key material. |
| 315 |
This has the side-effect of causing the run-time linker to remove certain |
| 316 |
environment variables which might have security implications for set-id |
| 317 |
programs, including |
| 318 |
.Ev LD_PRELOAD , |
| 319 |
.Ev LD_LIBRARY_PATH , |
| 320 |
and |
| 321 |
.Ev TMPDIR . |
| 322 |
If you need to set any of these environment variables, you will need to do |
| 323 |
so in the program executed by ssh-agent. |
| 324 |
.Sh FILES |
| 325 |
.Bl -tag -width Ds |
| 326 |
.It Pa $HOME/.ssh/agent/s.* |
| 327 |
.Ux Ns -domain |
| 328 |
sockets used to contain the connection to the authentication agent. |
| 329 |
These sockets should only be readable by the owner. |
| 330 |
The sockets should get automatically removed when the agent exits. |
| 331 |
.El |
| 332 |
.Sh SEE ALSO |
| 333 |
.Xr ssh 1 , |
| 334 |
.Xr ssh-add 1 , |
| 335 |
.Xr ssh-keygen 1 , |
| 336 |
.Xr ssh_config 5 , |
| 337 |
.Xr sshd 8 |
| 338 |
.Sh AUTHORS |
| 339 |
.An -nosplit |
| 340 |
OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
| 341 |
.An Tatu Ylonen . |
| 342 |
.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt |
| 343 |
and |
| 344 |
.An Dug Song |
| 345 |
removed many bugs, re-added newer features and created OpenSSH. |
| 346 |
.An Markus Friedl |
| 347 |
contributed the support for SSH protocol versions 1.5 and 2.0. |