19261079b7
Some notable changes, from upstream's release notes: - sshd(8): Remove support for obsolete "host/port" syntax. - ssh(1): When prompting whether to record a new host key, accept the key fingerprint as a synonym for "yes". - ssh-keygen(1): when acting as a CA and signing certificates with an RSA key, default to using the rsa-sha2-512 signature algorithm. - ssh(1), sshd(8), ssh-keygen(1): this release removes the "ssh-rsa" (RSA/SHA1) algorithm from those accepted for certificate signatures. - ssh-sk-helper(8): this is a new binary. It is used by the FIDO/U2F support to provide address-space isolation for token middleware libraries (including the internal one). - ssh(1): this release enables UpdateHostkeys by default subject to some conservative preconditions. - scp(1): this release changes the behaviour of remote to remote copies (e.g. "scp host-a:/path host-b:") to transfer through the local host by default. - scp(1): experimental support for transfers using the SFTP protocol as a replacement for the venerable SCP/RCP protocol that it has traditionally used. Additional integration work is needed to support FIDO/U2F in the base system. Deprecation Notice ------------------ OpenSSH will disable the ssh-rsa signature scheme by default in the next release. Reviewed by: imp MFC after: 1 month Relnotes: Yes Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D29985
263 lines
7.7 KiB
Groff
263 lines
7.7 KiB
Groff
.\" $OpenBSD: ssh-add.1,v 1.81 2020/07/14 23:57:01 djm 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: July 14 2020 $
|
|
.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 cDdKkLlqvXx
|
|
.Op Fl E Ar fingerprint_hash
|
|
.Op Fl S Ar provider
|
|
.Op Fl t Ar life
|
|
.Op Ar
|
|
.Nm ssh-add
|
|
.Fl s Ar pkcs11
|
|
.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_dsa ,
|
|
.Pa ~/.ssh/id_ecdsa ,
|
|
.Pa ~/.ssh/id_ecdsa_sk ,
|
|
.Pa ~/.ssh/id_ed25519 ,
|
|
and
|
|
.Pa ~/.ssh/id_ed25519_sk .
|
|
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
|
|
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 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 .
|
|
.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.
|