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