|
- .\" $OpenBSD: ssh-add.1,v 1.86 2023/12/19 06:57:34 jmc Exp $
- .\"
- .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
- .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
- .\" All rights reserved
- .\"
- .\" As far as I am concerned, the code I have written for this software
- .\" can be used freely for any purpose. Any derived versions of this
- .\" software must be clearly marked as such, and if the derived work is
- .\" incompatible with the protocol description in the RFC file, it must be
- .\" called by a name other than "ssh" or "Secure Shell".
- .\"
- .\"
- .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
- .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
- .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- .\"
- .Dd $Mdocdate: December 19 2023 $
- .Dt SSH-ADD 1
- .Os
- .Sh NAME
- .Nm ssh-add
- .Nd adds private key identities to the OpenSSH authentication agent
- .Sh SYNOPSIS
- .Nm ssh-add
- .Op Fl CcDdKkLlqvXx
- .Op Fl E Ar fingerprint_hash
- .Op Fl H Ar hostkey_file
- .Op Fl h Ar destination_constraint
- .Op Fl S Ar provider
- .Op Fl t Ar life
- .Op Ar
- .Nm ssh-add
- .Fl s Ar pkcs11
- .Op Fl Cv
- .Op Ar certificate ...
- .Nm ssh-add
- .Fl e Ar pkcs11
- .Nm ssh-add
- .Fl T
- .Ar pubkey ...
- .Sh DESCRIPTION
- .Nm
- adds private key identities to the authentication agent,
- .Xr ssh-agent 1 .
- When run without arguments, it adds the files
- .Pa ~/.ssh/id_rsa ,
- .Pa ~/.ssh/id_ecdsa ,
- .Pa ~/.ssh/id_ecdsa_sk ,
- .Pa ~/.ssh/id_ed25519 ,
- .Pa ~/.ssh/id_ed25519_sk ,
- and
- .Pa ~/.ssh/id_dsa .
- After loading a private key,
- .Nm
- will try to load corresponding certificate information from the
- filename obtained by appending
- .Pa -cert.pub
- to the name of the private key file.
- Alternative file names can be given on the command line.
- .Pp
- If any file requires a passphrase,
- .Nm
- asks for the passphrase from the user.
- The passphrase is read from the user's tty.
- .Nm
- retries the last passphrase if multiple identity files are given.
- .Pp
- The authentication agent must be running and the
- .Ev SSH_AUTH_SOCK
- environment variable must contain the name of its socket for
- .Nm
- to work.
- .Pp
- The options are as follows:
- .Bl -tag -width Ds
- .It Fl C
- When loading keys into or deleting keys from the agent, process
- certificates only and skip plain keys.
- .It Fl c
- Indicates that added identities should be subject to confirmation before
- being used for authentication.
- Confirmation is performed by
- .Xr ssh-askpass 1 .
- Successful confirmation is signaled by a zero exit status from
- .Xr ssh-askpass 1 ,
- rather than text entered into the requester.
- .It Fl D
- Deletes all identities from the agent.
- .It Fl d
- Instead of adding identities, removes identities from the agent.
- If
- .Nm
- has been run without arguments, the keys for the default identities and
- their corresponding certificates will be removed.
- Otherwise, the argument list will be interpreted as a list of paths to
- public key files to specify keys and certificates to be removed from the agent.
- If no public key is found at a given path,
- .Nm
- will append
- .Pa .pub
- and retry.
- If the argument list consists of
- .Dq -
- then
- .Nm
- will read public keys to be removed from standard input.
- .It Fl E Ar fingerprint_hash
- Specifies the hash algorithm used when displaying key fingerprints.
- Valid options are:
- .Dq md5
- and
- .Dq sha256 .
- The default is
- .Dq sha256 .
- .It Fl e Ar pkcs11
- Remove keys provided by the PKCS#11 shared library
- .Ar pkcs11 .
- .It Fl H Ar hostkey_file
- Specifies a known hosts file to look up hostkeys when using
- destination-constrained keys via the
- .Fl h
- flag.
- This option may be specified multiple times to allow multiple files to be
- searched.
- If no files are specified,
- .Nm
- will use the default
- .Xr ssh_config 5
- known hosts files:
- .Pa ~/.ssh/known_hosts ,
- .Pa ~/.ssh/known_hosts2 ,
- .Pa /etc/ssh/ssh_known_hosts ,
- and
- .Pa /etc/ssh/ssh_known_hosts2 .
- .It Fl h Ar destination_constraint
- When adding keys, constrain them to be usable only through specific hosts or to
- specific destinations.
- .Pp
- Destination constraints of the form
- .Sq [user@]dest-hostname
- permit use of the key only from the origin host (the one running
- .Xr ssh-agent 1 )
- to the listed destination host, with optional user name.
- .Pp
- Constraints of the form
- .Sq src-hostname>[user@]dst-hostname
- allow a key available on a forwarded
- .Xr ssh-agent 1
- to be used through a particular host (as specified by
- .Sq src-hostname )
- to authenticate to a further host,
- specified by
- .Sq dst-hostname .
- .Pp
- Multiple destination constraints may be added when loading keys.
- When attempting authentication with a key that has destination constraints,
- the whole connection path, including
- .Xr ssh-agent 1
- forwarding, is tested against those constraints and each
- hop must be permitted for the attempt to succeed.
- For example, if key is forwarded to a remote host,
- .Sq host-b ,
- and is attempting authentication to another host,
- .Sq host-c ,
- then the operation will be successful only if
- .Sq host-b
- was permitted from the origin host and the subsequent
- .Sq host-b>host-c
- hop is also permitted by destination constraints.
- .Pp
- Hosts are identified by their host keys, and are looked up from known hosts
- files by
- .Nm .
- Wildcards patterns may be used for hostnames and certificate host
- keys are supported.
- By default, keys added by
- .Nm
- are not destination constrained.
- .Pp
- Destination constraints were added in OpenSSH release 8.9.
- Support in both the remote SSH client and server is required when using
- destination-constrained keys over a forwarded
- .Xr ssh-agent 1
- channel.
- .Pp
- It is also important to note that destination constraints can only be
- enforced by
- .Xr ssh-agent 1
- when a key is used, or when it is forwarded by a
- .Sy cooperating
- .Xr ssh 1 .
- Specifically, it does not prevent an attacker with access to a remote
- .Ev SSH_AUTH_SOCK
- from forwarding it again and using it on a different host (but only to
- a permitted destination).
- .It Fl K
- Load resident keys from a FIDO authenticator.
- .It Fl k
- When loading keys into or deleting keys from the agent, process plain private
- keys only and skip certificates.
- .It Fl L
- Lists public key parameters of all identities currently represented
- by the agent.
- .It Fl l
- Lists fingerprints of all identities currently represented by the agent.
- .It Fl q
- Be quiet after a successful operation.
- .It Fl S Ar provider
- Specifies a path to a library that will be used when adding
- FIDO authenticator-hosted keys, overriding the default of using the
- internal USB HID support.
- .It Fl s Ar pkcs11
- Add keys provided by the PKCS#11 shared library
- .Ar pkcs11 .
- Certificate files may optionally be listed as command-line arguments.
- If these are present, then they will be loaded into the agent using any
- corresponding private keys loaded from the PKCS#11 token.
- .It Fl T Ar pubkey ...
- Tests whether the private keys that correspond to the specified
- .Ar pubkey
- files are usable by performing sign and verify operations on each.
- .It Fl t Ar life
- Set a maximum lifetime when adding identities to an agent.
- The lifetime may be specified in seconds or in a time format
- specified in
- .Xr sshd_config 5 .
- .It Fl v
- Verbose mode.
- Causes
- .Nm
- to print debugging messages about its progress.
- This is helpful in debugging problems.
- Multiple
- .Fl v
- options increase the verbosity.
- The maximum is 3.
- .It Fl X
- Unlock the agent.
- .It Fl x
- Lock the agent with a password.
- .El
- .Sh ENVIRONMENT
- .Bl -tag -width Ds
- .It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
- If
- .Nm
- needs a passphrase, it will read the passphrase from the current
- terminal if it was run from a terminal.
- If
- .Nm
- does not have a terminal associated with it but
- .Ev DISPLAY
- and
- .Ev SSH_ASKPASS
- are set, it will execute the program specified by
- .Ev SSH_ASKPASS
- (by default
- .Dq ssh-askpass )
- and open an X11 window to read the passphrase.
- This is particularly useful when calling
- .Nm
- from a
- .Pa .xsession
- or related script.
- .Pp
- .Ev SSH_ASKPASS_REQUIRE
- allows further control over the use of an askpass program.
- If this variable is set to
- .Dq never
- then
- .Nm
- will never attempt to use one.
- If it is set to
- .Dq prefer ,
- then
- .Nm
- will prefer to use the askpass program instead of the TTY when requesting
- passwords.
- Finally, if the variable is set to
- .Dq force ,
- then the askpass program will be used for all passphrase input regardless
- of whether
- .Ev DISPLAY
- is set.
- .It Ev SSH_AUTH_SOCK
- Identifies the path of a
- .Ux Ns -domain
- socket used to communicate with the agent.
- .It Ev SSH_SK_PROVIDER
- Specifies a path to a library that will be used when loading any
- FIDO authenticator-hosted keys, overriding the default of using
- the built-in USB HID support.
- .El
- .Sh FILES
- .Bl -tag -width Ds -compact
- .It Pa ~/.ssh/id_dsa
- .It Pa ~/.ssh/id_ecdsa
- .It Pa ~/.ssh/id_ecdsa_sk
- .It Pa ~/.ssh/id_ed25519
- .It Pa ~/.ssh/id_ed25519_sk
- .It Pa ~/.ssh/id_rsa
- Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
- authenticator-hosted Ed25519 or RSA authentication identity of the user.
- .El
- .Pp
- Identity files should not be readable by anyone but the user.
- Note that
- .Nm
- ignores identity files if they are accessible by others.
- .Sh EXIT STATUS
- Exit status is 0 on success, 1 if the specified command fails,
- and 2 if
- .Nm
- is unable to contact the authentication agent.
- .Sh SEE ALSO
- .Xr ssh 1 ,
- .Xr ssh-agent 1 ,
- .Xr ssh-askpass 1 ,
- .Xr ssh-keygen 1 ,
- .Xr sshd 8
- .Sh AUTHORS
- OpenSSH is a derivative of the original and free
- ssh 1.2.12 release by Tatu Ylonen.
- Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
- Theo de Raadt and Dug Song
- removed many bugs, re-added newer features and
- created OpenSSH.
- Markus Friedl contributed the support for SSH
- protocol versions 1.5 and 2.0.
|