Debian Codegraph @

upstream/debian-unstable/man1/ssh-add.1

raw
1 .\" $OpenBSD: ssh-add.1,v 1.89 2026/03/05 05:44:15 djm Exp $
2 .\"
3 .\" Author: Tatu Ylonen <[email protected]>
4 .\" Copyright (c) 1995 Tatu Ylonen <[email protected]>, Espoo, Finland
5 .\" All rights reserved
6 .\"
7 .\" As far as I am concerned, the code I have written for this software
8 .\" can be used freely for any purpose. Any derived versions of this
9 .\" software must be clearly marked as such, and if the derived work is
10 .\" incompatible with the protocol description in the RFC file, it must be
11 .\" called by a name other than "ssh" or "Secure Shell".
12 .\"
13 .\"
14 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
15 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
16 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
17 .\"
18 .\" Redistribution and use in source and binary forms, with or without
19 .\" modification, are permitted provided that the following conditions
20 .\" are met:
21 .\" 1. Redistributions of source code must retain the above copyright
22 .\" notice, this list of conditions and the following disclaimer.
23 .\" 2. Redistributions in binary form must reproduce the above copyright
24 .\" notice, this list of conditions and the following disclaimer in the
25 .\" documentation and/or other materials provided with the distribution.
26 .\"
27 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .\"
38 .Dd $Mdocdate: March 5 2026 $
39 .Dt SSH-ADD 1
40 .Os
41 .Sh NAME
42 .Nm ssh-add
43 .Nd adds private key identities to the OpenSSH authentication agent
44 .Sh SYNOPSIS
45 .Nm ssh-add
46 .Op Fl CcDdKkLlNqvXx
47 .Op Fl E Ar fingerprint_hash
48 .Op Fl H Ar hostkey_file
49 .Op Fl h Ar destination_constraint
50 .Op Fl S Ar provider
51 .Op Fl t Ar life
52 .Op Ar
53 .Nm ssh-add
54 .Fl s Ar pkcs11
55 .Op Fl Cv
56 .Op Ar certificate ...
57 .Nm ssh-add
58 .Fl e Ar pkcs11
59 .Nm ssh-add
60 .Fl T
61 .Ar pubkey ...
62 .Nm ssh-add
63 .Fl Q
64 .Sh DESCRIPTION
65 .Nm
66 adds private key identities to the authentication agent,
67 .Xr ssh-agent 1 .
68 When run without arguments, it adds the files
69 .Pa ~/.ssh/id_rsa ,
70 .Pa ~/.ssh/id_ecdsa ,
71 .Pa ~/.ssh/id_ecdsa_sk ,
72 .Pa ~/.ssh/id_ed25519
73 and
74 .Pa ~/.ssh/id_ed25519_sk .
75 After loading a private key,
76 .Nm
77 will try to load corresponding certificate information from the
78 filename obtained by appending
79 .Pa -cert.pub
80 to the name of the private key file.
81 Alternative file names can be given on the command line.
82 .Pp
83 If any file requires a passphrase,
84 .Nm
85 asks for the passphrase from the user.
86 The passphrase is read from the user's tty.
87 .Nm
88 retries the last passphrase if multiple identity files are given.
89 .Pp
90 The authentication agent must be running and the
91 .Ev SSH_AUTH_SOCK
92 environment variable must contain the name of its socket for
93 .Nm
94 to work.
95 .Pp
96 The options are as follows:
97 .Bl -tag -width Ds
98 .It Fl C
99 When loading keys into or deleting keys from the agent, process
100 certificates only and skip plain keys.
101 .It Fl c
102 Indicates that added identities should be subject to confirmation before
103 being used for authentication.
104 Confirmation is performed by
105 .Xr ssh-askpass 1 .
106 Successful confirmation is signaled by a zero exit status from
107 .Xr ssh-askpass 1 ,
108 rather than text entered into the requester.
109 .It Fl D
110 Deletes all identities from the agent.
111 .It Fl d
112 Instead of adding identities, removes identities from the agent.
113 If
114 .Nm
115 has been run without arguments, the keys for the default identities and
116 their corresponding certificates will be removed.
117 Otherwise, the argument list will be interpreted as a list of paths to
118 public key files to specify keys and certificates to be removed from the agent.
119 If no public key is found at a given path,
120 .Nm
121 will append
122 .Pa .pub
123 and retry.
124 If the argument list consists of
125 .Dq -
126 then
127 .Nm
128 will read public keys to be removed from standard input.
129 .It Fl E Ar fingerprint_hash
130 Specifies the hash algorithm used when displaying key fingerprints.
131 Valid options are:
132 .Dq md5
133 and
134 .Dq sha256 .
135 The default is
136 .Dq sha256 .
137 .It Fl e Ar pkcs11
138 Remove keys provided by the PKCS#11 shared library
139 .Ar pkcs11 .
140 .It Fl H Ar hostkey_file
141 Specifies a known hosts file to look up hostkeys when using
142 destination-constrained keys via the
143 .Fl h
144 flag.
145 This option may be specified multiple times to allow multiple files to be
146 searched.
147 If no files are specified,
148 .Nm
149 will use the default
150 .Xr ssh_config 5
151 known hosts files:
152 .Pa ~/.ssh/known_hosts ,
153 .Pa ~/.ssh/known_hosts2 ,
154 .Pa /etc/ssh/ssh_known_hosts ,
155 and
156 .Pa /etc/ssh/ssh_known_hosts2 .
157 .It Fl h Ar destination_constraint
158 When adding keys, constrain them to be usable only through specific hosts or to
159 specific destinations.
160 .Pp
161 Destination constraints of the form
162 .Sq [user@]dest-hostname
163 permit use of the key only from the origin host (the one running
164 .Xr ssh-agent 1 )
165 to the listed destination host, with optional user name.
166 .Pp
167 Constraints of the form
168 .Sq src-hostname>[user@]dst-hostname
169 allow a key available on a forwarded
170 .Xr ssh-agent 1
171 to be used through a particular host (as specified by
172 .Sq src-hostname )
173 to authenticate to a further host,
174 specified by
175 .Sq dst-hostname .
176 .Pp
177 Multiple destination constraints may be added when loading keys.
178 When attempting authentication with a key that has destination constraints,
179 the whole connection path, including
180 .Xr ssh-agent 1
181 forwarding, is tested against those constraints and each
182 hop must be permitted for the attempt to succeed.
183 For example, if key is forwarded to a remote host,
184 .Sq host-b ,
185 and is attempting authentication to another host,
186 .Sq host-c ,
187 then the operation will be successful only if
188 .Sq host-b
189 was permitted from the origin host and the subsequent
190 .Sq host-b>host-c
191 hop is also permitted by destination constraints.
192 .Pp
193 Hosts are identified by their host keys, and are looked up from known hosts
194 files by
195 .Nm .
196 Wildcards patterns may be used for hostnames and certificate host
197 keys are supported.
198 By default, keys added by
199 .Nm
200 are not destination constrained.
201 .Pp
202 Destination constraints were added in OpenSSH release 8.9.
203 Support in both the remote SSH client and server is required when using
204 destination-constrained keys over a forwarded
205 .Xr ssh-agent 1
206 channel.
207 .Pp
208 It is also important to note that destination constraints can only be
209 enforced by
210 .Xr ssh-agent 1
211 when a key is used, or when it is forwarded by a
212 .Sy cooperating
213 .Xr ssh 1 .
214 Specifically, it does not prevent an attacker with access to a remote
215 .Ev SSH_AUTH_SOCK
216 from forwarding it again and using it on a different host (but only to
217 a permitted destination).
218 .It Fl K
219 Load resident keys from a FIDO authenticator.
220 .It Fl k
221 When loading keys into or deleting keys from the agent, process plain private
222 keys only and skip certificates.
223 .It Fl L
224 Lists public key parameters of all identities currently represented
225 by the agent.
226 .It Fl l
227 Lists fingerprints of all identities currently represented by the agent.
228 .It Fl N
229 When adding certificates, by default
230 .Nm
231 will request that the agent automatically delete the certificate shortly
232 after the certificate's expiry date.
233 This flag suppresses this behaviour and does not specify a lifetime for
234 certificates added to an agent.
235 .It Fl Q
236 Query the agent for the list of protocol extensions it supports.
237 Note: not all agents support this query.
238 .It Fl q
239 Be quiet after a successful operation.
240 .It Fl S Ar provider
241 Specifies a path to a library that will be used when adding
242 FIDO authenticator-hosted keys, overriding the default of using the
243 internal USB HID support.
244 .It Fl s Ar pkcs11
245 Add keys provided by the PKCS#11 shared library
246 .Ar pkcs11 .
247 Certificate files may optionally be listed as command-line arguments.
248 If these are present, then they will be loaded into the agent using any
249 corresponding private keys loaded from the PKCS#11 token.
250 .It Fl T Ar pubkey ...
251 Tests whether the private keys that correspond to the specified
252 .Ar pubkey
253 files are usable by performing sign and verify operations on each.
254 .It Fl t Ar life
255 Set a maximum lifetime when adding identities to an agent.
256 The lifetime may be specified in seconds or in a time format
257 specified in
258 .Xr sshd_config 5 .
259 .It Fl v
260 Verbose mode.
261 Causes
262 .Nm
263 to print debugging messages about its progress.
264 This is helpful in debugging problems.
265 Multiple
266 .Fl v
267 options increase the verbosity.
268 The maximum is 3.
269 .It Fl X
270 Unlock the agent.
271 .It Fl x
272 Lock the agent with a password.
273 .El
274 .Sh ENVIRONMENT
275 .Bl -tag -width Ds
276 .It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
277 If
278 .Nm
279 needs a passphrase, it will read the passphrase from the current
280 terminal if it was run from a terminal.
281 If
282 .Nm
283 does not have a terminal associated with it but
284 .Ev DISPLAY
285 and
286 .Ev SSH_ASKPASS
287 are set, it will execute the program specified by
288 .Ev SSH_ASKPASS
289 (by default
290 .Dq ssh-askpass )
291 and open an X11 window to read the passphrase.
292 This is particularly useful when calling
293 .Nm
294 from a
295 .Pa .xsession
296 or related script.
297 .Pp
298 .Ev SSH_ASKPASS_REQUIRE
299 allows further control over the use of an askpass program.
300 If this variable is set to
301 .Dq never
302 then
303 .Nm
304 will never attempt to use one.
305 If it is set to
306 .Dq prefer ,
307 then
308 .Nm
309 will prefer to use the askpass program instead of the TTY when requesting
310 passwords.
311 Finally, if the variable is set to
312 .Dq force ,
313 then the askpass program will be used for all passphrase input regardless
314 of whether
315 .Ev DISPLAY
316 is set.
317 .It Ev SSH_AUTH_SOCK
318 Identifies the path of a
319 .Ux Ns -domain
320 socket used to communicate with the agent.
321 .It Ev SSH_SK_PROVIDER
322 Specifies a path to a library that will be used when loading any
323 FIDO authenticator-hosted keys, overriding the default of using
324 the built-in USB HID support.
325 .El
326 .Sh FILES
327 .Bl -tag -width Ds -compact
328 .It Pa ~/.ssh/id_ecdsa
329 .It Pa ~/.ssh/id_ecdsa_sk
330 .It Pa ~/.ssh/id_ed25519
331 .It Pa ~/.ssh/id_ed25519_sk
332 .It Pa ~/.ssh/id_rsa
333 Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
334 authenticator-hosted Ed25519 or RSA authentication identity of the user.
335 .El
336 .Pp
337 Identity files should not be readable by anyone but the user.
338 Note that
339 .Nm
340 ignores identity files if they are accessible by others.
341 .Sh EXIT STATUS
342 Exit status is 0 on success, 1 if the specified command fails,
343 and 2 if
344 .Nm
345 is unable to contact the authentication agent.
346 .Sh SEE ALSO
347 .Xr ssh 1 ,
348 .Xr ssh-agent 1 ,
349 .Xr ssh-askpass 1 ,
350 .Xr ssh-keygen 1 ,
351 .Xr sshd 8
352 .Sh AUTHORS
353 OpenSSH is a derivative of the original and free
354 ssh 1.2.12 release by Tatu Ylonen.
355 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
356 Theo de Raadt and Dug Song
357 removed many bugs, re-added newer features and
358 created OpenSSH.
359 Markus Friedl contributed the support for SSH
360 protocol versions 1.5 and 2.0.