1.\" $NetBSD: ssh-add.1,v 1.15 2020/02/27 00:24:40 christos Exp $ 2.\" $OpenBSD: ssh-add.1,v 1.79 2020/02/07 03:57:31 djm 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 7 2020 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 S Ar provider 50.Op Fl t Ar life 51.Op Ar 52.Nm ssh-add 53.Fl s Ar pkcs11 54.Nm ssh-add 55.Fl e Ar pkcs11 56.Nm ssh-add 57.Fl T 58.Ar pubkey ... 59.Sh DESCRIPTION 60.Nm 61adds private key identities to the authentication agent, 62.Xr ssh-agent 1 . 63When run without arguments, it adds the files 64.Pa ~/.ssh/id_rsa , 65.Pa ~/.ssh/id_dsa , 66.Pa ~/.ssh/id_ecdsa , 67.Pa ~/.ssh/id_ecdsa_sk , 68.Pa ~/.ssh/id_ed25519 , 69and 70.Pa ~/.ssh/id_ed25519_sk . 71After loading a private key, 72.Nm 73will try to load corresponding certificate information from the 74filename obtained by appending 75.Pa -cert.pub 76to the name of the private key file. 77Alternative file names can be given on the command line. 78.Pp 79If any file requires a passphrase, 80.Nm 81asks for the passphrase from the user. 82The passphrase is read from the user's tty. 83.Nm 84retries the last passphrase if multiple identity files are given. 85.Pp 86The authentication agent must be running and the 87.Ev SSH_AUTH_SOCK 88environment variable must contain the name of its socket for 89.Nm 90to work. 91.Pp 92The options are as follows: 93.Bl -tag -width Ds 94.It Fl c 95Indicates that added identities should be subject to confirmation before 96being used for authentication. 97Confirmation is performed by 98.Xr ssh-askpass 1 . 99Successful confirmation is signaled by a zero exit status from 100.Xr ssh-askpass 1 , 101rather than text entered into the requester. 102.It Fl D 103Deletes all identities from the agent. 104.It Fl d 105Instead of adding identities, removes identities from the agent. 106If 107.Nm 108has been run without arguments, the keys for the default identities and 109their corresponding certificates will be removed. 110Otherwise, the argument list will be interpreted as a list of paths to 111public key files to specify keys and certificates to be removed from the agent. 112If no public key is found at a given path, 113.Nm 114will append 115.Pa .pub 116and retry. 117.It Fl E Ar fingerprint_hash 118Specifies the hash algorithm used when displaying key fingerprints. 119Valid options are: 120.Dq md5 121and 122.Dq sha256 . 123The default is 124.Dq sha256 . 125.It Fl e Ar pkcs11 126Remove keys provided by the PKCS#11 shared library 127.Ar pkcs11 . 128.It Fl K 129Load resident keys from a FIDO authenticator. 130.It Fl k 131When loading keys into or deleting keys from the agent, process plain private 132keys only and skip certificates. 133.It Fl L 134Lists public key parameters of all identities currently represented 135by the agent. 136.It Fl l 137Lists fingerprints of all identities currently represented by the agent. 138.It Fl q 139Be quiet after a successful operation. 140.It Fl S Ar provider 141Specifies a path to a library that will be used when adding 142FIDO authenticator-hosted keys, overriding the default of using the 143internal USB HID support. 144.It Fl s Ar pkcs11 145Add keys provided by the PKCS#11 shared library 146.Ar pkcs11 . 147.It Fl T Ar pubkey ... 148Tests whether the private keys that correspond to the specified 149.Ar pubkey 150files are usable by performing sign and verify operations on each. 151.It Fl t Ar life 152Set a maximum lifetime when adding identities to an agent. 153The lifetime may be specified in seconds or in a time format 154specified in 155.Xr sshd_config 5 . 156.It Fl v 157Verbose mode. 158Causes 159.Nm 160to print debugging messages about its progress. 161This is helpful in debugging problems. 162Multiple 163.Fl v 164options increase the verbosity. 165The maximum is 3. 166.It Fl X 167Unlock the agent. 168.It Fl x 169Lock the agent with a password. 170.El 171.Sh ENVIRONMENT 172.Bl -tag -width Ds 173.It Ev "DISPLAY" and "SSH_ASKPASS" 174If 175.Nm 176needs a passphrase, it will read the passphrase from the current 177terminal if it was run from a terminal. 178If 179.Nm 180does not have a terminal associated with it but 181.Ev DISPLAY 182and 183.Ev SSH_ASKPASS 184are set, it will execute the program specified by 185.Ev SSH_ASKPASS 186(by default 187.Dq ssh-askpass ) 188and open an X11 window to read the passphrase. 189This is particularly useful when calling 190.Nm 191from a 192.Pa .xsession 193or related script. 194(Note that on some machines it 195may be necessary to redirect the input from 196.Pa /dev/null 197to make this work.) 198.It Ev SSH_AUTH_SOCK 199Identifies the path of a 200.Ux Ns -domain 201socket used to communicate with the agent. 202.It Ev SSH_SK_PROVIDER 203Specifies a path to a library that will be used when loading any 204FIDO authenticator-hosted keys, overriding the default of using 205the built-in USB HID support. 206.El 207.Sh FILES 208.Bl -tag -width Ds -compact 209.It Pa ~/.ssh/id_dsa 210.It Pa ~/.ssh/id_ecdsa 211.It Pa ~/.ssh/id_ecdsa_sk 212.It Pa ~/.ssh/id_ed25519 213.It Pa ~/.ssh/id_ed25519_sk 214.It Pa ~/.ssh/id_rsa 215Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 216authenticator-hosted Ed25519 or RSA authentication identity of the user. 217.El 218.Pp 219Identity files should not be readable by anyone but the user. 220Note that 221.Nm 222ignores identity files if they are accessible by others. 223.Sh EXIT STATUS 224Exit status is 0 on success, 1 if the specified command fails, 225and 2 if 226.Nm 227is unable to contact the authentication agent. 228.Sh SEE ALSO 229.Xr ssh 1 , 230.Xr ssh-agent 1 , 231.Xr ssh-askpass 1 , 232.Xr ssh-keygen 1 , 233.Xr sshd 8 234.Sh AUTHORS 235OpenSSH is a derivative of the original and free 236ssh 1.2.12 release by Tatu Ylonen. 237Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 238Theo de Raadt and Dug Song 239removed many bugs, re-added newer features and 240created OpenSSH. 241Markus Friedl contributed the support for SSH 242protocol versions 1.5 and 2.0. 243