ssh-add.1 6.39 KB
Newer Older
1
.\"	$OpenBSD: ssh-add.1,v 1.59 2013/12/07 11:58:46 naddy Exp $
2 3 4 5 6
.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\"                    All rights reserved
.\"
7 8 9 10 11 12 13
.\" 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".
.\"
.\"
14 15 16
.\" 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.
17 18 19 20 21 22 23 24 25
.\"
.\" 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.
26
.\"
27 28 29 30 31 32 33 34 35 36
.\" 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.
37
.\"
38
.Dd $Mdocdate: December 7 2013 $
39 40 41 42
.Dt SSH-ADD 1
.Os
.Sh NAME
.Nm ssh-add
43
.Nd adds private key identities to the authentication agent
44 45
.Sh SYNOPSIS
.Nm ssh-add
46
.Op Fl cDdkLlXx
47
.Op Fl t Ar life
48
.Op Ar
49
.Nm ssh-add
50
.Fl s Ar pkcs11
51
.Nm ssh-add
52
.Fl e Ar pkcs11
53
.Sh DESCRIPTION
54
.Nm
55
adds private key identities to the authentication agent,
56
.Xr ssh-agent 1 .
57
When run without arguments, it adds the files
58
.Pa ~/.ssh/id_rsa ,
59
.Pa ~/.ssh/id_dsa ,
60 61
.Pa ~/.ssh/id_ecdsa ,
.Pa ~/.ssh/id_ed25519
62
and
63
.Pa ~/.ssh/identity .
64 65 66 67 68 69
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.
Damien Miller's avatar
Damien Miller committed
70
Alternative file names can be given on the command line.
71
.Pp
Damien Miller's avatar
Damien Miller committed
72
If any file requires a passphrase,
73
.Nm
74
asks for the passphrase from the user.
75
The passphrase is read from the user's tty.
76 77
.Nm
retries the last passphrase if multiple identity files are given.
78
.Pp
79 80 81
The authentication agent must be running and the
.Ev SSH_AUTH_SOCK
environment variable must contain the name of its socket for
82 83 84 85 86
.Nm
to work.
.Pp
The options are as follows:
.Bl -tag -width Ds
87 88
.It Fl c
Indicates that added identities should be subject to confirmation before
89 90
being used for authentication.
Confirmation is performed by the
91
.Ev SSH_ASKPASS
92 93
program mentioned below.
Successful confirmation is signaled by a zero exit status from the
94 95
.Ev SSH_ASKPASS
program, rather than text entered into the requester.
96 97 98
.It Fl D
Deletes all identities from the agent.
.It Fl d
99
Instead of adding identities, removes identities from the agent.
100 101
If
.Nm
102
has been run without arguments, the keys for the default identities and
103
their corresponding certificates will be removed.
104
Otherwise, the argument list will be interpreted as a list of paths to
105
public key files to specify keys and certificates to be removed from the agent.
106 107 108 109 110
If no public key is found at a given path,
.Nm
will append
.Pa .pub
and retry.
111
.It Fl e Ar pkcs11
112
Remove keys provided by the PKCS#11 shared library
113
.Ar pkcs11 .
114
.It Fl k
115 116
When loading keys into or deleting keys from the agent, process plain private
keys only and skip certificates.
117 118 119 120 121
.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.
122
.It Fl s Ar pkcs11
123
Add keys provided by the PKCS#11 shared library
124
.Ar pkcs11 .
125 126 127 128 129 130 131 132 133
.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.
134
.El
135 136 137
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev "DISPLAY" and "SSH_ASKPASS"
138 139 140
If
.Nm
needs a passphrase, it will read the passphrase from the current
Damien Miller's avatar
Damien Miller committed
141 142
terminal if it was run from a terminal.
If
143 144 145
.Nm
does not have a terminal associated with it but
.Ev DISPLAY
146 147 148 149
and
.Ev SSH_ASKPASS
are set, it will execute the program specified by
.Ev SSH_ASKPASS
Damien Miller's avatar
Damien Miller committed
150 151
and open an X11 window to read the passphrase.
This is particularly useful when calling
152 153
.Nm
from a
154
.Pa .xsession
Damien Miller's avatar
Damien Miller committed
155 156
or related script.
(Note that on some machines it
157 158 159
may be necessary to redirect the input from
.Pa /dev/null
to make this work.)
160
.It Ev SSH_AUTH_SOCK
161
Identifies the path of a
162 163
.Ux Ns -domain
socket used to communicate with the agent.
Damien Miller's avatar
Damien Miller committed
164
.El
165 166
.Sh FILES
.Bl -tag -width Ds
167
.It Pa ~/.ssh/identity
168
Contains the protocol version 1 RSA authentication identity of the user.
169
.It Pa ~/.ssh/id_dsa
170
Contains the protocol version 2 DSA authentication identity of the user.
171 172
.It Pa ~/.ssh/id_ecdsa
Contains the protocol version 2 ECDSA authentication identity of the user.
173 174
.It Pa ~/.ssh/id_ed25519
Contains the protocol version 2 ED25519 authentication identity of the user.
175
.It Pa ~/.ssh/id_rsa
176 177 178 179 180 181 182
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.
183
.Sh EXIT STATUS
184 185 186 187
Exit status is 0 on success, 1 if the specified command fails,
and 2 if
.Nm
is unable to contact the authentication agent.
188 189 190 191 192
.Sh SEE ALSO
.Xr ssh 1 ,
.Xr ssh-agent 1 ,
.Xr ssh-keygen 1 ,
.Xr sshd 8
193
.Sh AUTHORS
194 195 196 197 198 199 200 201
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.