1.\" $NetBSD: ssh-add.1,v 1.19 2024/06/25 16:36:54 christos Exp $ 2.\" $OpenBSD: ssh-add.1,v 1.86 2023/12/19 06:57:34 jmc 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 December 19 2023 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 CcDdKkLlqvXx 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.Op Fl Cv 57.Op Ar certificate ... 58.Nm ssh-add 59.Fl e Ar pkcs11 60.Nm ssh-add 61.Fl T 62.Ar pubkey ... 63.Sh DESCRIPTION 64.Nm 65adds private key identities to the authentication agent, 66.Xr ssh-agent 1 . 67When run without arguments, it adds the files 68.Pa ~/.ssh/id_rsa , 69.Pa ~/.ssh/id_ecdsa , 70.Pa ~/.ssh/id_ecdsa_sk , 71.Pa ~/.ssh/id_ed25519 , 72.Pa ~/.ssh/id_ed25519_sk , 73and 74.Pa ~/.ssh/id_dsa . 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 q 229Be quiet after a successful operation. 230.It Fl S Ar provider 231Specifies a path to a library that will be used when adding 232FIDO authenticator-hosted keys, overriding the default of using the 233internal USB HID support. 234.It Fl s Ar pkcs11 235Add keys provided by the PKCS#11 shared library 236.Ar pkcs11 . 237Certificate files may optionally be listed as command-line arguments. 238If these are present, then they will be loaded into the agent using any 239corresponding private keys loaded from the PKCS#11 token. 240.It Fl T Ar pubkey ... 241Tests whether the private keys that correspond to the specified 242.Ar pubkey 243files are usable by performing sign and verify operations on each. 244.It Fl t Ar life 245Set a maximum lifetime when adding identities to an agent. 246The lifetime may be specified in seconds or in a time format 247specified in 248.Xr sshd_config 5 . 249.It Fl v 250Verbose mode. 251Causes 252.Nm 253to print debugging messages about its progress. 254This is helpful in debugging problems. 255Multiple 256.Fl v 257options increase the verbosity. 258The maximum is 3. 259.It Fl X 260Unlock the agent. 261.It Fl x 262Lock the agent with a password. 263.El 264.Sh ENVIRONMENT 265.Bl -tag -width Ds 266.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE" 267If 268.Nm 269needs a passphrase, it will read the passphrase from the current 270terminal if it was run from a terminal. 271If 272.Nm 273does not have a terminal associated with it but 274.Ev DISPLAY 275and 276.Ev SSH_ASKPASS 277are set, it will execute the program specified by 278.Ev SSH_ASKPASS 279(by default 280.Dq ssh-askpass ) 281and open an X11 window to read the passphrase. 282This is particularly useful when calling 283.Nm 284from a 285.Pa .xsession 286or related script. 287.Pp 288.Ev SSH_ASKPASS_REQUIRE 289allows further control over the use of an askpass program. 290If this variable is set to 291.Dq never 292then 293.Nm 294will never attempt to use one. 295If it is set to 296.Dq prefer , 297then 298.Nm 299will prefer to use the askpass program instead of the TTY when requesting 300passwords. 301Finally, if the variable is set to 302.Dq force , 303then the askpass program will be used for all passphrase input regardless 304of whether 305.Ev DISPLAY 306is set. 307.It Ev SSH_AUTH_SOCK 308Identifies the path of a 309.Ux Ns -domain 310socket used to communicate with the agent. 311.It Ev SSH_SK_PROVIDER 312Specifies a path to a library that will be used when loading any 313FIDO authenticator-hosted keys, overriding the default of using 314the built-in USB HID support. 315.El 316.Sh FILES 317.Bl -tag -width Ds -compact 318.It Pa ~/.ssh/id_dsa 319.It Pa ~/.ssh/id_ecdsa 320.It Pa ~/.ssh/id_ecdsa_sk 321.It Pa ~/.ssh/id_ed25519 322.It Pa ~/.ssh/id_ed25519_sk 323.It Pa ~/.ssh/id_rsa 324Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 325authenticator-hosted Ed25519 or RSA authentication identity of the user. 326.El 327.Pp 328Identity files should not be readable by anyone but the user. 329Note that 330.Nm 331ignores identity files if they are accessible by others. 332.Sh EXIT STATUS 333Exit status is 0 on success, 1 if the specified command fails, 334and 2 if 335.Nm 336is unable to contact the authentication agent. 337.Sh SEE ALSO 338.Xr ssh 1 , 339.Xr ssh-agent 1 , 340.Xr ssh-askpass 1 , 341.Xr ssh-keygen 1 , 342.Xr sshd 8 343.Sh AUTHORS 344OpenSSH is a derivative of the original and free 345ssh 1.2.12 release by Tatu Ylonen. 346Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 347Theo de Raadt and Dug Song 348removed many bugs, re-added newer features and 349created OpenSSH. 350Markus Friedl contributed the support for SSH 351protocol versions 1.5 and 2.0. 352