199 lines
6.2 KiB
Groff
199 lines
6.2 KiB
Groff
.\" $OpenBSD: ssh-add.1,v 1.56 2011/10/18 05:00:48 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: October 18 2011 $
|
|
.Dt SSH-ADD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ssh-add
|
|
.Nd adds private key identities to the authentication agent
|
|
.Sh SYNOPSIS
|
|
.Nm ssh-add
|
|
.Op Fl cDdkLlXx
|
|
.Op Fl t Ar life
|
|
.Op Ar
|
|
.Nm ssh-add
|
|
.Fl s Ar pkcs11
|
|
.Nm ssh-add
|
|
.Fl e Ar pkcs11
|
|
.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
|
|
and
|
|
.Pa ~/.ssh/identity .
|
|
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 the
|
|
.Ev SSH_ASKPASS
|
|
program mentioned below.
|
|
Successful confirmation is signaled by a zero exit status from the
|
|
.Ev SSH_ASKPASS
|
|
program, 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 will
|
|
be removed.
|
|
Otherwise, the argument list will be interpreted as a list of paths to
|
|
public key files and matching keys will be removed from the agent.
|
|
If no public key is found at a given path,
|
|
.Nm
|
|
will append
|
|
.Pa .pub
|
|
and retry.
|
|
.It Fl e Ar pkcs11
|
|
Remove keys provided by the PKCS#11 shared library
|
|
.Ar pkcs11 .
|
|
.It Fl k
|
|
When loading keys into the agent, load 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 s Ar pkcs11
|
|
Add keys provided by the PKCS#11 shared library
|
|
.Ar pkcs11 .
|
|
.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 X
|
|
Unlock the agent.
|
|
.It Fl x
|
|
Lock the agent with a password.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width Ds
|
|
.It Ev "DISPLAY" and "SSH_ASKPASS"
|
|
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
|
|
and open an X11 window to read the passphrase.
|
|
This is particularly useful when calling
|
|
.Nm
|
|
from a
|
|
.Pa .xsession
|
|
or related script.
|
|
(Note that on some machines it
|
|
may be necessary to redirect the input from
|
|
.Pa /dev/null
|
|
to make this work.)
|
|
.It Ev SSH_AUTH_SOCK
|
|
Identifies the path of a
|
|
.Ux Ns -domain
|
|
socket used to communicate with the agent.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width Ds
|
|
.It Pa ~/.ssh/identity
|
|
Contains the protocol version 1 RSA authentication identity of the user.
|
|
.It Pa ~/.ssh/id_dsa
|
|
Contains the protocol version 2 DSA authentication identity of the user.
|
|
.It Pa ~/.ssh/id_ecdsa
|
|
Contains the protocol version 2 ECDSA authentication identity of the user.
|
|
.It Pa ~/.ssh/id_rsa
|
|
Contains the protocol version 2 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-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.
|