1*ee116499SAntonio Huete Jimenez.\" $OpenBSD: ssh-add.1,v 1.84 2022/02/04 02:49:17 dtucker Exp $ 218de8d7fSPeter Avalos.\" 318de8d7fSPeter Avalos.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 418de8d7fSPeter Avalos.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 518de8d7fSPeter Avalos.\" All rights reserved 618de8d7fSPeter Avalos.\" 718de8d7fSPeter Avalos.\" As far as I am concerned, the code I have written for this software 818de8d7fSPeter Avalos.\" can be used freely for any purpose. Any derived versions of this 918de8d7fSPeter Avalos.\" software must be clearly marked as such, and if the derived work is 1018de8d7fSPeter Avalos.\" incompatible with the protocol description in the RFC file, it must be 1118de8d7fSPeter Avalos.\" called by a name other than "ssh" or "Secure Shell". 1218de8d7fSPeter Avalos.\" 1318de8d7fSPeter Avalos.\" 1418de8d7fSPeter Avalos.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 1518de8d7fSPeter Avalos.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 1618de8d7fSPeter Avalos.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 1718de8d7fSPeter Avalos.\" 1818de8d7fSPeter Avalos.\" Redistribution and use in source and binary forms, with or without 1918de8d7fSPeter Avalos.\" modification, are permitted provided that the following conditions 2018de8d7fSPeter Avalos.\" are met: 2118de8d7fSPeter Avalos.\" 1. Redistributions of source code must retain the above copyright 2218de8d7fSPeter Avalos.\" notice, this list of conditions and the following disclaimer. 2318de8d7fSPeter Avalos.\" 2. Redistributions in binary form must reproduce the above copyright 2418de8d7fSPeter Avalos.\" notice, this list of conditions and the following disclaimer in the 2518de8d7fSPeter Avalos.\" documentation and/or other materials provided with the distribution. 2618de8d7fSPeter Avalos.\" 2718de8d7fSPeter Avalos.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 2818de8d7fSPeter Avalos.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 2918de8d7fSPeter Avalos.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 3018de8d7fSPeter Avalos.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 3118de8d7fSPeter Avalos.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 3218de8d7fSPeter Avalos.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 3318de8d7fSPeter Avalos.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 3418de8d7fSPeter Avalos.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 3518de8d7fSPeter Avalos.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 3618de8d7fSPeter Avalos.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3718de8d7fSPeter Avalos.\" 38*ee116499SAntonio Huete Jimenez.Dd $Mdocdate: February 4 2022 $ 3918de8d7fSPeter Avalos.Dt SSH-ADD 1 4018de8d7fSPeter Avalos.Os 4118de8d7fSPeter Avalos.Sh NAME 4218de8d7fSPeter Avalos.Nm ssh-add 430cbfa66cSDaniel Fojt.Nd adds private key identities to the OpenSSH authentication agent 4418de8d7fSPeter Avalos.Sh SYNOPSIS 4518de8d7fSPeter Avalos.Nm ssh-add 460cbfa66cSDaniel Fojt.Op Fl cDdKkLlqvXx 47e9778795SPeter Avalos.Op Fl E Ar fingerprint_hash 48*ee116499SAntonio Huete Jimenez.Op Fl H Ar hostkey_file 49*ee116499SAntonio Huete Jimenez.Op Fl h Ar destination_constraint 500cbfa66cSDaniel Fojt.Op Fl S Ar provider 5118de8d7fSPeter Avalos.Op Fl t Ar life 5218de8d7fSPeter Avalos.Op Ar 5318de8d7fSPeter Avalos.Nm ssh-add 54856ea928SPeter Avalos.Fl s Ar pkcs11 5518de8d7fSPeter Avalos.Nm ssh-add 56856ea928SPeter Avalos.Fl e Ar pkcs11 57664f4763Szrj.Nm ssh-add 58664f4763Szrj.Fl T 59664f4763Szrj.Ar pubkey ... 6018de8d7fSPeter Avalos.Sh DESCRIPTION 6118de8d7fSPeter Avalos.Nm 629f304aafSPeter Avalosadds private key identities to the authentication agent, 6318de8d7fSPeter Avalos.Xr ssh-agent 1 . 6418de8d7fSPeter AvalosWhen run without arguments, it adds the files 6518de8d7fSPeter Avalos.Pa ~/.ssh/id_rsa , 6636e94dc5SPeter Avalos.Pa ~/.ssh/id_ecdsa , 670cbfa66cSDaniel Fojt.Pa ~/.ssh/id_ecdsa_sk , 680cbfa66cSDaniel Fojt.Pa ~/.ssh/id_ed25519 , 69*ee116499SAntonio Huete Jimenez.Pa ~/.ssh/id_ed25519_sk , 7018de8d7fSPeter Avalosand 71*ee116499SAntonio Huete Jimenez.Pa ~/.ssh/id_dsa . 72856ea928SPeter AvalosAfter loading a private key, 73856ea928SPeter Avalos.Nm 74856ea928SPeter Avaloswill try to load corresponding certificate information from the 75856ea928SPeter Avalosfilename obtained by appending 76856ea928SPeter Avalos.Pa -cert.pub 77856ea928SPeter Avalosto the name of the private key file. 7818de8d7fSPeter AvalosAlternative file names can be given on the command line. 79856ea928SPeter Avalos.Pp 8018de8d7fSPeter AvalosIf any file requires a passphrase, 8118de8d7fSPeter Avalos.Nm 8218de8d7fSPeter Avalosasks for the passphrase from the user. 8318de8d7fSPeter AvalosThe passphrase is read from the user's tty. 8418de8d7fSPeter Avalos.Nm 8518de8d7fSPeter Avalosretries the last passphrase if multiple identity files are given. 8618de8d7fSPeter Avalos.Pp 8718de8d7fSPeter AvalosThe authentication agent must be running and the 8818de8d7fSPeter Avalos.Ev SSH_AUTH_SOCK 8918de8d7fSPeter Avalosenvironment variable must contain the name of its socket for 9018de8d7fSPeter Avalos.Nm 9118de8d7fSPeter Avalosto work. 9218de8d7fSPeter Avalos.Pp 9318de8d7fSPeter AvalosThe options are as follows: 9418de8d7fSPeter Avalos.Bl -tag -width Ds 9518de8d7fSPeter Avalos.It Fl c 9618de8d7fSPeter AvalosIndicates that added identities should be subject to confirmation before 9718de8d7fSPeter Avalosbeing used for authentication. 98e9778795SPeter AvalosConfirmation is performed by 99e9778795SPeter Avalos.Xr ssh-askpass 1 . 100e9778795SPeter AvalosSuccessful confirmation is signaled by a zero exit status from 101e9778795SPeter Avalos.Xr ssh-askpass 1 , 102e9778795SPeter Avalosrather than text entered into the requester. 10318de8d7fSPeter Avalos.It Fl D 10418de8d7fSPeter AvalosDeletes all identities from the agent. 10518de8d7fSPeter Avalos.It Fl d 10618de8d7fSPeter AvalosInstead of adding identities, removes identities from the agent. 10718de8d7fSPeter AvalosIf 10818de8d7fSPeter Avalos.Nm 10936e94dc5SPeter Avaloshas been run without arguments, the keys for the default identities and 11036e94dc5SPeter Avalostheir corresponding certificates will be removed. 11118de8d7fSPeter AvalosOtherwise, the argument list will be interpreted as a list of paths to 11236e94dc5SPeter Avalospublic key files to specify keys and certificates to be removed from the agent. 11318de8d7fSPeter AvalosIf no public key is found at a given path, 11418de8d7fSPeter Avalos.Nm 11518de8d7fSPeter Avaloswill append 11618de8d7fSPeter Avalos.Pa .pub 11718de8d7fSPeter Avalosand retry. 11850a69bb5SSascha WildnerIf the argument list consists of 11950a69bb5SSascha Wildner.Dq - 12050a69bb5SSascha Wildnerthen 12150a69bb5SSascha Wildner.Nm 12250a69bb5SSascha Wildnerwill read public keys to be removed from standard input. 123e9778795SPeter Avalos.It Fl E Ar fingerprint_hash 124e9778795SPeter AvalosSpecifies the hash algorithm used when displaying key fingerprints. 125e9778795SPeter AvalosValid options are: 126e9778795SPeter Avalos.Dq md5 127e9778795SPeter Avalosand 128e9778795SPeter Avalos.Dq sha256 . 129e9778795SPeter AvalosThe default is 130e9778795SPeter Avalos.Dq sha256 . 131856ea928SPeter Avalos.It Fl e Ar pkcs11 132856ea928SPeter AvalosRemove keys provided by the PKCS#11 shared library 133856ea928SPeter Avalos.Ar pkcs11 . 134*ee116499SAntonio Huete Jimenez.It Fl H Ar hostkey_file 135*ee116499SAntonio Huete JimenezSpecifies a known hosts file to look up hostkeys when using 136*ee116499SAntonio Huete Jimenezdestination-constrained keys via the 137*ee116499SAntonio Huete Jimenez.Fl h 138*ee116499SAntonio Huete Jimenezflag. 139*ee116499SAntonio Huete JimenezThis option may be specified multiple times to allow multiple files to be 140*ee116499SAntonio Huete Jimenezsearched. 141*ee116499SAntonio Huete JimenezIf no files are specified, 142*ee116499SAntonio Huete Jimenez.Nm 143*ee116499SAntonio Huete Jimenezwill use the default 144*ee116499SAntonio Huete Jimenez.Xr ssh_config 5 145*ee116499SAntonio Huete Jimenezknown hosts files: 146*ee116499SAntonio Huete Jimenez.Pa ~/.ssh/known_hosts , 147*ee116499SAntonio Huete Jimenez.Pa ~/.ssh/known_hosts2 , 148*ee116499SAntonio Huete Jimenez.Pa /etc/ssh/ssh_known_hosts , 149*ee116499SAntonio Huete Jimenezand 150*ee116499SAntonio Huete Jimenez.Pa /etc/ssh/ssh_known_hosts2 . 151*ee116499SAntonio Huete Jimenez.It Fl h Ar destination_constraint 152*ee116499SAntonio Huete JimenezWhen adding keys, constrain them to be usable only through specific hosts or to 153*ee116499SAntonio Huete Jimenezspecific destinations. 154*ee116499SAntonio Huete Jimenez.Pp 155*ee116499SAntonio Huete JimenezDestination constraints of the form 156*ee116499SAntonio Huete Jimenez.Sq [user@]dest-hostname 157*ee116499SAntonio Huete Jimenezpermit use of the key only from the origin host (the one running 158*ee116499SAntonio Huete Jimenez.Xr ssh-agent 1 ) 159*ee116499SAntonio Huete Jimenezto the listed destination host, with optional user name. 160*ee116499SAntonio Huete Jimenez.Pp 161*ee116499SAntonio Huete JimenezConstraints of the form 162*ee116499SAntonio Huete Jimenez.Sq src-hostname>[user@]dst-hostname 163*ee116499SAntonio Huete Jimenezallow a key available on a forwarded 164*ee116499SAntonio Huete Jimenez.Xr ssh-agent 1 165*ee116499SAntonio Huete Jimenezto be used through a particular host (as specified by 166*ee116499SAntonio Huete Jimenez.Sq src-hostname ) 167*ee116499SAntonio Huete Jimenezto authenticate to a further host, 168*ee116499SAntonio Huete Jimenezspecified by 169*ee116499SAntonio Huete Jimenez.Sq dst-hostname . 170*ee116499SAntonio Huete Jimenez.Pp 171*ee116499SAntonio Huete JimenezMultiple destination constraints may be added when loading keys. 172*ee116499SAntonio Huete JimenezWhen attempting authentication with a key that has destination constraints, 173*ee116499SAntonio Huete Jimenezthe whole connection path, including 174*ee116499SAntonio Huete Jimenez.Xr ssh-agent 1 175*ee116499SAntonio Huete Jimenezforwarding, is tested against those constraints and each 176*ee116499SAntonio Huete Jimenezhop must be permitted for the attempt to succeed. 177*ee116499SAntonio Huete JimenezFor example, if key is forwarded to a remote host, 178*ee116499SAntonio Huete Jimenez.Sq host-b , 179*ee116499SAntonio Huete Jimenezand is attempting authentication to another host, 180*ee116499SAntonio Huete Jimenez.Sq host-c , 181*ee116499SAntonio Huete Jimenezthen the operation will be successful only if 182*ee116499SAntonio Huete Jimenez.Sq host-b 183*ee116499SAntonio Huete Jimenezwas permitted from the origin host and the subsequent 184*ee116499SAntonio Huete Jimenez.Sq host-b>host-c 185*ee116499SAntonio Huete Jimenezhop is also permitted by destination constraints. 186*ee116499SAntonio Huete Jimenez.Pp 187*ee116499SAntonio Huete JimenezHosts are identified by their host keys, and are looked up from known hosts 188*ee116499SAntonio Huete Jimenezfiles by 189*ee116499SAntonio Huete Jimenez.Nm . 190*ee116499SAntonio Huete JimenezWildcards patterns may be used for hostnames and certificate host 191*ee116499SAntonio Huete Jimenezkeys are supported. 192*ee116499SAntonio Huete JimenezBy default, keys added by 193*ee116499SAntonio Huete Jimenez.Nm 194*ee116499SAntonio Huete Jimenezare not destination constrained. 195*ee116499SAntonio Huete Jimenez.Pp 196*ee116499SAntonio Huete JimenezDestination constraints were added in OpenSSH release 8.9. 197*ee116499SAntonio Huete JimenezSupport in both the remote SSH client and server is required when using 198*ee116499SAntonio Huete Jimenezdestination-constrained keys over a forwarded 199*ee116499SAntonio Huete Jimenez.Xr ssh-agent 1 200*ee116499SAntonio Huete Jimenezchannel. 201*ee116499SAntonio Huete Jimenez.Pp 202*ee116499SAntonio Huete JimenezIt is also important to note that destination constraints can only be 203*ee116499SAntonio Huete Jimenezenforced by 204*ee116499SAntonio Huete Jimenez.Xr ssh-agent 1 205*ee116499SAntonio Huete Jimenezwhen a key is used, or when it is forwarded by a 206*ee116499SAntonio Huete Jimenez.Sy cooperating 207*ee116499SAntonio Huete Jimenez.Xr ssh 1 . 208*ee116499SAntonio Huete JimenezSpecifically, it does not prevent an attacker with access to a remote 209*ee116499SAntonio Huete Jimenez.Ev SSH_AUTH_SOCK 210*ee116499SAntonio Huete Jimenezfrom forwarding it again and using it on a different host (but only to 211*ee116499SAntonio Huete Jimeneza permitted destination). 2120cbfa66cSDaniel Fojt.It Fl K 2130cbfa66cSDaniel FojtLoad resident keys from a FIDO authenticator. 21499e85e0dSPeter Avalos.It Fl k 21536e94dc5SPeter AvalosWhen loading keys into or deleting keys from the agent, process plain private 21636e94dc5SPeter Avaloskeys only and skip certificates. 21718de8d7fSPeter Avalos.It Fl L 21818de8d7fSPeter AvalosLists public key parameters of all identities currently represented 21918de8d7fSPeter Avalosby the agent. 22018de8d7fSPeter Avalos.It Fl l 22118de8d7fSPeter AvalosLists fingerprints of all identities currently represented by the agent. 222ce74bacaSMatthew Dillon.It Fl q 223ce74bacaSMatthew DillonBe quiet after a successful operation. 2240cbfa66cSDaniel Fojt.It Fl S Ar provider 2250cbfa66cSDaniel FojtSpecifies a path to a library that will be used when adding 2260cbfa66cSDaniel FojtFIDO authenticator-hosted keys, overriding the default of using the 2270cbfa66cSDaniel Fojtinternal USB HID support. 228856ea928SPeter Avalos.It Fl s Ar pkcs11 229856ea928SPeter AvalosAdd keys provided by the PKCS#11 shared library 230856ea928SPeter Avalos.Ar pkcs11 . 231664f4763Szrj.It Fl T Ar pubkey ... 232664f4763SzrjTests whether the private keys that correspond to the specified 233664f4763Szrj.Ar pubkey 234664f4763Szrjfiles are usable by performing sign and verify operations on each. 23518de8d7fSPeter Avalos.It Fl t Ar life 23618de8d7fSPeter AvalosSet a maximum lifetime when adding identities to an agent. 23718de8d7fSPeter AvalosThe lifetime may be specified in seconds or in a time format 23818de8d7fSPeter Avalosspecified in 23918de8d7fSPeter Avalos.Xr sshd_config 5 . 240664f4763Szrj.It Fl v 241664f4763SzrjVerbose mode. 242664f4763SzrjCauses 243664f4763Szrj.Nm 244664f4763Szrjto print debugging messages about its progress. 245664f4763SzrjThis is helpful in debugging problems. 246664f4763SzrjMultiple 247664f4763Szrj.Fl v 248664f4763Szrjoptions increase the verbosity. 249664f4763SzrjThe maximum is 3. 25018de8d7fSPeter Avalos.It Fl X 25118de8d7fSPeter AvalosUnlock the agent. 25218de8d7fSPeter Avalos.It Fl x 25318de8d7fSPeter AvalosLock the agent with a password. 25418de8d7fSPeter Avalos.El 25518de8d7fSPeter Avalos.Sh ENVIRONMENT 25618de8d7fSPeter Avalos.Bl -tag -width Ds 25750a69bb5SSascha Wildner.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE" 25818de8d7fSPeter AvalosIf 25918de8d7fSPeter Avalos.Nm 26018de8d7fSPeter Avalosneeds a passphrase, it will read the passphrase from the current 26118de8d7fSPeter Avalosterminal if it was run from a terminal. 26218de8d7fSPeter AvalosIf 26318de8d7fSPeter Avalos.Nm 26418de8d7fSPeter Avalosdoes not have a terminal associated with it but 26518de8d7fSPeter Avalos.Ev DISPLAY 26618de8d7fSPeter Avalosand 26718de8d7fSPeter Avalos.Ev SSH_ASKPASS 26818de8d7fSPeter Avalosare set, it will execute the program specified by 26918de8d7fSPeter Avalos.Ev SSH_ASKPASS 270e9778795SPeter Avalos(by default 271e9778795SPeter Avalos.Dq ssh-askpass ) 27218de8d7fSPeter Avalosand open an X11 window to read the passphrase. 27318de8d7fSPeter AvalosThis is particularly useful when calling 27418de8d7fSPeter Avalos.Nm 27518de8d7fSPeter Avalosfrom a 27618de8d7fSPeter Avalos.Pa .xsession 27718de8d7fSPeter Avalosor related script. 27850a69bb5SSascha Wildner.Pp 27950a69bb5SSascha Wildner.Ev SSH_ASKPASS_REQUIRE 28050a69bb5SSascha Wildnerallows further control over the use of an askpass program. 28150a69bb5SSascha WildnerIf this variable is set to 28250a69bb5SSascha Wildner.Dq never 28350a69bb5SSascha Wildnerthen 28450a69bb5SSascha Wildner.Nm 28550a69bb5SSascha Wildnerwill never attempt to use one. 28650a69bb5SSascha WildnerIf it is set to 28750a69bb5SSascha Wildner.Dq prefer , 28850a69bb5SSascha Wildnerthen 28950a69bb5SSascha Wildner.Nm 29050a69bb5SSascha Wildnerwill prefer to use the askpass program instead of the TTY when requesting 29150a69bb5SSascha Wildnerpasswords. 29250a69bb5SSascha WildnerFinally, if the variable is set to 29350a69bb5SSascha Wildner.Dq force , 29450a69bb5SSascha Wildnerthen the askpass program will be used for all passphrase input regardless 29550a69bb5SSascha Wildnerof whether 29650a69bb5SSascha Wildner.Ev DISPLAY 29750a69bb5SSascha Wildneris set. 29818de8d7fSPeter Avalos.It Ev SSH_AUTH_SOCK 299856ea928SPeter AvalosIdentifies the path of a 300856ea928SPeter Avalos.Ux Ns -domain 301856ea928SPeter Avalossocket used to communicate with the agent. 3020cbfa66cSDaniel Fojt.It Ev SSH_SK_PROVIDER 3030cbfa66cSDaniel FojtSpecifies a path to a library that will be used when loading any 3040cbfa66cSDaniel FojtFIDO authenticator-hosted keys, overriding the default of using 3050cbfa66cSDaniel Fojtthe built-in USB HID support. 30618de8d7fSPeter Avalos.El 30718de8d7fSPeter Avalos.Sh FILES 3080cbfa66cSDaniel Fojt.Bl -tag -width Ds -compact 30918de8d7fSPeter Avalos.It Pa ~/.ssh/id_dsa 3109f304aafSPeter Avalos.It Pa ~/.ssh/id_ecdsa 3110cbfa66cSDaniel Fojt.It Pa ~/.ssh/id_ecdsa_sk 31236e94dc5SPeter Avalos.It Pa ~/.ssh/id_ed25519 3130cbfa66cSDaniel Fojt.It Pa ~/.ssh/id_ed25519_sk 31418de8d7fSPeter Avalos.It Pa ~/.ssh/id_rsa 3150cbfa66cSDaniel FojtContains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 3160cbfa66cSDaniel Fojtauthenticator-hosted Ed25519 or RSA authentication identity of the user. 31718de8d7fSPeter Avalos.El 31818de8d7fSPeter Avalos.Pp 31918de8d7fSPeter AvalosIdentity files should not be readable by anyone but the user. 32018de8d7fSPeter AvalosNote that 32118de8d7fSPeter Avalos.Nm 32218de8d7fSPeter Avalosignores identity files if they are accessible by others. 3239f304aafSPeter Avalos.Sh EXIT STATUS 32418de8d7fSPeter AvalosExit status is 0 on success, 1 if the specified command fails, 32518de8d7fSPeter Avalosand 2 if 32618de8d7fSPeter Avalos.Nm 32718de8d7fSPeter Avalosis unable to contact the authentication agent. 32818de8d7fSPeter Avalos.Sh SEE ALSO 32918de8d7fSPeter Avalos.Xr ssh 1 , 33018de8d7fSPeter Avalos.Xr ssh-agent 1 , 331e9778795SPeter Avalos.Xr ssh-askpass 1 , 33218de8d7fSPeter Avalos.Xr ssh-keygen 1 , 33318de8d7fSPeter Avalos.Xr sshd 8 33418de8d7fSPeter Avalos.Sh AUTHORS 33518de8d7fSPeter AvalosOpenSSH is a derivative of the original and free 33618de8d7fSPeter Avalosssh 1.2.12 release by Tatu Ylonen. 33718de8d7fSPeter AvalosAaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 33818de8d7fSPeter AvalosTheo de Raadt and Dug Song 33918de8d7fSPeter Avalosremoved many bugs, re-added newer features and 34018de8d7fSPeter Avaloscreated OpenSSH. 34118de8d7fSPeter AvalosMarkus Friedl contributed the support for SSH 34218de8d7fSPeter Avalosprotocol versions 1.5 and 2.0. 343