2024-06-17 01:30:29 -07:00
|
|
|
.\" $OpenBSD: ssh-add.1,v 1.87 2024/06/17 08:30:29 djm Exp $
|
1999-09-26 13:53:32 -07:00
|
|
|
.\"
|
|
|
|
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
|
|
|
|
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
|
|
|
|
.\" All rights reserved
|
|
|
|
.\"
|
2000-09-07 13:27:48 -07:00
|
|
|
.\" 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".
|
|
|
|
.\"
|
|
|
|
.\"
|
2001-03-02 10:54:30 -08:00
|
|
|
.\" 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.
|
2000-09-07 13:27:48 -07:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
1999-09-26 13:53:32 -07:00
|
|
|
.\"
|
2000-09-07 13:27:48 -07:00
|
|
|
.\" 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.
|
1999-09-26 13:53:32 -07:00
|
|
|
.\"
|
2024-06-17 01:30:29 -07:00
|
|
|
.Dd $Mdocdate: June 17 2024 $
|
1999-09-26 15:30:06 -07:00
|
|
|
.Dt SSH-ADD 1
|
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm ssh-add
|
2019-11-29 23:07:59 -08:00
|
|
|
.Nd adds private key identities to the OpenSSH authentication agent
|
1999-09-26 15:30:06 -07:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm ssh-add
|
2023-12-18 22:57:34 -08:00
|
|
|
.Op Fl CcDdKkLlqvXx
|
2014-12-21 14:27:55 -08:00
|
|
|
.Op Fl E Ar fingerprint_hash
|
2021-12-19 14:14:12 -08:00
|
|
|
.Op Fl H Ar hostkey_file
|
|
|
|
.Op Fl h Ar destination_constraint
|
2021-12-21 22:56:41 -08:00
|
|
|
.Op Fl S Ar provider
|
|
|
|
.Op Fl t Ar life
|
1999-09-26 15:30:06 -07:00
|
|
|
.Op Ar
|
2001-08-03 03:31:19 -07:00
|
|
|
.Nm ssh-add
|
2010-02-08 14:03:05 -08:00
|
|
|
.Fl s Ar pkcs11
|
2023-12-18 22:57:34 -08:00
|
|
|
.Op Fl Cv
|
2023-12-18 06:46:56 -08:00
|
|
|
.Op Ar certificate ...
|
2001-08-03 03:31:19 -07:00
|
|
|
.Nm ssh-add
|
2010-02-08 14:03:05 -08:00
|
|
|
.Fl e Ar pkcs11
|
2019-01-20 14:03:29 -08:00
|
|
|
.Nm ssh-add
|
|
|
|
.Fl T
|
2019-01-20 23:09:10 -08:00
|
|
|
.Ar pubkey ...
|
2000-04-12 14:47:47 -07:00
|
|
|
.Sh DESCRIPTION
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
2010-08-31 04:54:45 -07:00
|
|
|
adds private key identities to the authentication agent,
|
1999-09-26 15:30:06 -07:00
|
|
|
.Xr ssh-agent 1 .
|
2001-12-21 02:06:43 -08:00
|
|
|
When run without arguments, it adds the files
|
2005-04-20 23:17:50 -07:00
|
|
|
.Pa ~/.ssh/id_rsa ,
|
2013-12-07 03:58:46 -08:00
|
|
|
.Pa ~/.ssh/id_ecdsa ,
|
2019-11-07 00:38:38 -08:00
|
|
|
.Pa ~/.ssh/id_ecdsa_sk ,
|
2024-06-17 01:30:29 -07:00
|
|
|
.Pa ~/.ssh/id_ed25519
|
2001-12-21 02:06:43 -08:00
|
|
|
and
|
2024-06-17 01:30:29 -07:00
|
|
|
.Pa ~/.ssh/id_ed25519_sk .
|
2010-03-05 02:28:21 -08:00
|
|
|
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.
|
2000-03-23 13:10:09 -08:00
|
|
|
Alternative file names can be given on the command line.
|
2010-03-05 02:28:21 -08:00
|
|
|
.Pp
|
2000-03-23 13:10:09 -08:00
|
|
|
If any file requires a passphrase,
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
2000-04-12 14:47:47 -07:00
|
|
|
asks for the passphrase from the user.
|
2001-05-05 06:42:51 -07:00
|
|
|
The passphrase is read from the user's tty.
|
2001-04-09 08:19:49 -07:00
|
|
|
.Nm
|
|
|
|
retries the last passphrase if multiple identity files are given.
|
1999-09-26 15:30:06 -07:00
|
|
|
.Pp
|
2003-11-25 15:10:08 -08:00
|
|
|
The authentication agent must be running and the
|
|
|
|
.Ev SSH_AUTH_SOCK
|
|
|
|
environment variable must contain the name of its socket for
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
1999-09-26 13:53:32 -07:00
|
|
|
to work.
|
1999-09-26 15:30:06 -07:00
|
|
|
.Pp
|
|
|
|
The options are as follows:
|
|
|
|
.Bl -tag -width Ds
|
2023-12-18 22:57:34 -08:00
|
|
|
.It Fl C
|
|
|
|
When loading keys into or deleting keys from the agent, process
|
|
|
|
certificates only and skip plain keys.
|
2003-01-23 05:50:27 -08:00
|
|
|
.It Fl c
|
|
|
|
Indicates that added identities should be subject to confirmation before
|
2003-03-28 02:11:43 -08:00
|
|
|
being used for authentication.
|
2015-03-30 11:28:37 -07:00
|
|
|
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.
|
2005-03-01 09:32:19 -08:00
|
|
|
.It Fl D
|
|
|
|
Deletes all identities from the agent.
|
|
|
|
.It Fl d
|
2007-06-12 06:41:03 -07:00
|
|
|
Instead of adding identities, removes identities from the agent.
|
2007-06-12 00:41:00 -07:00
|
|
|
If
|
|
|
|
.Nm
|
2012-12-02 12:42:15 -08:00
|
|
|
has been run without arguments, the keys for the default identities and
|
2012-12-03 00:33:02 -08:00
|
|
|
their corresponding certificates will be removed.
|
2007-06-12 00:41:00 -07:00
|
|
|
Otherwise, the argument list will be interpreted as a list of paths to
|
2012-12-02 12:42:15 -08:00
|
|
|
public key files to specify keys and certificates to be removed from the agent.
|
2007-06-12 00:41:00 -07:00
|
|
|
If no public key is found at a given path,
|
|
|
|
.Nm
|
|
|
|
will append
|
|
|
|
.Pa .pub
|
|
|
|
and retry.
|
2020-06-25 22:04:07 -07:00
|
|
|
If the argument list consists of
|
|
|
|
.Dq -
|
|
|
|
then
|
|
|
|
.Nm
|
|
|
|
will read public keys to be removed from standard input.
|
2014-12-21 14:27:55 -08:00
|
|
|
.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 .
|
2010-02-08 02:50:20 -08:00
|
|
|
.It Fl e Ar pkcs11
|
2010-02-10 15:20:38 -08:00
|
|
|
Remove keys provided by the PKCS#11 shared library
|
2010-02-08 02:50:20 -08:00
|
|
|
.Ar pkcs11 .
|
2021-12-19 14:14:12 -08:00
|
|
|
.It Fl H Ar hostkey_file
|
2021-12-21 22:56:41 -08:00
|
|
|
Specifies a known hosts file to look up hostkeys when using
|
|
|
|
destination-constrained keys via the
|
2021-12-19 14:14:12 -08:00
|
|
|
.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).
|
2020-01-17 12:13:47 -08:00
|
|
|
.It Fl K
|
|
|
|
Load resident keys from a FIDO authenticator.
|
2011-10-17 22:00:48 -07:00
|
|
|
.It Fl k
|
2012-12-02 12:42:15 -08:00
|
|
|
When loading keys into or deleting keys from the agent, process plain private
|
|
|
|
keys only and skip certificates.
|
2005-03-01 09:32:19 -08:00
|
|
|
.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.
|
2017-08-29 06:05:58 -07:00
|
|
|
.It Fl q
|
|
|
|
Be quiet after a successful operation.
|
2019-10-31 14:19:56 -07:00
|
|
|
.It Fl S Ar provider
|
2019-12-21 12:22:34 -08:00
|
|
|
Specifies a path to a library that will be used when adding
|
|
|
|
FIDO authenticator-hosted keys, overriding the default of using the
|
2019-11-15 03:16:28 -08:00
|
|
|
internal USB HID support.
|
2019-10-31 17:52:35 -07:00
|
|
|
.It Fl s Ar pkcs11
|
|
|
|
Add keys provided by the PKCS#11 shared library
|
|
|
|
.Ar pkcs11 .
|
2023-12-18 06:46:56 -08:00
|
|
|
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.
|
2019-01-20 23:09:10 -08:00
|
|
|
.It Fl T Ar pubkey ...
|
2019-01-20 14:03:29 -08:00
|
|
|
Tests whether the private keys that correspond to the specified
|
|
|
|
.Ar pubkey
|
|
|
|
files are usable by performing sign and verify operations on each.
|
2005-03-01 09:32:19 -08:00
|
|
|
.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 .
|
2019-01-21 04:53:35 -08:00
|
|
|
.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.
|
2005-03-01 09:32:19 -08:00
|
|
|
.It Fl X
|
|
|
|
Unlock the agent.
|
|
|
|
.It Fl x
|
|
|
|
Lock the agent with a password.
|
1999-09-26 15:30:06 -07:00
|
|
|
.El
|
1999-12-02 12:05:40 -08:00
|
|
|
.Sh ENVIRONMENT
|
|
|
|
.Bl -tag -width Ds
|
2020-07-14 16:57:01 -07:00
|
|
|
.It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
|
1999-09-26 13:53:32 -07:00
|
|
|
If
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
1999-09-26 13:53:32 -07:00
|
|
|
needs a passphrase, it will read the passphrase from the current
|
2000-03-23 13:10:09 -08:00
|
|
|
terminal if it was run from a terminal.
|
|
|
|
If
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
1999-09-26 13:53:32 -07:00
|
|
|
does not have a terminal associated with it but
|
1999-09-26 15:30:06 -07:00
|
|
|
.Ev DISPLAY
|
1999-11-24 08:13:45 -08:00
|
|
|
and
|
|
|
|
.Ev SSH_ASKPASS
|
|
|
|
are set, it will execute the program specified by
|
|
|
|
.Ev SSH_ASKPASS
|
2015-03-30 11:28:37 -07:00
|
|
|
(by default
|
|
|
|
.Dq ssh-askpass )
|
2000-03-23 13:10:09 -08:00
|
|
|
and open an X11 window to read the passphrase.
|
|
|
|
This is particularly useful when calling
|
1999-09-26 15:30:06 -07:00
|
|
|
.Nm
|
|
|
|
from a
|
2004-08-30 14:22:49 -07:00
|
|
|
.Pa .xsession
|
2000-03-23 13:10:09 -08:00
|
|
|
or related script.
|
2020-07-14 16:57:01 -07:00
|
|
|
.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.
|
2002-06-05 09:35:45 -07:00
|
|
|
.It Ev SSH_AUTH_SOCK
|
2009-10-22 05:35:53 -07:00
|
|
|
Identifies the path of a
|
2009-10-22 08:02:12 -07:00
|
|
|
.Ux Ns -domain
|
|
|
|
socket used to communicate with the agent.
|
2019-10-31 14:19:56 -07:00
|
|
|
.It Ev SSH_SK_PROVIDER
|
2020-02-06 19:57:31 -08:00
|
|
|
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.
|
2000-09-03 08:23:28 -07:00
|
|
|
.El
|
2003-06-10 02:12:09 -07:00
|
|
|
.Sh FILES
|
2019-12-21 12:22:34 -08:00
|
|
|
.Bl -tag -width Ds -compact
|
2010-08-31 04:54:45 -07:00
|
|
|
.It Pa ~/.ssh/id_ecdsa
|
2019-11-07 00:38:38 -08:00
|
|
|
.It Pa ~/.ssh/id_ecdsa_sk
|
2013-12-07 03:58:46 -08:00
|
|
|
.It Pa ~/.ssh/id_ed25519
|
2019-11-18 15:16:49 -08:00
|
|
|
.It Pa ~/.ssh/id_ed25519_sk
|
2005-04-20 23:17:50 -07:00
|
|
|
.It Pa ~/.ssh/id_rsa
|
2024-06-17 01:30:29 -07:00
|
|
|
Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
|
2019-12-21 12:22:34 -08:00
|
|
|
authenticator-hosted Ed25519 or RSA authentication identity of the user.
|
2003-06-10 02:12:09 -07:00
|
|
|
.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.
|
2010-09-04 02:38:34 -07:00
|
|
|
.Sh EXIT STATUS
|
2002-01-29 08:41:19 -08:00
|
|
|
Exit status is 0 on success, 1 if the specified command fails,
|
|
|
|
and 2 if
|
|
|
|
.Nm
|
|
|
|
is unable to contact the authentication agent.
|
2003-06-10 02:12:09 -07:00
|
|
|
.Sh SEE ALSO
|
|
|
|
.Xr ssh 1 ,
|
|
|
|
.Xr ssh-agent 1 ,
|
2015-03-30 11:28:37 -07:00
|
|
|
.Xr ssh-askpass 1 ,
|
2003-06-10 02:12:09 -07:00
|
|
|
.Xr ssh-keygen 1 ,
|
|
|
|
.Xr sshd 8
|
2000-11-09 21:10:21 -08:00
|
|
|
.Sh AUTHORS
|
2001-01-28 02:24:04 -08:00
|
|
|
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.
|