Adding upstream version 1:9.6p1.upstream/1%9.6p1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 350 insertions, 0 deletions

diff --git a/ssh-add.1 b/ssh-add.1
new file mode 100644
index 0000000..f0186cd
--- /dev/null
+++ b/ssh-add.1
@@ -0,0 +1,350 @@
+.\"	$OpenBSD: ssh-add.1,v 1.85 2023/12/18 14:46:56 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: December 18 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 vC
+.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
+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 C
+When loading keys into or deleting keys from the agent, process
+certificates only and skip plain keys.
+.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.