1.\" $OpenBSD: ssh-add.1,v 1.89 2026/03/05 05:44:15 djm Exp $ 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, 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 66adds private key identities to the authentication agent, 67.Xr ssh-agent 1 . 68When 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 73and 74.Pa ~/.ssh/id_ed25519_sk . 75After loading a private key, 76.Nm 77will try to load corresponding certificate information from the 78filename obtained by appending 79.Pa -cert.pub 80to the name of the private key file. 81Alternative file names can be given on the command line. 82.Pp 83If any file requires a passphrase, 84.Nm 85asks for the passphrase from the user. 86The passphrase is read from the user's tty. 87.Nm 88retries the last passphrase if multiple identity files are given. 89.Pp 90The authentication agent must be running and the 91.Ev SSH_AUTH_SOCK 92environment variable must contain the name of its socket for 93.Nm 94to work. 95.Pp 96The options are as follows: 97.Bl -tag -width Ds 98.It Fl C 99When loading keys into or deleting keys from the agent, process 100certificates only and skip plain keys. 101.It Fl c 102Indicates that added identities should be subject to confirmation before 103being used for authentication. 104Confirmation is performed by 105.Xr ssh-askpass 1 . 106Successful confirmation is signaled by a zero exit status from 107.Xr ssh-askpass 1 , 108rather than text entered into the requester. 109.It Fl D 110Deletes all identities from the agent. 111.It Fl d 112Instead of adding identities, removes identities from the agent. 113If 114.Nm 115has been run without arguments, the keys for the default identities and 116their corresponding certificates will be removed. 117Otherwise, the argument list will be interpreted as a list of paths to 118public key files to specify keys and certificates to be removed from the agent. 119If no public key is found at a given path, 120.Nm 121will append 122.Pa .pub 123and retry. 124If the argument list consists of 125.Dq - 126then 127.Nm 128will read public keys to be removed from standard input. 129.It Fl E Ar fingerprint_hash 130Specifies the hash algorithm used when displaying key fingerprints. 131Valid options are: 132.Dq md5 133and 134.Dq sha256 . 135The default is 136.Dq sha256 . 137.It Fl e Ar pkcs11 138Remove keys provided by the PKCS#11 shared library 139.Ar pkcs11 . 140.It Fl H Ar hostkey_file 141Specifies a known hosts file to look up hostkeys when using 142destination-constrained keys via the 143.Fl h 144flag. 145This option may be specified multiple times to allow multiple files to be 146searched. 147If no files are specified, 148.Nm 149will use the default 150.Xr ssh_config 5 151known hosts files: 152.Pa ~/.ssh/known_hosts , 153.Pa ~/.ssh/known_hosts2 , 154.Pa /etc/ssh/ssh_known_hosts , 155and 156.Pa /etc/ssh/ssh_known_hosts2 . 157.It Fl h Ar destination_constraint 158When adding keys, constrain them to be usable only through specific hosts or to 159specific destinations. 160.Pp 161Destination constraints of the form 162.Sq [user@]dest-hostname 163permit use of the key only from the origin host (the one running 164.Xr ssh-agent 1 ) 165to the listed destination host, with optional user name. 166.Pp 167Constraints of the form 168.Sq src-hostname>[user@]dst-hostname 169allow a key available on a forwarded 170.Xr ssh-agent 1 171to be used through a particular host (as specified by 172.Sq src-hostname ) 173to authenticate to a further host, 174specified by 175.Sq dst-hostname . 176.Pp 177Multiple destination constraints may be added when loading keys. 178When attempting authentication with a key that has destination constraints, 179the whole connection path, including 180.Xr ssh-agent 1 181forwarding, is tested against those constraints and each 182hop must be permitted for the attempt to succeed. 183For example, if key is forwarded to a remote host, 184.Sq host-b , 185and is attempting authentication to another host, 186.Sq host-c , 187then the operation will be successful only if 188.Sq host-b 189was permitted from the origin host and the subsequent 190.Sq host-b>host-c 191hop is also permitted by destination constraints. 192.Pp 193Hosts are identified by their host keys, and are looked up from known hosts 194files by 195.Nm . 196Wildcards patterns may be used for hostnames and certificate host 197keys are supported. 198By default, keys added by 199.Nm 200are not destination constrained. 201.Pp 202Destination constraints were added in OpenSSH release 8.9. 203Support in both the remote SSH client and server is required when using 204destination-constrained keys over a forwarded 205.Xr ssh-agent 1 206channel. 207.Pp 208It is also important to note that destination constraints can only be 209enforced by 210.Xr ssh-agent 1 211when a key is used, or when it is forwarded by a 212.Sy cooperating 213.Xr ssh 1 . 214Specifically, it does not prevent an attacker with access to a remote 215.Ev SSH_AUTH_SOCK 216from forwarding it again and using it on a different host (but only to 217a permitted destination). 218.It Fl K 219Load resident keys from a FIDO authenticator. 220.It Fl k 221When loading keys into or deleting keys from the agent, process plain private 222keys only and skip certificates. 223.It Fl L 224Lists public key parameters of all identities currently represented 225by the agent. 226.It Fl l 227Lists fingerprints of all identities currently represented by the agent. 228.It Fl N 229When adding certificates, by default 230.Nm 231will request that the agent automatically delete the certificate shortly 232after the certificate's expiry date. 233This flag suppresses this behaviour and does not specify a lifetime for 234certificates added to an agent. 235.It Fl Q 236Query the agent for the list of protocol extensions it supports. 237Note: not all agents support this query. 238.It Fl q 239Be quiet after a successful operation. 240.It Fl S Ar provider 241Specifies a path to a library that will be used when adding 242FIDO authenticator-hosted keys, overriding the default of using the 243internal USB HID support. 244.It Fl s Ar pkcs11 245Add keys provided by the PKCS#11 shared library 246.Ar pkcs11 . 247Certificate files may optionally be listed as command-line arguments. 248If these are present, then they will be loaded into the agent using any 249corresponding private keys loaded from the PKCS#11 token. 250.It Fl T Ar pubkey ... 251Tests whether the private keys that correspond to the specified 252.Ar pubkey 253files are usable by performing sign and verify operations on each. 254.It Fl t Ar life 255Set a maximum lifetime when adding identities to an agent. 256The lifetime may be specified in seconds or in a time format 257specified in 258.Xr sshd_config 5 . 259.It Fl v 260Verbose mode. 261Causes 262.Nm 263to print debugging messages about its progress. 264This is helpful in debugging problems. 265Multiple 266.Fl v 267options increase the verbosity. 268The maximum is 3. 269.It Fl X 270Unlock the agent. 271.It Fl x 272Lock 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" 277If 278.Nm 279needs a passphrase, it will read the passphrase from the current 280terminal if it was run from a terminal. 281If 282.Nm 283does not have a terminal associated with it but 284.Ev DISPLAY 285and 286.Ev SSH_ASKPASS 287are set, it will execute the program specified by 288.Ev SSH_ASKPASS 289(by default 290.Dq ssh-askpass ) 291and open an X11 window to read the passphrase. 292This is particularly useful when calling 293.Nm 294from a 295.Pa .xsession 296or related script. 297.Pp 298.Ev SSH_ASKPASS_REQUIRE 299allows further control over the use of an askpass program. 300If this variable is set to 301.Dq never 302then 303.Nm 304will never attempt to use one. 305If it is set to 306.Dq prefer , 307then 308.Nm 309will prefer to use the askpass program instead of the TTY when requesting 310passwords. 311Finally, if the variable is set to 312.Dq force , 313then the askpass program will be used for all passphrase input regardless 314of whether 315.Ev DISPLAY 316is set. 317.It Ev SSH_AUTH_SOCK 318Identifies the path of a 319.Ux Ns -domain 320socket used to communicate with the agent. 321.It Ev SSH_SK_PROVIDER 322Specifies a path to a library that will be used when loading any 323FIDO authenticator-hosted keys, overriding the default of using 324the 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 333Contains the ECDSA, authenticator-hosted ECDSA, Ed25519, 334authenticator-hosted Ed25519 or RSA authentication identity of the user. 335.El 336.Pp 337Identity files should not be readable by anyone but the user. 338Note that 339.Nm 340ignores identity files if they are accessible by others. 341.Sh EXIT STATUS 342Exit status is 0 on success, 1 if the specified command fails, 343and 2 if 344.Nm 345is 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 353OpenSSH is a derivative of the original and free 354ssh 1.2.12 release by Tatu Ylonen. 355Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 356Theo de Raadt and Dug Song 357removed many bugs, re-added newer features and 358created OpenSSH. 359Markus Friedl contributed the support for SSH 360protocol versions 1.5 and 2.0. 361