diff options
Diffstat (limited to 'ssh-add.1')
| -rw-r--r-- | ssh-add.1 | 350 |
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. |