crypto/openssh/ssh-add.1

   1 .\"     $OpenBSD: ssh-add.1,v 1.85 2023/12/18 14:46:56 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: December 18 2023 $
  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 cCDdKkLlqvXx
  47 .Op Fl E Ar fingerprint_hash
  48 .Op Fl H Ar hostkey_file
  49 .Op Fl h Ar destination_constraint
  50 .Op Fl S Ar provider
  51 .Op Fl t Ar life
  52 .Op Ar
  53 .Nm ssh-add
  54 .Fl s Ar pkcs11
  55 .Op Fl vC
  56 .Op Ar certificate ...
  57 .Nm ssh-add
  58 .Fl e Ar pkcs11
  59 .Nm ssh-add
  60 .Fl T
  61 .Ar pubkey ...
  62 .Sh DESCRIPTION
  63 .Nm
  64 adds private key identities to the authentication agent,
  65 .Xr ssh-agent 1 .
  66 When run without arguments, it adds the files
  67 .Pa ~/.ssh/id_rsa ,
  68 .Pa ~/.ssh/id_ecdsa ,
  69 .Pa ~/.ssh/id_ecdsa_sk ,
  70 .Pa ~/.ssh/id_ed25519 ,
  71 .Pa ~/.ssh/id_ed25519_sk ,
  72 and
  73 .Pa ~/.ssh/id_dsa .
  74 After loading a private key,
  75 .Nm
  76 will try to load corresponding certificate information from the
  77 filename obtained by appending
  78 .Pa -cert.pub
  79 to the name of the private key file.
  80 Alternative file names can be given on the command line.
  81 .Pp
  82 If any file requires a passphrase,
  83 .Nm
  84 asks for the passphrase from the user.
  85 The passphrase is read from the user's tty.
  86 .Nm
  87 retries the last passphrase if multiple identity files are given.
  88 .Pp
  89 The authentication agent must be running and the
  90 .Ev SSH_AUTH_SOCK
  91 environment variable must contain the name of its socket for
  92 .Nm
  93 to work.
  94 .Pp
  95 The options are as follows:
  96 .Bl -tag -width Ds
  97 .It Fl c
  98 Indicates that added identities should be subject to confirmation before
  99 being used for authentication.
 100 Confirmation is performed by
 101 .Xr ssh-askpass 1 .
 102 Successful confirmation is signaled by a zero exit status from
 103 .Xr ssh-askpass 1 ,
 104 rather than text entered into the requester.
 105 .It Fl C
 106 When loading keys into or deleting keys from the agent, process
 107 certificates only and skip plain keys.
 108 .It Fl D
 109 Deletes all identities from the agent.
 110 .It Fl d
 111 Instead of adding identities, removes identities from the agent.
 112 If
 113 .Nm
 114 has been run without arguments, the keys for the default identities and
 115 their corresponding certificates will be removed.
 116 Otherwise, the argument list will be interpreted as a list of paths to
 117 public key files to specify keys and certificates to be removed from the agent.
 118 If no public key is found at a given path,
 119 .Nm
 120 will append
 121 .Pa .pub
 122 and retry.
 123 If the argument list consists of
 124 .Dq -
 125 then
 126 .Nm
 127 will read public keys to be removed from standard input.
 128 .It Fl E Ar fingerprint_hash
 129 Specifies the hash algorithm used when displaying key fingerprints.
 130 Valid options are:
 131 .Dq md5
 132 and
 133 .Dq sha256 .
 134 The default is
 135 .Dq sha256 .
 136 .It Fl e Ar pkcs11
 137 Remove keys provided by the PKCS#11 shared library
 138 .Ar pkcs11 .
 139 .It Fl H Ar hostkey_file
 140 Specifies a known hosts file to look up hostkeys when using
 141 destination-constrained keys via the
 142 .Fl h
 143 flag.
 144 This option may be specified multiple times to allow multiple files to be
 145 searched.
 146 If no files are specified,
 147 .Nm
 148 will use the default
 149 .Xr ssh_config 5
 150 known hosts files:
 151 .Pa ~/.ssh/known_hosts ,
 152 .Pa ~/.ssh/known_hosts2 ,
 153 .Pa /etc/ssh/ssh_known_hosts ,
 154 and
 155 .Pa /etc/ssh/ssh_known_hosts2 .
 156 .It Fl h Ar destination_constraint
 157 When adding keys, constrain them to be usable only through specific hosts or to
 158 specific destinations.
 159 .Pp
 160 Destination constraints of the form
 161 .Sq [user@]dest-hostname
 162 permit use of the key only from the origin host (the one running
 163 .Xr ssh-agent 1 )
 164 to the listed destination host, with optional user name.
 165 .Pp
 166 Constraints of the form
 167 .Sq src-hostname>[user@]dst-hostname
 168 allow a key available on a forwarded
 169 .Xr ssh-agent 1
 170 to be used through a particular host (as specified by
 171 .Sq src-hostname )
 172 to authenticate to a further host,
 173 specified by
 174 .Sq dst-hostname .
 175 .Pp
 176 Multiple destination constraints may be added when loading keys.
 177 When attempting authentication with a key that has destination constraints,
 178 the whole connection path, including
 179 .Xr ssh-agent 1
 180 forwarding, is tested against those constraints and each
 181 hop must be permitted for the attempt to succeed.
 182 For example, if key is forwarded to a remote host,
 183 .Sq host-b ,
 184 and is attempting authentication to another host,
 185 .Sq host-c ,
 186 then the operation will be successful only if
 187 .Sq host-b
 188 was permitted from the origin host and the subsequent
 189 .Sq host-b>host-c
 190 hop is also permitted by destination constraints.
 191 .Pp
 192 Hosts are identified by their host keys, and are looked up from known hosts
 193 files by
 194 .Nm .
 195 Wildcards patterns may be used for hostnames and certificate host
 196 keys are supported.
 197 By default, keys added by
 198 .Nm
 199 are not destination constrained.
 200 .Pp
 201 Destination constraints were added in OpenSSH release 8.9.
 202 Support in both the remote SSH client and server is required when using
 203 destination-constrained keys over a forwarded
 204 .Xr ssh-agent 1
 205 channel.
 206 .Pp
 207 It is also important to note that destination constraints can only be
 208 enforced by
 209 .Xr ssh-agent 1
 210 when a key is used, or when it is forwarded by a
 211 .Sy cooperating
 212 .Xr ssh 1 .
 213 Specifically, it does not prevent an attacker with access to a remote
 214 .Ev SSH_AUTH_SOCK
 215 from forwarding it again and using it on a different host (but only to
 216 a permitted destination).
 217 .It Fl K
 218 Load resident keys from a FIDO authenticator.
 219 .It Fl k
 220 When loading keys into or deleting keys from the agent, process plain private
 221 keys only and skip certificates.
 222 .It Fl L
 223 Lists public key parameters of all identities currently represented
 224 by the agent.
 225 .It Fl l
 226 Lists fingerprints of all identities currently represented by the agent.
 227 .It Fl q
 228 Be quiet after a successful operation.
 229 .It Fl S Ar provider
 230 Specifies a path to a library that will be used when adding
 231 FIDO authenticator-hosted keys, overriding the default of using the
 232 internal USB HID support.
 233 .It Fl s Ar pkcs11
 234 Add keys provided by the PKCS#11 shared library
 235 .Ar pkcs11 .
 236 Certificate files may optionally be listed as command-line arguments.
 237 If these are present, then they will be loaded into the agent using any
 238 corresponding private keys loaded from the PKCS#11 token.
 239 .It Fl T Ar pubkey ...
 240 Tests whether the private keys that correspond to the specified
 241 .Ar pubkey
 242 files are usable by performing sign and verify operations on each.
 243 .It Fl t Ar life
 244 Set a maximum lifetime when adding identities to an agent.
 245 The lifetime may be specified in seconds or in a time format
 246 specified in
 247 .Xr sshd_config 5 .
 248 .It Fl v
 249 Verbose mode.
 250 Causes
 251 .Nm
 252 to print debugging messages about its progress.
 253 This is helpful in debugging problems.
 254 Multiple
 255 .Fl v
 256 options increase the verbosity.
 257 The maximum is 3.
 258 .It Fl X
 259 Unlock the agent.
 260 .It Fl x
 261 Lock the agent with a password.
 262 .El
 263 .Sh ENVIRONMENT
 264 .Bl -tag -width Ds
 265 .It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
 266 If
 267 .Nm
 268 needs a passphrase, it will read the passphrase from the current
 269 terminal if it was run from a terminal.
 270 If
 271 .Nm
 272 does not have a terminal associated with it but
 273 .Ev DISPLAY
 274 and
 275 .Ev SSH_ASKPASS
 276 are set, it will execute the program specified by
 277 .Ev SSH_ASKPASS
 278 (by default
 279 .Dq ssh-askpass )
 280 and open an X11 window to read the passphrase.
 281 This is particularly useful when calling
 282 .Nm
 283 from a
 284 .Pa .xsession
 285 or related script.
 286 .Pp
 287 .Ev SSH_ASKPASS_REQUIRE
 288 allows further control over the use of an askpass program.
 289 If this variable is set to
 290 .Dq never
 291 then
 292 .Nm
 293 will never attempt to use one.
 294 If it is set to
 295 .Dq prefer ,
 296 then
 297 .Nm
 298 will prefer to use the askpass program instead of the TTY when requesting
 299 passwords.
 300 Finally, if the variable is set to
 301 .Dq force ,
 302 then the askpass program will be used for all passphrase input regardless
 303 of whether
 304 .Ev DISPLAY
 305 is set.
 306 .It Ev SSH_AUTH_SOCK
 307 Identifies the path of a
 308 .Ux Ns -domain
 309 socket used to communicate with the agent.
 310 .It Ev SSH_SK_PROVIDER
 311 Specifies a path to a library that will be used when loading any
 312 FIDO authenticator-hosted keys, overriding the default of using
 313 the built-in USB HID support.
 314 .El
 315 .Sh FILES
 316 .Bl -tag -width Ds -compact
 317 .It Pa ~/.ssh/id_dsa
 318 .It Pa ~/.ssh/id_ecdsa
 319 .It Pa ~/.ssh/id_ecdsa_sk
 320 .It Pa ~/.ssh/id_ed25519
 321 .It Pa ~/.ssh/id_ed25519_sk
 322 .It Pa ~/.ssh/id_rsa
 323 Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
 324 authenticator-hosted Ed25519 or RSA authentication identity of the user.
 325 .El
 326 .Pp
 327 Identity files should not be readable by anyone but the user.
 328 Note that
 329 .Nm
 330 ignores identity files if they are accessible by others.
 331 .Sh EXIT STATUS
 332 Exit status is 0 on success, 1 if the specified command fails,
 333 and 2 if
 334 .Nm
 335 is unable to contact the authentication agent.
 336 .Sh SEE ALSO
 337 .Xr ssh 1 ,
 338 .Xr ssh-agent 1 ,
 339 .Xr ssh-askpass 1 ,
 340 .Xr ssh-keygen 1 ,
 341 .Xr sshd 8
 342 .Sh AUTHORS
 343 OpenSSH is a derivative of the original and free
 344 ssh 1.2.12 release by Tatu Ylonen.
 345 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
 346 Theo de Raadt and Dug Song
 347 removed many bugs, re-added newer features and
 348 created OpenSSH.
 349 Markus Friedl contributed the support for SSH
 350 protocol versions 1.5 and 2.0.