crypto/openssh/ssh-add.1

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