1a91a2465SEd Maste.\" $OpenBSD: ssh-add.1,v 1.86 2023/12/19 06:57:34 jmc Exp $ 2511b41d2SMark Murray.\" 3511b41d2SMark Murray.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4511b41d2SMark Murray.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5511b41d2SMark Murray.\" All rights reserved 6511b41d2SMark Murray.\" 7b66f2d16SKris Kennaway.\" As far as I am concerned, the code I have written for this software 8b66f2d16SKris Kennaway.\" can be used freely for any purpose. Any derived versions of this 9b66f2d16SKris Kennaway.\" software must be clearly marked as such, and if the derived work is 10b66f2d16SKris Kennaway.\" incompatible with the protocol description in the RFC file, it must be 11b66f2d16SKris Kennaway.\" called by a name other than "ssh" or "Secure Shell". 12511b41d2SMark Murray.\" 13b66f2d16SKris Kennaway.\" 14b66f2d16SKris Kennaway.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 15b66f2d16SKris Kennaway.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 16b66f2d16SKris Kennaway.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 17b66f2d16SKris Kennaway.\" 18b66f2d16SKris Kennaway.\" Redistribution and use in source and binary forms, with or without 19b66f2d16SKris Kennaway.\" modification, are permitted provided that the following conditions 20b66f2d16SKris Kennaway.\" are met: 21b66f2d16SKris Kennaway.\" 1. Redistributions of source code must retain the above copyright 22b66f2d16SKris Kennaway.\" notice, this list of conditions and the following disclaimer. 23b66f2d16SKris Kennaway.\" 2. Redistributions in binary form must reproduce the above copyright 24b66f2d16SKris Kennaway.\" notice, this list of conditions and the following disclaimer in the 25b66f2d16SKris Kennaway.\" documentation and/or other materials provided with the distribution. 26b66f2d16SKris Kennaway.\" 27b66f2d16SKris Kennaway.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 28b66f2d16SKris Kennaway.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 29b66f2d16SKris Kennaway.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 30b66f2d16SKris Kennaway.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 31b66f2d16SKris Kennaway.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 32b66f2d16SKris Kennaway.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 33b66f2d16SKris Kennaway.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 34b66f2d16SKris Kennaway.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 35b66f2d16SKris Kennaway.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 36b66f2d16SKris Kennaway.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37511b41d2SMark Murray.\" 38a91a2465SEd Maste.Dd $Mdocdate: December 19 2023 $ 39511b41d2SMark Murray.Dt SSH-ADD 1 40511b41d2SMark Murray.Os 41511b41d2SMark Murray.Sh NAME 42511b41d2SMark Murray.Nm ssh-add 4319261079SEd Maste.Nd adds private key identities to the OpenSSH authentication agent 44511b41d2SMark Murray.Sh SYNOPSIS 45511b41d2SMark Murray.Nm ssh-add 46a91a2465SEd Maste.Op Fl CcDdKkLlqvXx 47bc5531deSDag-Erling Smørgrav.Op Fl E Ar fingerprint_hash 481323ec57SEd Maste.Op Fl H Ar hostkey_file 491323ec57SEd Maste.Op Fl h Ar destination_constraint 5019261079SEd Maste.Op Fl S Ar provider 51545d5ecaSDag-Erling Smørgrav.Op Fl t Ar life 52511b41d2SMark Murray.Op Ar 53ae1f160dSDag-Erling Smørgrav.Nm ssh-add 54b15c8340SDag-Erling Smørgrav.Fl s Ar pkcs11 55a91a2465SEd Maste.Op Fl Cv 56069ac184SEd Maste.Op Ar certificate ... 57ae1f160dSDag-Erling Smørgrav.Nm ssh-add 58b15c8340SDag-Erling Smørgrav.Fl e Ar pkcs11 5919261079SEd Maste.Nm ssh-add 6019261079SEd Maste.Fl T 6119261079SEd Maste.Ar pubkey ... 62511b41d2SMark Murray.Sh DESCRIPTION 63511b41d2SMark Murray.Nm 644a421b63SDag-Erling Smørgravadds private key identities to the authentication agent, 65511b41d2SMark Murray.Xr ssh-agent 1 . 66ae1f160dSDag-Erling SmørgravWhen run without arguments, it adds the files 67043840dfSDag-Erling Smørgrav.Pa ~/.ssh/id_rsa , 68f7167e0eSDag-Erling Smørgrav.Pa ~/.ssh/id_ecdsa , 6919261079SEd Maste.Pa ~/.ssh/id_ecdsa_sk , 7019261079SEd Maste.Pa ~/.ssh/id_ed25519 , 711323ec57SEd Maste.Pa ~/.ssh/id_ed25519_sk , 72ae1f160dSDag-Erling Smørgravand 731323ec57SEd Maste.Pa ~/.ssh/id_dsa . 74b15c8340SDag-Erling SmørgravAfter loading a private key, 75b15c8340SDag-Erling Smørgrav.Nm 76b15c8340SDag-Erling Smørgravwill try to load corresponding certificate information from the 77b15c8340SDag-Erling Smørgravfilename obtained by appending 78b15c8340SDag-Erling Smørgrav.Pa -cert.pub 79b15c8340SDag-Erling Smørgravto the name of the private key file. 80a8f6863aSKris KennawayAlternative file names can be given on the command line. 81b15c8340SDag-Erling Smørgrav.Pp 82a8f6863aSKris KennawayIf any file requires a passphrase, 83511b41d2SMark Murray.Nm 84511b41d2SMark Murrayasks for the passphrase from the user. 85ae1f160dSDag-Erling SmørgravThe passphrase is read from the user's tty. 861e8db6e2SBrian Feldman.Nm 871e8db6e2SBrian Feldmanretries the last passphrase if multiple identity files are given. 88511b41d2SMark Murray.Pp 89efcad6b7SDag-Erling SmørgravThe authentication agent must be running and the 90efcad6b7SDag-Erling Smørgrav.Ev SSH_AUTH_SOCK 91efcad6b7SDag-Erling Smørgravenvironment variable must contain the name of its socket for 92511b41d2SMark Murray.Nm 93511b41d2SMark Murrayto work. 94511b41d2SMark Murray.Pp 95511b41d2SMark MurrayThe options are as follows: 96511b41d2SMark Murray.Bl -tag -width Ds 97a91a2465SEd Maste.It Fl C 98a91a2465SEd MasteWhen loading keys into or deleting keys from the agent, process 99a91a2465SEd Mastecertificates only and skip plain keys. 100d0c8c0bcSDag-Erling Smørgrav.It Fl c 101d0c8c0bcSDag-Erling SmørgravIndicates that added identities should be subject to confirmation before 102d0c8c0bcSDag-Erling Smørgravbeing used for authentication. 103557f75e5SDag-Erling SmørgravConfirmation is performed by 104557f75e5SDag-Erling Smørgrav.Xr ssh-askpass 1 . 105557f75e5SDag-Erling SmørgravSuccessful confirmation is signaled by a zero exit status from 106557f75e5SDag-Erling Smørgrav.Xr ssh-askpass 1 , 107557f75e5SDag-Erling Smørgravrather than text entered into the requester. 1085e8dbd04SDag-Erling Smørgrav.It Fl D 1095e8dbd04SDag-Erling SmørgravDeletes all identities from the agent. 1105e8dbd04SDag-Erling Smørgrav.It Fl d 111d4af9e69SDag-Erling SmørgravInstead of adding identities, removes identities from the agent. 112d4af9e69SDag-Erling SmørgravIf 113d4af9e69SDag-Erling Smørgrav.Nm 1146888a9beSDag-Erling Smørgravhas been run without arguments, the keys for the default identities and 1156888a9beSDag-Erling Smørgravtheir corresponding certificates will be removed. 116d4af9e69SDag-Erling SmørgravOtherwise, the argument list will be interpreted as a list of paths to 1176888a9beSDag-Erling Smørgravpublic key files to specify keys and certificates to be removed from the agent. 118d4af9e69SDag-Erling SmørgravIf no public key is found at a given path, 119d4af9e69SDag-Erling Smørgrav.Nm 120d4af9e69SDag-Erling Smørgravwill append 121d4af9e69SDag-Erling Smørgrav.Pa .pub 122d4af9e69SDag-Erling Smørgravand retry. 12319261079SEd MasteIf the argument list consists of 12419261079SEd Maste.Dq - 12519261079SEd Mastethen 12619261079SEd Maste.Nm 12719261079SEd Mastewill read public keys to be removed from standard input. 128bc5531deSDag-Erling Smørgrav.It Fl E Ar fingerprint_hash 129bc5531deSDag-Erling SmørgravSpecifies the hash algorithm used when displaying key fingerprints. 130bc5531deSDag-Erling SmørgravValid options are: 131bc5531deSDag-Erling Smørgrav.Dq md5 132bc5531deSDag-Erling Smørgravand 133bc5531deSDag-Erling Smørgrav.Dq sha256 . 134bc5531deSDag-Erling SmørgravThe default is 135bc5531deSDag-Erling Smørgrav.Dq sha256 . 136b15c8340SDag-Erling Smørgrav.It Fl e Ar pkcs11 137b15c8340SDag-Erling SmørgravRemove keys provided by the PKCS#11 shared library 138b15c8340SDag-Erling Smørgrav.Ar pkcs11 . 1391323ec57SEd Maste.It Fl H Ar hostkey_file 1401323ec57SEd MasteSpecifies a known hosts file to look up hostkeys when using 1411323ec57SEd Mastedestination-constrained keys via the 1421323ec57SEd Maste.Fl h 1431323ec57SEd Masteflag. 1441323ec57SEd MasteThis option may be specified multiple times to allow multiple files to be 1451323ec57SEd Mastesearched. 1461323ec57SEd MasteIf no files are specified, 1471323ec57SEd Maste.Nm 1481323ec57SEd Mastewill use the default 1491323ec57SEd Maste.Xr ssh_config 5 1501323ec57SEd Masteknown hosts files: 1511323ec57SEd Maste.Pa ~/.ssh/known_hosts , 1521323ec57SEd Maste.Pa ~/.ssh/known_hosts2 , 1531323ec57SEd Maste.Pa /etc/ssh/ssh_known_hosts , 1541323ec57SEd Masteand 1551323ec57SEd Maste.Pa /etc/ssh/ssh_known_hosts2 . 1561323ec57SEd Maste.It Fl h Ar destination_constraint 1571323ec57SEd MasteWhen adding keys, constrain them to be usable only through specific hosts or to 1581323ec57SEd Mastespecific destinations. 1591323ec57SEd Maste.Pp 1601323ec57SEd MasteDestination constraints of the form 1611323ec57SEd Maste.Sq [user@]dest-hostname 1621323ec57SEd Mastepermit use of the key only from the origin host (the one running 1631323ec57SEd Maste.Xr ssh-agent 1 ) 1641323ec57SEd Masteto the listed destination host, with optional user name. 1651323ec57SEd Maste.Pp 1661323ec57SEd MasteConstraints of the form 1671323ec57SEd Maste.Sq src-hostname>[user@]dst-hostname 1681323ec57SEd Masteallow a key available on a forwarded 1691323ec57SEd Maste.Xr ssh-agent 1 1701323ec57SEd Masteto be used through a particular host (as specified by 1711323ec57SEd Maste.Sq src-hostname ) 1721323ec57SEd Masteto authenticate to a further host, 1731323ec57SEd Mastespecified by 1741323ec57SEd Maste.Sq dst-hostname . 1751323ec57SEd Maste.Pp 1761323ec57SEd MasteMultiple destination constraints may be added when loading keys. 1771323ec57SEd MasteWhen attempting authentication with a key that has destination constraints, 1781323ec57SEd Mastethe whole connection path, including 1791323ec57SEd Maste.Xr ssh-agent 1 1801323ec57SEd Masteforwarding, is tested against those constraints and each 1811323ec57SEd Mastehop must be permitted for the attempt to succeed. 1821323ec57SEd MasteFor example, if key is forwarded to a remote host, 1831323ec57SEd Maste.Sq host-b , 1841323ec57SEd Masteand is attempting authentication to another host, 1851323ec57SEd Maste.Sq host-c , 1861323ec57SEd Mastethen the operation will be successful only if 1871323ec57SEd Maste.Sq host-b 1881323ec57SEd Mastewas permitted from the origin host and the subsequent 1891323ec57SEd Maste.Sq host-b>host-c 1901323ec57SEd Mastehop is also permitted by destination constraints. 1911323ec57SEd Maste.Pp 1921323ec57SEd MasteHosts are identified by their host keys, and are looked up from known hosts 1931323ec57SEd Mastefiles by 1941323ec57SEd Maste.Nm . 1951323ec57SEd MasteWildcards patterns may be used for hostnames and certificate host 1961323ec57SEd Mastekeys are supported. 1971323ec57SEd MasteBy default, keys added by 1981323ec57SEd Maste.Nm 1991323ec57SEd Masteare not destination constrained. 2001323ec57SEd Maste.Pp 2011323ec57SEd MasteDestination constraints were added in OpenSSH release 8.9. 2021323ec57SEd MasteSupport in both the remote SSH client and server is required when using 2031323ec57SEd Mastedestination-constrained keys over a forwarded 2041323ec57SEd Maste.Xr ssh-agent 1 2051323ec57SEd Mastechannel. 2061323ec57SEd Maste.Pp 2071323ec57SEd MasteIt is also important to note that destination constraints can only be 2081323ec57SEd Masteenforced by 2091323ec57SEd Maste.Xr ssh-agent 1 2101323ec57SEd Mastewhen a key is used, or when it is forwarded by a 2111323ec57SEd Maste.Sy cooperating 2121323ec57SEd Maste.Xr ssh 1 . 2131323ec57SEd MasteSpecifically, it does not prevent an attacker with access to a remote 2141323ec57SEd Maste.Ev SSH_AUTH_SOCK 2151323ec57SEd Mastefrom forwarding it again and using it on a different host (but only to 2161323ec57SEd Mastea permitted destination). 21719261079SEd Maste.It Fl K 21819261079SEd MasteLoad resident keys from a FIDO authenticator. 219462c32cbSDag-Erling Smørgrav.It Fl k 2206888a9beSDag-Erling SmørgravWhen loading keys into or deleting keys from the agent, process plain private 2216888a9beSDag-Erling Smørgravkeys only and skip certificates. 2225e8dbd04SDag-Erling Smørgrav.It Fl L 2235e8dbd04SDag-Erling SmørgravLists public key parameters of all identities currently represented 2245e8dbd04SDag-Erling Smørgravby the agent. 2255e8dbd04SDag-Erling Smørgrav.It Fl l 2265e8dbd04SDag-Erling SmørgravLists fingerprints of all identities currently represented by the agent. 2274f52dfbbSDag-Erling Smørgrav.It Fl q 2284f52dfbbSDag-Erling SmørgravBe quiet after a successful operation. 22919261079SEd Maste.It Fl S Ar provider 23019261079SEd MasteSpecifies a path to a library that will be used when adding 23119261079SEd MasteFIDO authenticator-hosted keys, overriding the default of using the 23219261079SEd Masteinternal USB HID support. 233b15c8340SDag-Erling Smørgrav.It Fl s Ar pkcs11 234b15c8340SDag-Erling SmørgravAdd keys provided by the PKCS#11 shared library 235b15c8340SDag-Erling Smørgrav.Ar pkcs11 . 236069ac184SEd MasteCertificate files may optionally be listed as command-line arguments. 237069ac184SEd MasteIf these are present, then they will be loaded into the agent using any 238069ac184SEd Mastecorresponding private keys loaded from the PKCS#11 token. 23919261079SEd Maste.It Fl T Ar pubkey ... 24019261079SEd MasteTests whether the private keys that correspond to the specified 24119261079SEd Maste.Ar pubkey 24219261079SEd Mastefiles are usable by performing sign and verify operations on each. 2435e8dbd04SDag-Erling Smørgrav.It Fl t Ar life 2445e8dbd04SDag-Erling SmørgravSet a maximum lifetime when adding identities to an agent. 2455e8dbd04SDag-Erling SmørgravThe lifetime may be specified in seconds or in a time format 2465e8dbd04SDag-Erling Smørgravspecified in 2475e8dbd04SDag-Erling Smørgrav.Xr sshd_config 5 . 24819261079SEd Maste.It Fl v 24919261079SEd MasteVerbose mode. 25019261079SEd MasteCauses 25119261079SEd Maste.Nm 25219261079SEd Masteto print debugging messages about its progress. 25319261079SEd MasteThis is helpful in debugging problems. 25419261079SEd MasteMultiple 25519261079SEd Maste.Fl v 25619261079SEd Masteoptions increase the verbosity. 25719261079SEd MasteThe maximum is 3. 2585e8dbd04SDag-Erling Smørgrav.It Fl X 2595e8dbd04SDag-Erling SmørgravUnlock the agent. 2605e8dbd04SDag-Erling Smørgrav.It Fl x 2615e8dbd04SDag-Erling SmørgravLock the agent with a password. 262511b41d2SMark Murray.El 263511b41d2SMark Murray.Sh ENVIRONMENT 264511b41d2SMark Murray.Bl -tag -width Ds 26519261079SEd Maste.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE" 266511b41d2SMark MurrayIf 267511b41d2SMark Murray.Nm 268511b41d2SMark Murrayneeds a passphrase, it will read the passphrase from the current 269a8f6863aSKris Kennawayterminal if it was run from a terminal. 270a8f6863aSKris KennawayIf 271511b41d2SMark Murray.Nm 272511b41d2SMark Murraydoes not have a terminal associated with it but 273511b41d2SMark Murray.Ev DISPLAY 274511b41d2SMark Murrayand 275511b41d2SMark Murray.Ev SSH_ASKPASS 276511b41d2SMark Murrayare set, it will execute the program specified by 277511b41d2SMark Murray.Ev SSH_ASKPASS 278557f75e5SDag-Erling Smørgrav(by default 279557f75e5SDag-Erling Smørgrav.Dq ssh-askpass ) 280a8f6863aSKris Kennawayand open an X11 window to read the passphrase. 281a8f6863aSKris KennawayThis is particularly useful when calling 282511b41d2SMark Murray.Nm 283511b41d2SMark Murrayfrom a 2845e8dbd04SDag-Erling Smørgrav.Pa .xsession 285a8f6863aSKris Kennawayor related script. 28619261079SEd Maste.Pp 28719261079SEd Maste.Ev SSH_ASKPASS_REQUIRE 28819261079SEd Masteallows further control over the use of an askpass program. 28919261079SEd MasteIf this variable is set to 29019261079SEd Maste.Dq never 29119261079SEd Mastethen 29219261079SEd Maste.Nm 29319261079SEd Mastewill never attempt to use one. 29419261079SEd MasteIf it is set to 29519261079SEd Maste.Dq prefer , 29619261079SEd Mastethen 29719261079SEd Maste.Nm 29819261079SEd Mastewill prefer to use the askpass program instead of the TTY when requesting 29919261079SEd Mastepasswords. 30019261079SEd MasteFinally, if the variable is set to 30119261079SEd Maste.Dq force , 30219261079SEd Mastethen the askpass program will be used for all passphrase input regardless 30319261079SEd Masteof whether 30419261079SEd Maste.Ev DISPLAY 30519261079SEd Masteis set. 306545d5ecaSDag-Erling Smørgrav.It Ev SSH_AUTH_SOCK 307b15c8340SDag-Erling SmørgravIdentifies the path of a 308b15c8340SDag-Erling Smørgrav.Ux Ns -domain 309b15c8340SDag-Erling Smørgravsocket used to communicate with the agent. 31019261079SEd Maste.It Ev SSH_SK_PROVIDER 31119261079SEd MasteSpecifies a path to a library that will be used when loading any 31219261079SEd MasteFIDO authenticator-hosted keys, overriding the default of using 31319261079SEd Mastethe built-in USB HID support. 314b66f2d16SKris Kennaway.El 315d95e11bfSDag-Erling Smørgrav.Sh FILES 31619261079SEd Maste.Bl -tag -width Ds -compact 317043840dfSDag-Erling Smørgrav.It Pa ~/.ssh/id_dsa 3184a421b63SDag-Erling Smørgrav.It Pa ~/.ssh/id_ecdsa 31919261079SEd Maste.It Pa ~/.ssh/id_ecdsa_sk 320f7167e0eSDag-Erling Smørgrav.It Pa ~/.ssh/id_ed25519 32119261079SEd Maste.It Pa ~/.ssh/id_ed25519_sk 322043840dfSDag-Erling Smørgrav.It Pa ~/.ssh/id_rsa 32319261079SEd MasteContains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 32419261079SEd Masteauthenticator-hosted Ed25519 or RSA authentication identity of the user. 325d95e11bfSDag-Erling Smørgrav.El 326d95e11bfSDag-Erling Smørgrav.Pp 327d95e11bfSDag-Erling SmørgravIdentity files should not be readable by anyone but the user. 328d95e11bfSDag-Erling SmørgravNote that 329d95e11bfSDag-Erling Smørgrav.Nm 330d95e11bfSDag-Erling Smørgravignores identity files if they are accessible by others. 3314a421b63SDag-Erling Smørgrav.Sh EXIT STATUS 332ae1f160dSDag-Erling SmørgravExit status is 0 on success, 1 if the specified command fails, 333ae1f160dSDag-Erling Smørgravand 2 if 334ae1f160dSDag-Erling Smørgrav.Nm 335ae1f160dSDag-Erling Smørgravis unable to contact the authentication agent. 336d95e11bfSDag-Erling Smørgrav.Sh SEE ALSO 337d95e11bfSDag-Erling Smørgrav.Xr ssh 1 , 338d95e11bfSDag-Erling Smørgrav.Xr ssh-agent 1 , 339557f75e5SDag-Erling Smørgrav.Xr ssh-askpass 1 , 340d95e11bfSDag-Erling Smørgrav.Xr ssh-keygen 1 , 341d95e11bfSDag-Erling Smørgrav.Xr sshd 8 3421e8db6e2SBrian Feldman.Sh AUTHORS 3431e8db6e2SBrian FeldmanOpenSSH is a derivative of the original and free 3441e8db6e2SBrian Feldmanssh 1.2.12 release by Tatu Ylonen. 3451e8db6e2SBrian FeldmanAaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 3461e8db6e2SBrian FeldmanTheo de Raadt and Dug Song 3471e8db6e2SBrian Feldmanremoved many bugs, re-added newer features and 3481e8db6e2SBrian Feldmancreated OpenSSH. 3491e8db6e2SBrian FeldmanMarkus Friedl contributed the support for SSH 3501e8db6e2SBrian Feldmanprotocol versions 1.5 and 2.0. 351