| 1 |
.\" $OpenBSD: ssh-add.1,v 1.89 2026/03/05 05:44:15 djm 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 |
.\" |
| 14 |
.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. |
| 15 |
.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. |
| 16 |
.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. |
| 17 |
.\" |
| 18 |
.\" Redistribution and use in source and binary forms, with or without |
| 19 |
.\" modification, are permitted provided that the following conditions |
| 20 |
.\" are met: |
| 21 |
.\" 1. Redistributions of source code must retain the above copyright |
| 22 |
.\" notice, this list of conditions and the following disclaimer. |
| 23 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
| 24 |
.\" notice, this list of conditions and the following disclaimer in the |
| 25 |
.\" documentation and/or other materials provided with the distribution. |
| 26 |
.\" |
| 27 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
| 28 |
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| 29 |
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| 30 |
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 31 |
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| 32 |
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 33 |
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 34 |
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 35 |
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
| 36 |
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 37 |
.\" |
| 38 |
.Dd $Mdocdate: March 5 2026 $ |
| 39 |
.Dt SSH-ADD 1 |
| 40 |
.Os |
| 41 |
.Sh NAME |
| 42 |
.Nm ssh-add |
| 43 |
.Nd adds private key identities to the OpenSSH authentication agent |
| 44 |
.Sh SYNOPSIS |
| 45 |
.Nm ssh-add |
| 46 |
.Op Fl CcDdKkLlNqvXx |
| 47 |
.Op Fl E Ar fingerprint_hash |
| 48 |
.Op Fl H Ar hostkey_file |
| 49 |
.Op Fl h Ar destination_constraint |
| 50 |
.Op Fl S Ar provider |
| 51 |
.Op Fl t Ar life |
| 52 |
.Op Ar |
| 53 |
.Nm ssh-add |
| 54 |
.Fl s Ar pkcs11 |
| 55 |
.Op Fl Cv |
| 56 |
.Op Ar certificate ... |
| 57 |
.Nm ssh-add |
| 58 |
.Fl e Ar pkcs11 |
| 59 |
.Nm ssh-add |
| 60 |
.Fl T |
| 61 |
.Ar pubkey ... |
| 62 |
.Nm ssh-add |
| 63 |
.Fl Q |
| 64 |
.Sh DESCRIPTION |
| 65 |
.Nm |
| 66 |
adds private key identities to the authentication agent, |
| 67 |
.Xr ssh-agent 1 . |
| 68 |
When run without arguments, it adds the files |
| 69 |
.Pa ~/.ssh/id_rsa , |
| 70 |
.Pa ~/.ssh/id_ecdsa , |
| 71 |
.Pa ~/.ssh/id_ecdsa_sk , |
| 72 |
.Pa ~/.ssh/id_ed25519 |
| 73 |
and |
| 74 |
.Pa ~/.ssh/id_ed25519_sk . |
| 75 |
After loading a private key, |
| 76 |
.Nm |
| 77 |
will try to load corresponding certificate information from the |
| 78 |
filename obtained by appending |
| 79 |
.Pa -cert.pub |
| 80 |
to the name of the private key file. |
| 81 |
Alternative file names can be given on the command line. |
| 82 |
.Pp |
| 83 |
If any file requires a passphrase, |
| 84 |
.Nm |
| 85 |
asks for the passphrase from the user. |
| 86 |
The passphrase is read from the user's tty. |
| 87 |
.Nm |
| 88 |
retries the last passphrase if multiple identity files are given. |
| 89 |
.Pp |
| 90 |
The authentication agent must be running and the |
| 91 |
.Ev SSH_AUTH_SOCK |
| 92 |
environment variable must contain the name of its socket for |
| 93 |
.Nm |
| 94 |
to work. |
| 95 |
.Pp |
| 96 |
The options are as follows: |
| 97 |
.Bl -tag -width Ds |
| 98 |
.It Fl C |
| 99 |
When loading keys into or deleting keys from the agent, process |
| 100 |
certificates only and skip plain keys. |
| 101 |
.It Fl c |
| 102 |
Indicates that added identities should be subject to confirmation before |
| 103 |
being used for authentication. |
| 104 |
Confirmation is performed by |
| 105 |
.Xr ssh-askpass 1 . |
| 106 |
Successful confirmation is signaled by a zero exit status from |
| 107 |
.Xr ssh-askpass 1 , |
| 108 |
rather than text entered into the requester. |
| 109 |
.It Fl D |
| 110 |
Deletes all identities from the agent. |
| 111 |
.It Fl d |
| 112 |
Instead of adding identities, removes identities from the agent. |
| 113 |
If |
| 114 |
.Nm |
| 115 |
has been run without arguments, the keys for the default identities and |
| 116 |
their corresponding certificates will be removed. |
| 117 |
Otherwise, the argument list will be interpreted as a list of paths to |
| 118 |
public key files to specify keys and certificates to be removed from the agent. |
| 119 |
If no public key is found at a given path, |
| 120 |
.Nm |
| 121 |
will append |
| 122 |
.Pa .pub |
| 123 |
and retry. |
| 124 |
If the argument list consists of |
| 125 |
.Dq - |
| 126 |
then |
| 127 |
.Nm |
| 128 |
will read public keys to be removed from standard input. |
| 129 |
.It Fl E Ar fingerprint_hash |
| 130 |
Specifies the hash algorithm used when displaying key fingerprints. |
| 131 |
Valid options are: |
| 132 |
.Dq md5 |
| 133 |
and |
| 134 |
.Dq sha256 . |
| 135 |
The default is |
| 136 |
.Dq sha256 . |
| 137 |
.It Fl e Ar pkcs11 |
| 138 |
Remove keys provided by the PKCS#11 shared library |
| 139 |
.Ar pkcs11 . |
| 140 |
.It Fl H Ar hostkey_file |
| 141 |
Specifies a known hosts file to look up hostkeys when using |
| 142 |
destination-constrained keys via the |
| 143 |
.Fl h |
| 144 |
flag. |
| 145 |
This option may be specified multiple times to allow multiple files to be |
| 146 |
searched. |
| 147 |
If no files are specified, |
| 148 |
.Nm |
| 149 |
will use the default |
| 150 |
.Xr ssh_config 5 |
| 151 |
known hosts files: |
| 152 |
.Pa ~/.ssh/known_hosts , |
| 153 |
.Pa ~/.ssh/known_hosts2 , |
| 154 |
.Pa /etc/ssh/ssh_known_hosts , |
| 155 |
and |
| 156 |
.Pa /etc/ssh/ssh_known_hosts2 . |
| 157 |
.It Fl h Ar destination_constraint |
| 158 |
When adding keys, constrain them to be usable only through specific hosts or to |
| 159 |
specific destinations. |
| 160 |
.Pp |
| 161 |
Destination constraints of the form |
| 162 |
.Sq [user@]dest-hostname |
| 163 |
permit use of the key only from the origin host (the one running |
| 164 |
.Xr ssh-agent 1 ) |
| 165 |
to the listed destination host, with optional user name. |
| 166 |
.Pp |
| 167 |
Constraints of the form |
| 168 |
.Sq src-hostname>[user@]dst-hostname |
| 169 |
allow a key available on a forwarded |
| 170 |
.Xr ssh-agent 1 |
| 171 |
to be used through a particular host (as specified by |
| 172 |
.Sq src-hostname ) |
| 173 |
to authenticate to a further host, |
| 174 |
specified by |
| 175 |
.Sq dst-hostname . |
| 176 |
.Pp |
| 177 |
Multiple destination constraints may be added when loading keys. |
| 178 |
When attempting authentication with a key that has destination constraints, |
| 179 |
the whole connection path, including |
| 180 |
.Xr ssh-agent 1 |
| 181 |
forwarding, is tested against those constraints and each |
| 182 |
hop must be permitted for the attempt to succeed. |
| 183 |
For example, if key is forwarded to a remote host, |
| 184 |
.Sq host-b , |
| 185 |
and is attempting authentication to another host, |
| 186 |
.Sq host-c , |
| 187 |
then the operation will be successful only if |
| 188 |
.Sq host-b |
| 189 |
was permitted from the origin host and the subsequent |
| 190 |
.Sq host-b>host-c |
| 191 |
hop is also permitted by destination constraints. |
| 192 |
.Pp |
| 193 |
Hosts are identified by their host keys, and are looked up from known hosts |
| 194 |
files by |
| 195 |
.Nm . |
| 196 |
Wildcards patterns may be used for hostnames and certificate host |
| 197 |
keys are supported. |
| 198 |
By default, keys added by |
| 199 |
.Nm |
| 200 |
are not destination constrained. |
| 201 |
.Pp |
| 202 |
Destination constraints were added in OpenSSH release 8.9. |
| 203 |
Support in both the remote SSH client and server is required when using |
| 204 |
destination-constrained keys over a forwarded |
| 205 |
.Xr ssh-agent 1 |
| 206 |
channel. |
| 207 |
.Pp |
| 208 |
It is also important to note that destination constraints can only be |
| 209 |
enforced by |
| 210 |
.Xr ssh-agent 1 |
| 211 |
when a key is used, or when it is forwarded by a |
| 212 |
.Sy cooperating |
| 213 |
.Xr ssh 1 . |
| 214 |
Specifically, it does not prevent an attacker with access to a remote |
| 215 |
.Ev SSH_AUTH_SOCK |
| 216 |
from forwarding it again and using it on a different host (but only to |
| 217 |
a permitted destination). |
| 218 |
.It Fl K |
| 219 |
Load resident keys from a FIDO authenticator. |
| 220 |
.It Fl k |
| 221 |
When loading keys into or deleting keys from the agent, process plain private |
| 222 |
keys only and skip certificates. |
| 223 |
.It Fl L |
| 224 |
Lists public key parameters of all identities currently represented |
| 225 |
by the agent. |
| 226 |
.It Fl l |
| 227 |
Lists fingerprints of all identities currently represented by the agent. |
| 228 |
.It Fl N |
| 229 |
When adding certificates, by default |
| 230 |
.Nm |
| 231 |
will request that the agent automatically delete the certificate shortly |
| 232 |
after the certificate's expiry date. |
| 233 |
This flag suppresses this behaviour and does not specify a lifetime for |
| 234 |
certificates added to an agent. |
| 235 |
.It Fl Q |
| 236 |
Query the agent for the list of protocol extensions it supports. |
| 237 |
Note: not all agents support this query. |
| 238 |
.It Fl q |
| 239 |
Be quiet after a successful operation. |
| 240 |
.It Fl S Ar provider |
| 241 |
Specifies a path to a library that will be used when adding |
| 242 |
FIDO authenticator-hosted keys, overriding the default of using the |
| 243 |
internal USB HID support. |
| 244 |
.It Fl s Ar pkcs11 |
| 245 |
Add keys provided by the PKCS#11 shared library |
| 246 |
.Ar pkcs11 . |
| 247 |
Certificate files may optionally be listed as command-line arguments. |
| 248 |
If these are present, then they will be loaded into the agent using any |
| 249 |
corresponding private keys loaded from the PKCS#11 token. |
| 250 |
.It Fl T Ar pubkey ... |
| 251 |
Tests whether the private keys that correspond to the specified |
| 252 |
.Ar pubkey |
| 253 |
files are usable by performing sign and verify operations on each. |
| 254 |
.It Fl t Ar life |
| 255 |
Set a maximum lifetime when adding identities to an agent. |
| 256 |
The lifetime may be specified in seconds or in a time format |
| 257 |
specified in |
| 258 |
.Xr sshd_config 5 . |
| 259 |
.It Fl v |
| 260 |
Verbose mode. |
| 261 |
Causes |
| 262 |
.Nm |
| 263 |
to print debugging messages about its progress. |
| 264 |
This is helpful in debugging problems. |
| 265 |
Multiple |
| 266 |
.Fl v |
| 267 |
options increase the verbosity. |
| 268 |
The maximum is 3. |
| 269 |
.It Fl X |
| 270 |
Unlock the agent. |
| 271 |
.It Fl x |
| 272 |
Lock the agent with a password. |
| 273 |
.El |
| 274 |
.Sh ENVIRONMENT |
| 275 |
.Bl -tag -width Ds |
| 276 |
.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE" |
| 277 |
If |
| 278 |
.Nm |
| 279 |
needs a passphrase, it will read the passphrase from the current |
| 280 |
terminal if it was run from a terminal. |
| 281 |
If |
| 282 |
.Nm |
| 283 |
does not have a terminal associated with it but |
| 284 |
.Ev DISPLAY |
| 285 |
and |
| 286 |
.Ev SSH_ASKPASS |
| 287 |
are set, it will execute the program specified by |
| 288 |
.Ev SSH_ASKPASS |
| 289 |
(by default |
| 290 |
.Dq ssh-askpass ) |
| 291 |
and open an X11 window to read the passphrase. |
| 292 |
This is particularly useful when calling |
| 293 |
.Nm |
| 294 |
from a |
| 295 |
.Pa .xsession |
| 296 |
or related script. |
| 297 |
.Pp |
| 298 |
.Ev SSH_ASKPASS_REQUIRE |
| 299 |
allows further control over the use of an askpass program. |
| 300 |
If this variable is set to |
| 301 |
.Dq never |
| 302 |
then |
| 303 |
.Nm |
| 304 |
will never attempt to use one. |
| 305 |
If it is set to |
| 306 |
.Dq prefer , |
| 307 |
then |
| 308 |
.Nm |
| 309 |
will prefer to use the askpass program instead of the TTY when requesting |
| 310 |
passwords. |
| 311 |
Finally, if the variable is set to |
| 312 |
.Dq force , |
| 313 |
then the askpass program will be used for all passphrase input regardless |
| 314 |
of whether |
| 315 |
.Ev DISPLAY |
| 316 |
is set. |
| 317 |
.It Ev SSH_AUTH_SOCK |
| 318 |
Identifies the path of a |
| 319 |
.Ux Ns -domain |
| 320 |
socket used to communicate with the agent. |
| 321 |
.It Ev SSH_SK_PROVIDER |
| 322 |
Specifies a path to a library that will be used when loading any |
| 323 |
FIDO authenticator-hosted keys, overriding the default of using |
| 324 |
the built-in USB HID support. |
| 325 |
.El |
| 326 |
.Sh FILES |
| 327 |
.Bl -tag -width Ds -compact |
| 328 |
.It Pa ~/.ssh/id_ecdsa |
| 329 |
.It Pa ~/.ssh/id_ecdsa_sk |
| 330 |
.It Pa ~/.ssh/id_ed25519 |
| 331 |
.It Pa ~/.ssh/id_ed25519_sk |
| 332 |
.It Pa ~/.ssh/id_rsa |
| 333 |
Contains the ECDSA, authenticator-hosted ECDSA, Ed25519, |
| 334 |
authenticator-hosted Ed25519 or RSA authentication identity of the user. |
| 335 |
.El |
| 336 |
.Pp |
| 337 |
Identity files should not be readable by anyone but the user. |
| 338 |
Note that |
| 339 |
.Nm |
| 340 |
ignores identity files if they are accessible by others. |
| 341 |
.Sh EXIT STATUS |
| 342 |
Exit status is 0 on success, 1 if the specified command fails, |
| 343 |
and 2 if |
| 344 |
.Nm |
| 345 |
is unable to contact the authentication agent. |
| 346 |
.Sh SEE ALSO |
| 347 |
.Xr ssh 1 , |
| 348 |
.Xr ssh-agent 1 , |
| 349 |
.Xr ssh-askpass 1 , |
| 350 |
.Xr ssh-keygen 1 , |
| 351 |
.Xr sshd 8 |
| 352 |
.Sh AUTHORS |
| 353 |
OpenSSH is a derivative of the original and free |
| 354 |
ssh 1.2.12 release by Tatu Ylonen. |
| 355 |
Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, |
| 356 |
Theo de Raadt and Dug Song |
| 357 |
removed many bugs, re-added newer features and |
| 358 |
created OpenSSH. |
| 359 |
Markus Friedl contributed the support for SSH |
| 360 |
protocol versions 1.5 and 2.0. |